tt status

Inspect every live Turbotunnel process running on this machine.

tt status [--format json]

tt status reports lifecycle state, relay health, traffic counters, and gateway reachability for Turbotunnel processes on this machine.

Unlike tt list, this command reads authenticated local control sockets. It does not depend on gateway presence events or show tunnels running on other machines.

Terminal output

The terminal view prints one block per tunnel:

Local tunnels

✓ Tunnel           ready
  Public           https://docs-turbotunnel.vercel.app/
  Local            http://localhost:5173
  Gateway          reachable
  Relays           2/2
  Uptime           12m

Field	Meaning
`Tunnel`	Current lifecycle state: starting, connecting, ready, or reconnecting.
`Public`	URL served by the configured gateway.
`Local`	Local HTTP target receiving forwarded requests.
`Gateway`	Whether the gateway returned valid JSON within three seconds.
`Relays`	Connected relay sockets compared with the configured pool size.
`Uptime`	Time since the process started, rounded down to seconds, minutes, or hours.

If no tunnel process is running, the command prints No local tunnels are running.

JSON output

Use JSON when another program needs the full lifecycle snapshot:

tt status --format json

The command writes a JSON array to stdout. Each item includes the terminal fields plus process and traffic counters:

[
  {
    "version": 1,
    "sessionId": "ses_example",
    "pid": 24817,
    "state": "ready",
    "startedAtMs": 1752667200000,
    "publicUrl": "https://docs-turbotunnel.vercel.app/",
    "localUrl": "http://localhost:5173",
    "gatewayStatusUrl": "https://docs-turbotunnel.vercel.app/_turbotunnel/status",
    "configuredRelays": 2,
    "connectedRelays": 2,
    "relayConnects": 2,
    "relayCloses": 0,
    "relayErrors": 0,
    "reconnects": 0,
    "framesReceived": 14,
    "framesSent": 14,
    "invalidFrames": 0,
    "httpRequests": 14,
    "httpResponses": 14,
    "webSocketsOpened": 1,
    "webSocketsClosed": 0,
    "uptimeSeconds": 720,
    "gateway": "running"
  }
]

The version field identifies the snapshot schema. The gateway field is "running", "unreachable", "rejected", or "invalid-response". Timeouts and network failures produce "unreachable"; non-200 responses produce "rejected"; malformed or oversized responses produce "invalid-response". These gateway results do not fail tt status.

Human output goes to stderr. JSON output goes to stdout without ANSI styling.

Local process discovery

Each tt http and tt dev process registers a private record under ~/.turbotunnel. It also listens on an authenticated local control socket.

Turbotunnel removes records whose processes have stopped. It preserves records for temporarily unavailable processes and fails instead of reporting that the tunnel stopped.

Use local status

Check whether a local tunnel reached ready before running an end-to-end test.
Diagnose a degraded relay pool or repeated reconnects.
Find the public and local URLs for tunnels started in other terminals.
Collect versioned process and traffic counters for local tooling.

Use tt list instead when you need gateway-reported tunnels across machines. Its results are bounded by presence-event delivery and leases.