Skip to content
TurbotunnelTurbotunnel
Esc
↑↓navigate↵open⌘Jpreview
On this page

Preview work from background agents

Give coding agents a stable public URL for apps in sandboxes and remote VMs.

Use Turbotunnel when an agent runs an app inside a sandbox, container, or remote workspace and a human needs to review it.

Decide whether Turbotunnel is the right ingress

Vercel Sandbox can already expose ports with ports and sandbox.domain(port). Prefer native Sandbox URLs for one-off previews inside that product.

Use Turbotunnel when you need:

  • Stable repository-defined hostnames
  • Generated password or IP access
  • The same preview workflow outside Vercel Sandbox
  • Gateway-wide discovery with tt list

Follow the agent preview flow

Run these steps in order:

  1. Deploy the gateway once outside the sandbox: tt deploy
  2. Inject ~/.turbotunnel/config.json as a protected secret with mode 0600
  3. Start the app and tunnel as long-lived processes in the same network namespace
  4. Default to generated password access
  5. Poll readiness with tt status --format json
  6. Return the public URL and password with the agent result
  7. Stop the sandbox when review ends

Bootstrap config and start the tunnel

Copy the gateway config into the sandbox home directory:

install -d -m 700 "$HOME/.turbotunnel"
install -m 600 /run/secrets/turbotunnel-config \
  "$HOME/.turbotunnel/config.json"

Start the app under the agent or sandbox supervisor, then keep the tunnel process alive:

npm run dev -- --host 127.0.0.1 --port 5173 &

tt http 5173 --host 127.0.0.1 --password --slug agent-pr-1842

When repository configuration and Vercel authentication are available in the environment:

tt dev dashboard --password -- pnpm --filter dashboard dev

A preloaded gateway config lets tt http <port> run without an interactive Vercel login. A discovered turbotunnel.json project triggers domain reconciliation and needs an authenticated Vercel CLI session.

Check readiness and discover tunnels

Tunnel commands stay in the foreground while healthy. For automation, poll local state:

tt status --format json

tt status reports exact process state only within the same machine and home directory. For gateway-wide discovery:

tt list --format json

tt list is bounded by Queue delivery and a 30s presence lease. It can briefly omit or retain sessions.

Protect agent previews

Treat agent-built apps as untrusted until you review them:

  • Prefer generated --password; avoid putting passwords in process arguments or logs when you can
  • Do not commit, bake into images, or print ~/.turbotunnel/config.json; it contains the relay secret
  • Override the default public access with password access for agent-built apps
  • Allow HTTPS and WebSocket egress to the gateway domain in the sandbox firewall
  • Expect the tunnel to stop when you stop or suspend the sandbox, even if the filesystem persists

Respect agent environment limits

These limits shape how you run tunnels from agents:

  • The public URL lives only while tt and its host environment stay running
  • Turbotunnel does not daemonize, discover ports, inject environment variables, or extend sandbox lifetime
  • HTTP requests time out after 30s; request and response bodies are limited to 4 MiB
  • One process owns a public host; a second claim is a route conflict, not load balancing
  • localhost means local to the tt process; an app on another machine is not reachable through sandbox localhost

Was this page helpful?