Tunnels

A tunnel is the live connection from the CLI to the relay. It attaches your alias to whatever port is running on your machine.

A tunnel is the WebSocket connection between the fixedhook CLI on your machine and the FixedHook relay. It is the live "wire" that the alias forwards traffic through.

A tunnel is ephemeral — it lives only as long as the CLI process. The alias it attaches to is permanent. This is the core separation that makes FixedHook work.

How a tunnel works

1. The CLI opens a WebSocket connection to the relay and authenticates.
2. The CLI says "I am the active session for alias my-app-dev."
3. The relay marks the alias as online.
4. When a request hits my-app-dev.fixedhook.com, the relay streams the request bytes through the open WebSocket.
5. The CLI writes the request to http://127.0.0.1:<port> and streams the response back.
6. The relay records the event in the database and forwards the response to the original caller.

The whole round trip is one network hop (CLI → relay), so latency overhead is small — typically under 50 ms in normal conditions.

Online vs. offline

A tunnel is online as long as the CLI keeps the WebSocket alive. The CLI sends a ping every 10 seconds. The relay considers a session offline if it has not pinged in the last 40 seconds (2× the ping interval). This means:

• A graceful CLI shutdown (Ctrl+C) updates the dashboard to offline within a second.
• A crashed CLI process or a network drop shows as offline within 40 seconds.
• Reconnecting (e.g. after a sleep/wake cycle) shows as online within a second of the new connection.

The online status is what the dashboard uses to show the green dot next to an alias.

What happens when the tunnel is offline

Incoming requests do not disappear. The relay:

1. Accepts the request.
2. Returns 503 to the caller immediately with a Retry-After header.
3. Records the event with status queued.
4. When a tunnel comes back online, the event is not automatically replayed — that is a manual action.

The reasoning is that an event might have been queued for hours, and the original payload might no longer be relevant. Replay should be a deliberate choice, not an automatic consequence of coming back online.

One tunnel per alias

At any moment, at most one tunnel can be attached to an alias. Starting a new tunnel for an alias you already own replaces the old session. The relay does not load-balance across multiple sessions; that is intentional.

This is the right behavior for development. If two teammates run tunnels on the same alias at once, they will steal each other's traffic. The solution is to give each person their own alias (e.g. alice-app-dev, bob-app-dev) or to use separate aliases for shared previews.

Tunnel authentication

Tunnels authenticate with the CLI key associated with your account. The key is created when you run fixedhook login and stored in the OS keychain. It is never sent in plaintext over the WebSocket — the handshake is signed with HMAC.

If you suspect a key leak, revoke it from Dashboard → Settings → CLI keys. Revoking a key invalidates all active sessions for that key.

Tunnel performance

Tunnels are not designed for high-throughput production traffic. The current limits:

• Up to ~50 requests per second per tunnel.
• Up to 5 MB per request body (request and response).
• A few hundred concurrent in-flight requests.

For production-scale traffic, point the alias at a real server (a long-lived process you control) rather than a local tunnel. The architecture is the same; the difference is who runs the listener.