Private Tunnels

Protect a single tunnel

Pass a passcode when you start the tunnel. It applies to that tunnel only and is discarded when the tunnel closes, which makes it a good fit for a one-off demo link.

portbuddy --passcode my-secret 3000

The short form is -pc. Passcodes apply to HTTP tunnels only — TCP and UDP tunnels carry no HTTP layer to challenge the visitor on.

Protect a domain

A passcode set on a domain persists across restarts and applies to every tunnel served from it. Set one in the Domains section of the dashboard, and remove it there when the tunnel should go public. Domain passcodes must be at least four characters long.

Domain passcodes work with your own custom domains as well as generated subdomains.

What visitors see

A request to a protected tunnel is redirected to a passcode page naming the domain being opened. Once the visitor enters the correct passcode they are forwarded to the tunnel, and a cookie keeps them signed in to that tunnel for 12 hours.

Scripts and API clients can skip the page by sending the passcode themselves, either as a query parameter or as a request header:

curl "https://otter-4821.portbuddy.dev/?passcode=my-secret"
curl -H "X-API-Key: my-secret" https://otter-4821.portbuddy.dev/

What a passcode is and is not

A passcode is one shared secret for everyone who has the link. It keeps a demo, a staging build or a webhook endpoint from being opened by whoever finds the URL — it is not per-user authentication, and it does not replace your application’s own login.

• Changing the passcode ends existing sessions: the cookie is checked against the current passcode on every request, so everyone is challenged again.
• Removing it takes effect immediately, and the tunnel is public again from the next request.
• A tunnel-level passcode disappears with the tunnel; a domain-level one outlives it, which is the safer default for anything long-lived.