Skip to content

Quick Start

Create your first Localport tunnel and reach your local app from the internet in about two minutes. Dashboard walkthrough for web apps, APIs, and databases.

Summary

Your local service gets a public HTTPS address in about two minutes. Create a tunnel in the dashboard, copy the command it hands you, and run it. Nothing to deploy, and nothing to change on your router.

What you need before you start#

You need an account, the agent, and something listening on a port. The first two take under a minute each.

1. A Localport account. Sign in or create one at dashboard.localport.io. This is where tunnels are created and where you copy the command to run.

2. The Localport agent. A single binary with no dependencies. Install it for your operating system:

brew install localport/tap/localport

See Installation for manual downloads, checksum verification, and building from source. Confirm it worked with localport version.

On Windows, open a new terminal first

The installer adds itself to your user PATH, and an already-open PowerShell window will not see it until you start a new one.

3. Something running locally. Any program listening on a TCP port will do. If you do not have one to hand, start a throwaway server on port 3000:

# Python (already present on macOS and most Linux systems)
python3 -m http.server 3000

# or Node.js
npx serve -p 3000

Step 1: Create a tunnel in the dashboard#

Open dashboard.localport.io, go to Tunnels, and click Create tunnel. Give the tunnel a name, pick a region, and create it.

Create a tunnel in the dashboard, then copy the ready-to-run command.

There are only two fields to decide.

  • Name is a label for you. Change it whenever you like. It is not part of the public address.
  • Region is where your tunnel is served from: EU, US, or Asia Pacific. Pick the one closest to whoever will be connecting. Your traffic stays in that region.

The tunnel and its address are yours to keep

The tunnel, its name, region, settings, and public address are saved to your account. The address does not change between sessions, so you can stop and restart as often as you like and keep sharing the same link.

Step 2: Copy your connect command#

After you create a tunnel the dashboard moves to the Connect step and builds the exact command to run. You can reopen it any time with the Connect button on the tunnel.

  • Preset. Fills in the protocol and port for a known tool (Next.js, Vite, Django, PostgreSQL, Minecraft), or choose Custom.
  • Protocol. http for web apps and APIs, tcp for databases, game servers, and SSH, tls for services that terminate TLS themselves.
  • Local Address. Where to forward traffic. Defaults to localhost. Set something like 192.168.1.50:5432 to reach a different machine on your network.
  • Name. Optional label for this connection, sent as --name. Required for fleet devices, where it becomes the device's own address.
  • Run without the live UI. Swaps the live panel for plain log lines (--noui). Use it under systemd, Docker, or CI. The agent also switches to plain logs on its own when nothing is attached to a terminal.
  • Log HTTP requests. Adds --log-requests, writing one line per request. Available on HTTP tunnels with the live UI off.
  • Token. The tunnel's credential, already filled into the command. Treat it like a password.

The finished command looks like this:

localport http 3000 --token tok_k8f2 --region eu

Keep the token off shared command lines

On a machine other people use, a token typed as an argument shows up in a process list. Set LOCALPORT_TOKEN, or point LOCALPORT_TOKEN_FILE at a file only your user can read.

Every command and flag is in the CLI reference.

Step 3: Run the tunnel#

Paste the command into your terminal and press Enter. The agent connects and the terminal becomes a live status panel.

Run the command and the tunnel connects, with live traffic in the status panel.

The panel reports everything at a glance:

  • Forwarding is your public address. This is the link you share.
  • Local is the address on your machine that traffic is delivered to.
  • Region confirms which region you connected through.
  • Bandwidth and Connections update live, with a per-connection breakdown of origin IP, duration, and bytes in and out.

Leave the command running. The address is live for as long as it runs.

Step 4: Open your public address#

Copy the Forwarding address and put it to work:

  • Open it in a browser, or on your phone over mobile data to check it on a real device on a real network.
  • Send it to a colleague or a client to show work in progress.
  • Paste it into a webhook setting for Stripe, GitHub, Slack, or Twilio.
https://example-service.eu.localport.dev

HTTPS is served with a publicly trusted certificate. No warning to click through, nothing to install, and webhook senders and mobile apps accept it with no special configuration.

Before you share the address widely#

Anyone holding that address can reach the service you just connected. For a demo you are watching, that is fine.

Before it goes anywhere more permanent, put a control in front of it. Basic Auth puts a password prompt in the way. IP Allowlists narrow it to addresses you approve, and Header Authentication to clients sending a header you chose. If the caller is a webhook sender, Webhook Verification checks the signature instead. For named machines and people, there is Remote Access.

Each is a per-tunnel setting in the dashboard, and each takes effect on a running tunnel.

Stop and restart the tunnel#

Press Ctrl+C. The session ends and the address stops answering: an HTTP address returns a 404 saying the tunnel was not found, and a TCP address refuses the connection.

Nothing is deleted. The tunnel, its token, its address, and every setting stay in your account. Run the same command again and the same address serves traffic again. To keep a tunnel up without a terminal window, add --noui and run it under systemd, launchd, or Docker, as covered in Installation.

Frequently asked questions#

Do I need to install anything on the machine I am exposing?

Only the Localport agent, and only on a machine that can reach your service over the network. The service itself needs no changes, no library, and no Localport-specific code.

Is my tunnel address public?

By default, yes. Anyone who has the address can reach your service while the agent is running. The address is not guessable, and it is not a secret either. Add Basic Auth, an IP allowlist, Header Authentication, or Remote Access to change that, all without restarting.

Does my tunnel address stay the same between restarts?

Yes. The address belongs to the tunnel and not to the session, so it survives restarts, reboots, and network changes. You can also set your own subdomain in the tunnel's settings, which is the one to use for webhook endpoints and OAuth callback URLs already registered somewhere else. A custom subdomain is 12 characters or more.

Does Localport work behind a firewall, NAT, or CGNAT?

Yes. The agent makes an outbound connection to Localport, the same kind a browser makes. There is no port to forward and no inbound firewall rule to add. It works on home routers, corporate networks, mobile hotspots, and carrier-grade NAT where you have no public address.

Can I expose a database or game server instead of a web app?

Yes. Use a tcp tunnel for anything that is not HTTP, including PostgreSQL, MySQL, Redis, MQTT, SSH, and game servers such as Minecraft. See TCP Tunnels and the game server guide.

Where do I find my token, and what happens if it leaks?

The token is on the tunnel's page in the dashboard, behind the Connect button. It authenticates that one tunnel, so treat it like a password: keep it out of screenshots, shared terminals, and committed files. If it does leak, rotate it on the tunnel's settings page. Connections already running are unaffected, and the next connection has to present the new token. Instead of putting it on the command line, where other users of the machine can read it in a process list, set LOCALPORT_TOKEN or point LOCALPORT_TOKEN_FILE at a file only your user can read.

Why am I seeing a 404 instead of my app?

A 404 saying the tunnel was not found means Localport has the address but no agent is currently connected to it. Check that the command is still running and that it did not exit with an error. If the agent is running and you still see it, copy the address from the Forwarding line instead of typing it from memory.

How do I run more than one tunnel at once?

List them in a YAML file and start them together with localport --config localport.yaml. That is also the tidiest way to run a web app, a database, and a homelab service side by side. See Configuration for the format and worked examples.

Can I run a tunnel without keeping a terminal open?

Yes. Add --noui so the agent writes plain log lines instead of the live panel, then run it as a service. The repository ships a hardened systemd unit and a launchd daemon that keep the token out of the process list and restart the agent automatically. See Installation.

Can I use my own domain instead of the localport.dev address?

Yes. Add the domain in the dashboard, create one CNAME record at your DNS provider, and attach it to the tunnel. Localport obtains and renews the certificate for it. See Custom Domains.

  • HTTP Tunnels. Share a web app, test webhooks, demo to a client.
  • TCP Tunnels. Expose databases, game servers, and SSH.
  • Fleets. Give every device in a fleet its own address.
  • Fanout Tunnels. Send one webhook to your whole team at once.
  • Remote Access. Put a service behind a client certificate with a fleet.
  • CLI. Every flag, option, and exit code.
Previous Installation Next CLI