> ## 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 Live Browser: Cloud-Hosted Devtools for AI Agents

> A cloud-hosted browser for AI agents: Sightmap-enriched snapshots, network inspection, device emulation, and full interaction support in Subtext Verify.

The Subtext Live Browser is a cloud-hosted Chromium instance your agent opens, navigates, and drives — no local browser setup required. It gives agents an interactive surface for testing UI flows, verifying fixes against a running app, checking responsive behavior across device profiles, and inspecting the network and console output produced by real page loads. Every snapshot the Live Browser returns is enriched by your Sightmap, so agents see semantic component names and source paths rather than raw DOM selectors.

## Sightmap enrichment

When you have a `.sightmap/` directory in your project, `live-connect` returns a `sightmap_upload_url`. The Subtext plugin pushes your local Sightmap files to that URL before the first snapshot is taken. From that point on, every snapshot includes five additional properties per matched element: **semantic component name**, **source file path**, **visibility**, **interactivity**, and **bounding box**. Memory entries attached to components appear in a `[Guide]` block at the top of the snapshot, giving your agent immediate contextual understanding without having to read source files.

## Capabilities

<CardGroup cols={2}>
  <Card title="Connection & Navigation" icon="plug">
    Open a connection with `live-connect`, navigate to any URL with `live-view-navigate`, manage multiple views with `live-view-list`, `live-view-select`, `live-view-new`, and `live-view-close`, and resize the viewport with `live-view-resize`. Close everything cleanly with `live-disconnect`.
  </Card>

  <Card title="Interaction" icon="cursor-arrow-rays">
    Drive the page with `live-act-click` (by component UID), `live-act-hover`, `live-act-fill` (single input or batch), `live-act-drag` (pixel offset), `live-act-upload` (file input), `live-act-keypress` (with optional focus target), and `live-act-dialog` (accept or dismiss). Gate interactions on state with `live-act-wait-for`.
  </Card>

  <Card title="Inspection" icon="magnifying-glass">
    Capture a component-tree snapshot with `live-view-snapshot` (element UIDs, no image), take a visual screenshot with `live-view-screenshot` (optionally clipped to an element), and retrieve CSS selectors, attributes, and classes per component with `live-view-inspect`.
  </Card>

  <Card title="Network & Console" icon="satellite-dish">
    List all captured network requests for a view with `live-net-list` and fetch full request details by index with `live-net-get`. List console messages with `live-log-list` and retrieve a single message with `live-log-get`.
  </Card>

  <Card title="Device Emulation" icon="mobile-screen">
    Apply a device profile — viewport dimensions plus user agent string — with `live-emulate`. Use this to verify responsive layouts and mobile-specific behavior without leaving the hosted browser session.
  </Card>

  <Card title="Scripting" icon="code">
    Evaluate arbitrary JavaScript in the page context with `live-eval-script`. Use this to read application state, trigger events programmatically, or probe values that aren't exposed through the component tree.
  </Card>
</CardGroup>

## Reaching localhost

<Warning>
  The cloud-hosted browser cannot reach your machine directly. If your dev server runs on `localhost`, you must set up the Subtext Tunnel before navigating to it. See [Tunnel](/docs/verify/tunnel) for full setup instructions.
</Warning>

The tunnel is a lightweight local MCP server — separate from the main Subtext session-review server — that creates a reverse tunnel from the hosted browser to your dev server. Add it to your MCP config alongside your existing Subtext entry:

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

Once the tunnel is running, call `live-tunnel` to allocate a connection and get the relay URL, then use that URL instead of `localhost` when navigating in the live browser.

## Getting started

<Steps>
  <Step title="Connect">
    Call `live-connect` with a starting URL. The tool returns a connection ID and, if you have a Sightmap configured, a `sightmap_upload_url` — the plugin uploads your `.sightmap/` files automatically before the first snapshot.

    ```
    live-connect({ url: "https://your-app.example.com" })
    ```
  </Step>

  <Step title="Navigate or interact">
    Use `live-view-navigate` to move to a specific route, or jump straight into interaction with `live-act-click`, `live-act-fill`, and the rest of the `live-act-*` tools. Use `live-act-wait-for` to block until a selector is visible or the page reaches a load state before proceeding.
  </Step>

  <Step title="Capture a snapshot or screenshot">
    Call `live-view-snapshot` for a Sightmap-enriched component tree (fast, no image data), or `live-view-screenshot` for a visual capture. Use `live-view-inspect` to pull CSS selectors and attributes for specific components when you need to verify styling details.
  </Step>

  <Step title="Inspect network and console output">
    Call `live-net-list` to see all requests the page made, then `live-net-get` on any index for full request and response details. Call `live-log-list` to surface console messages — errors, warnings, and custom log output — that the page emitted during the session.
  </Step>

  <Step title="Disconnect">
    Call `live-disconnect` when you're done. This closes the hosted browser and frees all associated resources. Always disconnect at the end of a session — open connections count against your quota.

    ```
    live-disconnect()
    ```
  </Step>
</Steps>

<Note>
  To capture structured, versioned evidence of what the Live Browser found — before/after screenshots, diffs, and logs attached to a permanent record — pair the Live Browser with [Proof Docs](/docs/verify/proof-docs).
</Note>