Agent Browser

The Agent Browser tile lets you watch an agent drive a real browser inside your workspace. Use it when your agent needs to navigate a web app, fill out a form, click through a flow, or take screenshots — you’ll see exactly what it’s doing in a live viewport instead of guessing from logs.

Agents open this tile when they start a browser session; it isn’t in the tile picker.

Two modes

When your agent opens a browser session, it picks one of two modes:

Headless — the browser runs in the background. Nothing shows up in your workspace. Best for CI-style runs.
Tile — same browser, plus a live tile in your workspace that mirrors the page. The tile opens as a 2×2 pane in the first free spot on your main desktop; you can move and resize it.

Your agent picks at create time. Both modes work identically for the agent — the tile is just for you.

What you’ll see

Open the workspace. When the agent opens a browser tile, a new pane appears with a state pill in the header:

connecting → the stream is opening
paused → connected but the agent hasn’t started broadcasting yet
live → frames flowing
disconnected → reconnect attempts exhausted; click retry
error → the session couldn’t start; the pill names why (for example MISSING_CONFIG), with retry

While the tile is live:

The camera icon in the header captures a full-resolution PNG and opens it in a new tab. Use this for bug reports or doc captures — the live stream is JPEG-compressed for bandwidth, and the camera goes around that.
The hand icon lets you take control of the browser yourself (Take manual control of the browser); the header shows you are in control until you give it back.
The gear icon chooses how the stream is delivered — auto (recommended), webrtc or mjpeg — for the whole workspace. Leave it on auto unless the stream misbehaves.
The transcript panel at the bottom expands to show the last 20 commands the agent has run, with status and duration. Raw selectors, URLs, and expressions are hidden by design.

Troubleshooting

Stuck at paused — the agent hasn’t started the screencast or the browser crashed. Check the agent’s transcript.
Stuck at connecting — confirm the workspace is running and you own it.
Stream is choppy or drops to 6 fps — the tile reduces frame rate under load and restores once it eases. Close unused browser tiles or refresh the page if it stays slow.
Disconnected with no recovery — the session has closed. Have the agent open a fresh one.

Limits and controls

One tab per session, up to four sessions per workspace.
Chromium only; Firefox and WebKit aren’t supported.
The Take control button in the tile header lets you click and type into the page yourself; while you hold control the agent’s commands are refused. Click it again to give control back.
Cookies and logins clear when the session closes unless the agent saves them first with studio.browser_save_state and reapplies them with studio.browser_restore_state (internal-tier tools, origin-scoped).

Network

The live viewport uses WebRTC for video. Strict corporate firewalls that block UDP can prevent WebRTC, in which case the tile automatically falls back to a JPEG-over-WebSocket stream within a few seconds — the tile keeps working, just on the legacy path. No configuration needed on your side.

Testing your preview tiles from an agent

Agent-browser runs in the same container as your Preview tiles. To verify your dev server end-to-end, your agent navigates the browser directly to http://localhost:<port> — no proxy, no auth token, no public URL needed.

studio.list_tiles returns a pre-composed preview.url for every preview tile that the agent can pass straight to studio.browser_navigate:


{
  "tiles": [
    {
      "id": "preview-...",
      "type": "preview",
      "preview": {
        "port": 3000,
        "path": "/",
        "status": "ready",
        "url": "http://localhost:3000/"
      }
    }
  ]
}

Wait until preview.status === "ready" before navigating. Earlier states (starting, waiting, unconfigured) mean the dev server hasn’t bound its port yet and the navigate will return ERR_CONNECTION_REFUSED.

For testing against an externally-hosted preview (Cloudflare Workers, Pages, staging services), see Remote Previews. Those don’t get a usable preview.url; navigate the agent browser straight to the public HTTPS URL instead.

Opening a browser tile requires a URL

When you open a browser in tile mode (studio.browser_create with renderMode: "tile", or any “create me a browser tile” intent), you must pass initialUrl. A tile is a passive viewer the operator watches — with no URL it lands on about:blank and renders blank (the MISSING_CONFIG state). studio.browser_create rejects a tile-mode call with no initialUrl so you fix it immediately instead of stranding a dead tile.

Where to get the URL:

Dev server is a preview tile → use its preview.url from studio.list_tiles (above), or just call studio.browser_attach_to_preview with the preview tile’s id (it waits for ready and resolves the URL for you).
Dev server runs in another tile (e.g. a coding-agent or terminal tile running npm run dev) → list_tiles won’t carry a preview.url for it. Resolve the listening port first (studio.inspect_port, or read it from the agent/terminal that started the server), then pass initialUrl: "http://localhost:<port>". Don’t spawn the tile blind and hope.
Headless mode (renderMode: "headless", the default) is exempt — you drive it programmatically and studio.browser_navigate later. initialUrl is optional there.