Agent Browser

See what your agent sees.

Self-hosted Chrome for AI agents.
Your agent drives one real browser session — and you can watch it happen, and step in.

Quickstart · API · MCP · Security model · Node client · Python client · Contributing · Changelog

_{An 18-second recorded demonstration. The agent signs in, reaches a 2FA prompt it has no way to answer, and stops. A human types the code into the displayed session, then the agent continues.
Capture provenance, checksums, and independently verifiable limits are documented.  ·  How this was recorded}

Why this exists

Most browser tooling for agents hands the model a browser you cannot see. When it misreads a page or stalls on a login, all you get is a transcript and a guess.

Agent Browser runs one headed Chrome session. Your agent drives it through a small JSON API, and a live view of that same session sits open in front of you. When the agent gets stuck, you take over in the window it is already using — then hand it back.

Start the runtime:

docker compose up --build

Then reach it however you like:

npm install aether-browser    # TypeScript
pip install aether-browser    # Python
claude mcp add agent-browser -- npx -y aether-browser mcp    # any MCP client

Quickstart

One command, on Docker Engine for Linux with Compose v2. It builds from the source checkout and starts Xvfb, x11vnc, noVNC, and the API — the stack that owns a single headed Chrome session. Both user-facing listeners bind to numeric loopback.

docker compose up --build

Once health responds, open the live view at 127.0.0.1:6080/vnc.html and check the API from another terminal:

curl -fsS http://127.0.0.1:8092/browser/health | jq .

Ctrl+C stops it.

The first build takes several minutes. It installs the hash-locked Python environment, then uses Patchright to install the current Google Chrome Stable package. The exact browser version is captured with each accepted image, so rebuilding the same source later may pick up a newer Stable.

Linux host networking is deliberate. It keeps the unauthenticated v0.x noVNC surface on numeric loopback. Docker Desktop and remote-host deployment are outside this quickstart.

The API in four calls

With the runtime healthy and curl plus jq installed. Local loopback needs no bearer token by design — read the authority contract before you change the deployment shape.

# Open the session. This is the browser you are about to watch.
SESSION_ID="$(curl -fsS -X POST http://127.0.0.1:8092/browser/session/create \
  -H 'Content-Type: application/json' \
  -d '{"api_version":"v1"}' | jq -er '.session_id')"

# Go somewhere. The page changes in the live view as this runs.
curl -fsS -X POST http://127.0.0.1:8092/browser/navigate \
  -H 'Content-Type: application/json' \
  -d "{\"api_version\":\"v1\",\"session_id\":\"${SESSION_ID}\",\"url\":\"https://example.com\"}" \
  | jq '{status, final_url, title, readable_text}'

# Read it back as structure, not pixels.
curl -fsS -X POST http://127.0.0.1:8092/browser/snapshot \
  -H 'Content-Type: application/json' \
  -d "{\"api_version\":\"v1\",\"session_id\":\"${SESSION_ID}\"}" \
  | jq '{status, url, title, sequence, vision_steps_remaining}'

# Give the browser back.
curl -fsS -X POST http://127.0.0.1:8092/browser/session/end \
  -H 'Content-Type: application/json' \
  -d "{\"api_version\":\"v1\",\"session_id\":\"${SESSION_ID}\"}" | jq .

What that did: session/create started one headed Chrome session and returned its UUID plus the local view URL. navigate validated the destination, pinned the allowed addresses, and changed the page on the shared display. snapshot returned bounded text, accessibility state, viewport metadata, counters, and a PNG of that same page. At no point did the API and the human view create competing browsers — they met at one owned session.

The same flow ships as examples/curl.sh.

Use it from an MCP client

Any MCP client — Claude Code, Claude Desktop, Cursor, Windsurf — can drive the session while you watch, and take over when it gets stuck.

claude mcp add agent-browser -- npx -y aether-browser mcp

Already have the Python client? aether-browser mcp serves the same nine tools.

{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": ["-y", "aether-browser", "mcp"]
    }
  }
}

Nine tools — browser_open · browser_navigate · browser_read · browser_click · browser_type · browser_press · browser_scroll · browser_status · browser_close

browser_open hands back the live view URL, and every response after it repeats that URL, so you always know where to look. On connect, the server tells the model to stop and ask for a takeover at a login, a payment, or a 2FA prompt rather than guessing — the loop in the recording above.

Setup and limits: docs/MCP.md.

Node and TypeScript client

The same API from Node, with types and cleanup you cannot forget:

npm install aether-browser

import { AgentBrowser, withSession } from 'aether-browser'

const browser = new AgentBrowser({ controllerToken: process.env.AGENT_BROWSER_CONTROLLER_TOKEN })

await withSession(browser, async (session) => {
  const page = await session.navigate('https://example.com')
  await session.click({ selector: '#login' })
  await session.type({ selector: '#user', text: 'ada' })
  console.log(page.title, session.viewUrl)
})

withSession always ends the session, including when your callback throws, so a crash cannot leave the single slot occupied. No runtime dependencies, and it runs anywhere that can reach the server. It carries a small CLI too: npx aether-browser doctor tells you what is missing before a first run, and up builds and starts the runtime on a Linux host.

See clients/node/README.md.

Python client

The same client, same name, same commands, released version for version with the npm package:

pip install aether-browser

import os

from aether_browser import AgentBrowser, session

browser = AgentBrowser(controller_token=os.environ["AGENT_BROWSER_CONTROLLER_TOKEN"])

with session(browser) as live:
    page = live.navigate("https://example.com")
    live.click(selector="#login")
    live.type("ada", selector="#user")
    print(page["title"], live.view_url)

The session context manager always ends the session, including when the body raises. No runtime dependencies — the transport is urllib from the standard library — ships type hints, and runs on Python 3.10 or newer, anywhere that can reach the server. Same CLI as the npm package: aether-browser doctor, up, status, open, down.

See clients/python/README.md.

What makes it different

• One session, two participants. The agent acts through JSON. You watch the same display, and take the controls whenever you want them.
• Structure before pixels. Readable text and a bounded accessibility tree come back before you spend a vision step on a screenshot.
• A small control surface. The v0.x API exposes explicit browser actions — not a shell, not arbitrary JavaScript, not raw DevTools.
• Model-agnostic and self-hosted. Bring the framework you already use, and keep the browser on hardware you control.

What it does today