Password-protect a tunnel

You want to put a password in front of a tunnel — typically because you're sharing a preview build with a client, or exposing a staging service that should not be world-readable.

JustTunnel ships basic-auth gating directly into the CLI via the --password flag. The password lives only on the edge; your local server never sees the auth header. You'll need an authenticated CLI (justtunnel auth) and any local web server to point the tunnel at.

Steps

1. Pick a password

The password must be 4 to 128 characters. Anything outside that range is rejected before the tunnel is opened.

For a one-off share with a client, a short, memorable password is fine. For anything sensitive, generate a long random one and pipe it in:

PASSWORD=$(openssl rand -base64 24)
echo "Share this password: $PASSWORD"

2. Open the tunnel with --password

justtunnel 3000 --password 'staging-only'

Or with the generated password from step 1:

justtunnel 3000 --password "$PASSWORD"

The CLI prints the public URL just like a normal tunnel:

Forwarding  https://wandering-otter-42.justtunnel.dev → http://localhost:3000

3. Hit the URL in a browser

Visitors see a basic-auth prompt before any request reaches your local server:

• Username: anything (the CLI accepts any value)
• Password: the value you passed to --password

Once the visitor submits a correct password, the browser caches the credentials for the rest of the session and traffic flows normally.

Verify

From a separate machine or an incognito window, hit the tunnel without credentials:

curl -I https://wandering-otter-42.justtunnel.dev

HTTP/2 401
www-authenticate: Basic realm="JustTunnel"

Now retry with the password (basic auth uses an arbitrary username):

curl -I -u 'preview:staging-only' https://wandering-otter-42.justtunnel.dev

HTTP/2 200

If the unauthenticated request returns 200, the password did not stick — re-check that you passed --password to the same tunnel you're hitting.

Common issues

• Password too short or too long. The CLI rejects anything outside 4 to 128 characters with password must be between 4 and 128 characters. Pick a value in range.
• Special characters from your shell. Wrap the password in single quotes ('...') so your shell does not interpret $, !, or backticks.
• Using a config file. The password field in tunnels.yaml follows the same 4 to 128 rule. See Use a tunnels.yaml config file.

Related

• justtunnel [port] — the root command and full flag list.
• Password protection — how the gate works at the edge.
• Use a tunnels.yaml config file — set passwords per tunnel in YAML.