Disconnects and reconnects
What happens when a tunnel loses its WebSocket connection, how the reconnect-token mechanism keeps your URL stable, and which CLI versions support it.
JustTunnel tunnels run over a single long-lived WebSocket between the CLI and the edge. Networks aren't perfect, so disconnects happen — laptop sleeps, Wi-Fi roams, server restarts. The CLI is built to recover automatically.
What you see when it happens
When the WebSocket drops, the CLI logs the disconnect and starts trying to reconnect with backoff. If you're running with the TUI you'll see the tunnel switch into a reconnecting state with an attempt counter:
[api:8080] reconnecting attempt 3The CLI keeps trying up to --max-reconnect-attempts (default 50; set to 0 for unlimited) before giving up. Once it reconnects, the tunnel goes back to running.
In-flight requests at the moment the connection drops are lost — the caller will see a 502 or a network error from the edge. This is the price of doing TCP over a single WebSocket; clients are expected to retry.
Reconnect tokens — keeping the same URL
The first time a tunnel connects, the server issues a reconnect token along with the assigned subdomain (in the tunnel_assigned frame). The CLI keeps this token in memory. When the connection drops and the CLI dials again, it sends the token back, and the server reuses the previous subdomain so your tunnel URL stays stable across the reconnect.
Without a reconnect token (or with an invalid one), the server allocates a new random subdomain. Your URL changes, any callers holding the old URL get a 404 or routing failure, and reserved-subdomain holders fall back to a fresh random name.
Reconnect tokens are valid for 24 hours after issue. A CLI that has been disconnected for longer than that loses its reserved subdomain on the next reconnect and is treated as a fresh client.
Reconnect token v2 and the version cutoff
The reconnect-token mechanism was upgraded to v2 in CLI v0.2.3 (PR #23). The new format includes the issue timestamp, which lets the server enforce the 24-hour validity window cleanly.
As of CLI v0.2.3, reconnect tokens persist across reconnects with a server-enforced expiry; older versions reconnect from scratch and may lose their assigned subdomain.
If you're running an older CLI (v0.2.2 or earlier), upgrade — older clients still work, but every reconnect risks a new subdomain.
go install github.com/justtunnel/justtunnel-cli@latest
justtunnel --versionWhen reconnects fail
A few things can break the reconnect loop:
--max-reconnect-attemptsexhausted. The CLI gives up. Re-run the command.- Server returned 401 on reconnect. Your API key was rotated or revoked. Run
justtunnel authto mint a new one. - Server returned 403 on reconnect. Your account or team was suspended, or the requested subdomain is no longer available to you. See Common errors → server returned 403.
- Token expired (>24h offline). The CLI gets a fresh subdomain. If you had a reserved subdomain, request it explicitly (
--subdomain mything) on the next run.
Tuning the reconnect behavior
Two flags affect reconnects:
| Flag | Default | When to change it |
|---|---|---|
--max-reconnect-attempts | 50 | Set to 0 for a worker tunnel that should keep trying forever, or a small number for short-lived demo tunnels. |
--local-timeout | 30s | Doesn't affect reconnect, but raise it if your local handler is slow — otherwise you'll see 504s while reconnects are working fine. |
You can also set max_reconnect_attempts in ~/.justtunnel/config.yaml. The flag takes precedence.
Worker tunnels and reconnects
Worker tunnels (Pro/Team) are designed to reconnect indefinitely — they're meant to outlive transient network issues without manual intervention. The supervisor (launchd / systemd) restarts the CLI process if it exits, and inside that process the reconnect loop handles every drop short of process death.
See Worker won't start if a worker isn't recovering on its own.
Still stuck?
If reconnects keep failing or your tunnel URL keeps changing across reconnects on a recent CLI, open an issue with your CLI version (justtunnel --version) and a snippet of the disconnect logs.