# Tunnel Devices

URL: https://docs.testvibe.com/account-settings/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](/assets/images/settings-devices-792359a68553c6c5d78e91d7e30eaee2.png)

## 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](/account-settings/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:

```bash
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:**

```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:**

```bash
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.

## Related Help

- [API keys](/account-settings/api-keys)
- [Configure environments and App Repository](/workspace/configure-site-url-and-repository)
- [Run failed](/troubleshooting/run-failed)