// docs

SSH tunnel documentation: expose localhost

tunnl.gg is a reverse tunneling service that exposes local servers to the public internet. It works with the SSH client you already have, so there is nothing to install, and the basic command needs no account.

The command

ssh -t -R 80:localhost:8080 proxy.tunnl.gg
  • -t allocates a terminal so the server can show you your public URL and a QR code to open it on your phone. It is required.
  • -R 80:localhost:8080 is remote port forwarding. It tells the SSH server to forward traffic from its port 80 to your localhost:8080. The syntax is [remote_port]:[local_host]:[local_port]; change the last number to the port your app listens on.
  • proxy.tunnl.gg is the hostname of the tunnl.gg SSH server.

The server replies with a URL such as https://happy-tiger-a1b2c3d4.tunnl.gg. Anyone with that URL reaches your local app over HTTPS for as long as the SSH session stays open.

The SSH client ships with macOS, Linux and Windows 10 or later, so the same command works in Terminal, PowerShell and most CI runners.

Verify the host key

The first time you connect, SSH asks you to confirm the server's host key. proxy.tunnl.gg has a single ED25519 host key, with this fingerprint:

SHA256:5uQ6VobmUpY4wyMmm5jnAwFtt3aX06WYDDM4ER+2WUw

If SSH shows this fingerprint, answer yes. If it shows a different one, don't connect, and open an issue.

To trust the key without the question, for example on a CI runner or a service, add this line to ~/.ssh/known_hosts:

proxy.tunnl.gg ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIN3HFkIcqgWI6Sa1E31KiUbcfcrX/5MZl4LnaQnUYL8K

The key is also published as a DNSSEC-signed SSHFP record, so SSH can check it against DNS for you:

ssh -t -o VerifyHostKeyDNS=yes -R 80:localhost:8080 proxy.tunnl.gg

If your resolver validates DNSSEC, SSH accepts the key without asking. Otherwise it still asks, and the question includes "Matching host key fingerprint found in DNS".

Keep the same URL

By default each connection gets a new random URL. Add stable@ to get the same URL every time you connect, tied to your SSH key:

ssh -t -R 80:localhost:8080 stable@proxy.tunnl.gg

The key must be registered to a free account (new keys now, keys already in use from December 1, 2026): run ssh -t link@proxy.tunnl.gg, open the link it prints and sign in with your email. It takes about 30 seconds, and your URL stays the same. See Stable URLs for how it works, choosing a key, and keeping a tunnel running.

Free request inspector and replay

Explore the request inspector to see an example and its capture limits.

Sign in to the dashboard using the email login link, then add your SSH key: run ssh -t link@proxy.tunnl.gg and open the link it prints. You can also paste the public key under SSH keys and sign a code with it. Your private key stays on your computer.

Connect with the verified key using:

ssh -t -R 80:localhost:3000 pro@proxy.tunnl.gg

The pro@ username connects your account, including free accounts; no subscription is required. Open Inspector in the dashboard to view requests and responses or replay a request to your local app. If you have several keys, select the verified key with -i.

Each tunnel keeps its latest 50 requests in memory until it closes, with up to 32 KiB of each request and response body and a 1 MiB total body budget. Older bodies can be dropped. Incomplete requests cannot be replayed. Replaying sends the request again and can repeat actions in your app.

Free accounts still have three simultaneous tunnels, a two-hour idle timeout, a 24-hour maximum duration and the browser warning page. stable@ and random tunnels do not record requests for the dashboard inspector.

Choose your own name (Pro)

With Pro, reserve names like myapp in the dashboard and connect as pro@:

ssh -t -R myapp:80:localhost:8080 pro@proxy.tunnl.gg

Pro tunnels have no time limits and no warning page, and can add passwords, IP allowlists and CORS. See Using Pro.

Common examples

Expose a React or Vite app:

ssh -t -R 80:localhost:5173 proxy.tunnl.gg

Expose a Next.js app:

ssh -t -R 80:localhost:3000 proxy.tunnl.gg

Expose a Python Flask app:

ssh -t -R 80:localhost:5000 proxy.tunnl.gg

Dev servers such as Vite, Next.js, webpack, Rails and Django reject unknown hostnames by default. If you see "Blocked request", "Invalid Host header" or "Blocked host", follow Share a local dev server.

Scripts and AI agents

Add output=json after the host and the session prints JSON lines instead of the banner: the URL first, then one line per request. Scripts, CI jobs and AI coding agents like Claude Code can read them without parsing terminal output. It works on every tunnel, free ones included:

ssh -n -T -R 80:localhost:3000 stable@proxy.tunnl.gg output=json

See Use tunnl.gg from AI coding agents for running it in the background, reading the URL, and instructions to paste into AGENTS.md or CLAUDE.md.

The browser warning page

The first time someone opens your URL in a browser, tunnl.gg shows a warning page that tells them the site runs on someone's computer. It protects visitors from phishing, and it is shown once a day per site, or once a week for stable URLs. Pro tunnels don't show it.

Only browsers see it. Requests from webhooks, curl, SDKs and other non-browser clients go straight to your app. To skip it from a browser-like client, send the tunnl-skip-browser-warning header with any value:

curl -H "tunnl-skip-browser-warning: 1" https://happy-tiger-a1b2c3d4.tunnl.gg

Limits

LimitValue
Tunnels per IP3 at once
Requests per visitor25/s, bursts up to 200 (per visitor IP, per tunnel)
Requests per tunnel50/s, bursts up to 400 (across all visitors)
Request and response body64 MB each
Daily transfer5 GB per IP, resetting at 00:00 UTC; stable URLs count against both the IP and the SSH key
Proxied request idle timeout2 minutes without data
WebSocket transfer1 GB per direction, per connection
WebSocket idle timeout2 hours
WebSockets100 per tunnel, 20 per visitor IP
New SSH connections10 per minute per IP
Inactivity timeout2 hours with no requests or open WebSockets
Tunnel lifetime24 hours at most

Requests over a limit get HTTP 429. Repeated abuse leads to a temporary 1-hour IP block.

The server README explains how each limit works. On Pro, tunnels have no inactivity timeout or lifetime limit, you can have 10 open at once (10 per seat on Team), and they may transfer 10 GB a day (10 GB per seat on Team). Transfer counts request and response bodies and WebSocket data, both ways; past the limit, visitors get HTTP 429 until 00:00 UTC.

Troubleshooting

Connection refused?

Make sure your local server is actually running on the port you specified (for example 8080). You can check by visiting localhost:8080 in your browser. If your server only listens on 127.0.0.1 or ::1, use that address in the command instead of localhost.

How long does the tunnel last?

The tunnel stays open as long as your SSH connection is active, up to 24 hours, and closes after 2 hours without any requests. If you close the terminal or lose your internet connection, the tunnel closes. To reconnect automatically, see Keep a tunnel running. Each new connection gets a new random URL, unless you connect as stable@ to keep the same URL.

I don't see a URL after connecting

Add -t to the command. Without a terminal, the server can't print the URL.

stable@ says "Permission denied (publickey)"

Stable URLs need an SSH key registered to a free account (new keys now, all keys from December 1, 2026). Create one with ssh-keygen -t ed25519, register it, and connect again. If you have several keys, pick one with -i as described in Stable URLs.

Last updated