Skip to main content

Tunnel Devices

Devices are machines in your network running the tvtunnel agent. With a device connected, cloud runs can test apps that are not reachable from the public internet — the app URL stays unchanged and traffic between the run and your network is end-to-end encrypted.

The Tunnels settings panel

Connect A Device​

  1. Select Settings from the navigation rail, then Tunnels under Workspace.
  2. Get an API key to use as the token from Settings → CLI & API keys — see API keys.
  3. On a machine inside your network (Node 20+), run the one command shown in the panel. The same line works on macOS, Linux, and Windows — no download step:
npx --yes testvibe-tunnel@latest --token <your-api-key> --relay <relay-url> --server <your-testvibe-url>

The panel fills in the actual token, relay, and server for you — copy the command shown there rather than retyping it.

  1. The device appears in the list automatically when the agent connects with one of your API keys.

No npm registry access? (self-hosted / air-gapped)​

If the machine can't reach the public npm registry, download this server's agent bundle to a temp directory and run it from that local file:

Windows PowerShell:

$t = Join-Path $env:TEMP 'tvtunnel.tgz'; iwr <agent-tarball-url> -OutFile $t; npx --yes $t --token <your-api-key> --relay <relay-url> --server <your-testvibe-url>

macOS / Linux:

curl -fsSL <agent-tarball-url> -o /tmp/tvtunnel.tgz && npx --yes /tmp/tvtunnel.tgz --token <your-api-key> --relay <relay-url> --server <your-testvibe-url>

The panel fills in the actual tarball URL, token, relay, and server. Self-hosted installs should prefer this tarball — it ships the agent version matched to your server, so the panel leads with it and offers the npm one-liner as the secondary option.

How Runs Use Devices​

  • A project's tunneled runs use the project's pinned device, falling back to the Default device.
  • If no device is connected, runs against private URLs fail to reach the target — the public-URL path is unaffected.
  • Keep the agent running as a service on a stable machine; a laptop that sleeps will take your tunnel down mid-run.
  • If an agent is running an older protocol than the server supports, its runs fail honestly with a message to rerun npx --yes testvibe-tunnel@latest …. Update the agent by rerunning the connect command above.