> ## Documentation Index
> Fetch the complete documentation index at: https://subtext.fullstory.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Subtext Tunnel: Connect the Hosted Browser to Localhost

> Subtext Tunnel creates a reverse tunnel between the cloud-hosted browser and your local dev server so your agent can test against localhost.

The Subtext hosted browser runs in the cloud — which means it can't reach your `localhost` dev server directly. The tunnel solves this: a separate local MCP server (`subtext-tunnel`) runs on your machine, bridges the hosted browser to your local server, and hands your agent a relay URL it can pass to `live-connect`.

<Warning>
  Tunnel is part of the Verify beta. It is available to the closed beta cohort and may change before general availability.
</Warning>

## How the tunnel works

When you start a tunnel, `subtext-tunnel` opens a reverse connection from your machine to Subtext's relay infrastructure. The hosted browser then reaches your local dev server through that relay — no firewall changes, no public IP required. Your agent calls `tunnel-connect` from the local side and `live-tunnel` from the hosted browser side to get the relay URL.

<Note>
  `subtext-tunnel` is a **separate** MCP server from the main Subtext MCP. It runs entirely on your local machine. Add it as a second entry in your MCP config — do not replace your existing Subtext entry with it.
</Note>

## Add `subtext-tunnel` to your MCP config

Add the following entry alongside your existing Subtext MCP server configuration:

```json theme={null}
{
  "mcpServers": {
    "subtext-tunnel": {
      "command": "npx",
      "args": ["-y", "@subtextdev/subtext-cli@latest"]
    }
  }
}
```

Your MCP config will have two entries when both are present: one for the main `subtext` server and one for `subtext-tunnel`.

## Tunnel tools

| Tool                | Description                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `tunnel-connect`    | Connect a reverse tunnel so the hosted browser can reach localhost. Pass in your local server URL. |
| `tunnel-disconnect` | Disconnect a specific tunnel, or all active tunnels.                                               |
| `tunnel-status`     | Report the status of all active tunnels.                                                           |
| `live-tunnel`       | Allocate a connection on the hosted browser side and return the tunnel relay URL.                  |

## Connect your agent to localhost

<Steps>
  <Step title="Add subtext-tunnel to your MCP config">
    Add the `subtext-tunnel` entry shown above to your MCP configuration file. Restart your agent or MCP host to pick up the new server.
  </Step>

  <Step title="Start your local dev server">
    Run your development server as usual — for example, `npm run dev` on port 3000. Confirm it is reachable at `http://localhost:3000` before proceeding.
  </Step>

  <Step title="Open a tunnel from the local side">
    Ask your agent to call `tunnel-connect` with your local server URL:

    ```
    tunnel-connect http://localhost:3000
    ```

    This establishes the reverse connection from your machine to the relay.
  </Step>

  <Step title="Get the relay URL on the hosted browser side">
    Ask your agent to call `live-tunnel` on the hosted browser side. It returns the relay URL that the cloud browser can reach.
  </Step>

  <Step title="Open your app in the hosted browser">
    Pass the relay URL to `live-connect`. The hosted browser navigates to your local app through the tunnel, and your agent can interact with it just like any other live session.
  </Step>
</Steps>