> Call the `diagnose` tool first. Full index: /llms.txt. Errors: /reference/problems.

# Test an app on localhost

TaloTrace's browser runs in the cloud. A tunnel from your laptop carries the page, and any API it calls, to that browser. The app keeps its `localhost` address in the browser, in your code and in the run. Never rewrite a URL or add a host name for TaloTrace.

## Through your coding agent

Start your dev server, then ask your agent to verify. The MCP server opens the tunnel itself when `start_run` has a plain-HTTP loopback start page such as `http://localhost:3000`:

* It waits up to 15 seconds for the tunnel and otherwise answers `LOCAL_TARGET_NOT_CONNECTED` with the port.
* A second run on the same port reuses the tunnel.
* The tunnel closes after the idle time you set with `mcp --idle`, and when the agent exits.

## A page and its API on two ports

When the page calls an API on another local port, list both. Port 3000 is the page and 3001 is the API:

```bash
talotrace connect 3000 3001
```

Through the agent, pass the extra ports in the target of `start_run` (`"ports": [3001]`), or start the server with `mcp --ports 3001`. At most eight ports go in one session. Without the API's port the API calls fail.

## Intercept mode

A local web run keeps your `localhost` address as its entry URL. Requests to it travel through your tunnel to your laptop. Register OAuth callbacks for `localhost` exactly as you do when you run the app locally.

## From the command line

```bash
talotrace connect 3000       # serve the page until you press Ctrl-C
talotrace doctor --ports 3000
talotrace run <scenario id>  # starts a run; it does not say whether it passed
```

For a CI job use `talotrace check`, which owns its tunnel. See [exit codes](/reference/cli/exit-codes).

## Who owns a tunnel

A tunnel is visible only to the sign-in that opened it. An API key and a browser sign-in cannot share one. If a run is refused with `LOCAL_TARGET_NOT_CONNECTED`, use the same credential for both. See [Sign in](/sign-in).

You can hold up to five sessions at once. Ctrl-C ends a session within two seconds.