# Documentation - Getting Started

> Start using Pinggy in three simple steps. Host websites, receive webhooks, share files, and connect to your localhost remotely with ease.
> Source: https://pinggy.io/docs/


# Pinggy - Quickstart

Pinggy is the easiest way to get public URLs for your localhost. You can use it to quickly host a website from your laptop, receive webhooks, share files, connect to your Raspberry Pi, and more.

Follow the three simple steps to get started:

#### Step 1: Run your service in localhost

First you need to run the service you want to share in localhost. For example you may be using a webserver like <a href="https://httpd.apache.org" target="_blank">Apache</a>. Make sure your service is available in a localhost URL such as <a href="http://localhost:8080" target="_blank">http://localhost:8080</a>.

You can quickly launch such a server for testing purposes using Python: `python3 -m http.server` .
This will start a server at <a href="http://localhost:8000" target="_blank">http://localhost:8000</a>.

#### Step 2: Create a tunnel using a single command


#### SSH

<p>Open your terminal / command prompt and run the following to create a tunnel using SSH:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ssh -p <span class="m">443</span> -R0:localhost:8000 free.pinggy.io
</span></span></code></pre></div><p>Replace the port <code>8000</code> with the localhost port where your service is running.</p>
<p>If you are prompted for a password, just press enter.</p>
<p><img src="/assets/ssh_tui_screenshot.png" alt="SSH Tunnel Screenshot"></p>


#### CLI

<p>Download the Pinggy CLI from <a href="/cli/" target="_blank">here</a> and run the following command:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">./pinggy -p <span class="m">443</span> -R0:localhost:8000
</span></span></code></pre></div><p>Replace the port <code>8000</code> with the localhost port where your service is running.</p>
<p><img src="/assets/cli_tui.png" alt="CLI Tunnel Screenshot"></p>


#### App

<p>Download the Pinggy App from <a href="/app/" target="_blank">here</a> and follow the instructions to set up a tunnel for your localhost service.</p>
<p><img src="/assets/app5.webp" alt="Pinggy App Screenshot"></p>


#### Node.js SDK

<p>Install the <a target="_blank" href="https://pinggy-io.github.io/sdk-nodejs/">Pinggy Node.js SDK</a> using <code>npm</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">npm i @pinggy/pinggy
</span></span></code></pre></div><br/>
<p>Then, create a tunnel in your Node.js application:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-js" data-lang="js"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">pinggy</span> <span class="p">}</span> <span class="nx">from</span> <span class="s2">&#34;@pinggy/pinggy&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">tunnel</span> <span class="o">=</span> <span class="kr">await</span> <span class="nx">pinggy</span><span class="p">.</span><span class="nx">createTunnel</span><span class="p">({</span> <span class="nx">forwarding</span><span class="o">:</span> <span class="s2">&#34;localhost:3000&#34;</span> <span class="p">});</span>
</span></span><span class="line"><span class="cl"><span class="kr">await</span> <span class="nx">tunnel</span><span class="p">.</span><span class="nx">start</span><span class="p">();</span>
</span></span><span class="line"><span class="cl"><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s2">&#34;Tunnel URLs:&#34;</span><span class="p">,</span> <span class="kr">await</span> <span class="nx">tunnel</span><span class="p">.</span><span class="nx">urls</span><span class="p">());</span> <span class="c1">// Get all public urls
</span></span></span></code></pre></div><p>Replace <code>3000</code> with the port where your service is running.</p>
<p>Follow <a target="_blank" href="https://pinggy-io.github.io/sdk-nodejs/">Pinggy Node.js SDK docs</a> for more details.</p>


#### Python SDK

<p>Install the <a target="_blank" href="https://pypi.org/project/pinggy/">Python SDK</a> using <code>pip</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pip install pinggy
</span></span></code></pre></div><br/>
<p>Then, create a tunnel in your Python application:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">pinggy</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Start an HTTP tunnel forwarding traffic to localhost on port 8000</span>
</span></span><span class="line"><span class="cl"><span class="n">tunnel</span> <span class="o">=</span> <span class="n">pinggy</span><span class="o">.</span><span class="n">start_tunnel</span><span class="p">(</span><span class="n">forwardto</span><span class="o">=</span><span class="s2">&#34;localhost:8000&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;Tunnel started. Urls: </span><span class="si">{</span><span class="n">tunnel</span><span class="o">.</span><span class="n">urls</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span></code></pre></div><p>Replace <code>8000</code> with the port where your service is running.</p>
<p>Follow <a target="_blank" href="https://pypi.org/project/pinggy/">Python SDK docs</a> for more details.</p>




#### Step 3: Access through public URL

The above step will provide you http and https URLs as follows:

```
// You can access local server via following URL(s):
http://uljtt-30-47-152-61.run.pinggy-free.link
https://uljtt-30-47-152-61.run.pinggy-free.link
```

You can access your localhost service using these URLs.

With Pinggy Pro you can customize these urls by logging in to  <a href="https://dashboard.pinggy.io" target="_blank">dashboard.pinggy.io</a>.

#### Using Pinggy with an AI agent

Install the Pinggy **skill**:

```bash
npx skills add https://pinggy.io
```

Describe what you need in plain language, for example:

```
Share my dev server on port 3000 using Pinggy.
```

See the <a href="/docs/ai_agents/">Use Pinggy with AI Agents</a> guide for the full tool reference and more example prompts.

#### Quickstart Recipes

View our <a href="/quickstart/" target="_blank"><button type="button" class="btn btn-dark">Quickstart Recipes</button></a> to find the Pinggy configuration for your favourite app / service.

