agent-browser
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agent-browser open my bank portal — I'll take over for the 2FA, then read my balance"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 --buildThen 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 clientRelated MCP server: monkeysee
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 --buildOnce 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 mcpAlready 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-browserimport { 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.
Python client
The same client, same name, same commands, released version for version with the npm package:
pip install aether-browserimport 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.
Optional Jev web decisions (Python)
The Python client has an opt-in aether_browser.jev layer for Jev → your selected model.
Jev reads a caller-selected text excerpt and chooses between up to three caller-approved URLs,
handoff, or human takeover. The browser navigates only to a URL the caller supplied, and its
normal destination checks still apply. On handoff, your callback receives the current page
evidence and Jev's request IDs, token counts, and costs; your application invokes its chosen
reasoning model to write, analyze, or continue browsing. Jev returns decisions, not prose or
visual judgments, so screenshots and complex page interactions belong to that selected model or
the human watching the live browser.
import os
from aether_browser import AgentBrowser, session
from aether_browser.jev import HumanTakeover, JevWebAgent, NavigationOption, OpenRouterJev
browser = AgentBrowser(controller_token=os.environ["AGENT_BROWSER_CONTROLLER_TOKEN"])
with session(browser) as live:
first_page = live.navigate("https://example.com")
result = JevWebAgent(OpenRouterJev(os.environ["OPENROUTER_API_KEY"])).run(
live,
goal="Read the site's documentation",
initial_page=first_page,
options_for=lambda page: (
[NavigationOption("https://example.com/docs", "Official documentation")]
if page["final_url"] == "https://example.com/"
else []
),
excerpt_for=lambda page: page["readable_text"][:6000],
selected_model=lambda handoff: your_model(handoff), # Supply your own model callback.
)
if isinstance(result, HumanTakeover):
print("Take control at", result.view_url)
input("Press Enter when the human is done to close this session: ")
else:
print(result)The example's your_model is an application-defined function, not part of this package. The
excerpt_for callback explicitly chooses text sent to OpenRouter, and options_for explicitly
chooses candidate URLs. Never return private page content or signed URLs unless your application
intends to send them to that provider. The OpenRouter key stays in the calling process; the
browser server does not store it. No Jev request occurs unless you call this optional layer.
If Jev fails or returns an invalid decision, the selected-model callback receives a handoff
with reason="jev_unavailable" and the browser takes no additional action. Recognized authentication
or payment pages prompt human takeover before Jev receives their text. The session remains owned
by your code; keep it open while the human takes over. See docs/JEV.md for
the complete contract and limitations.
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
Capability | v0.x contract |
Browser | One headed Google Chrome Stable session launched through Patchright |
State | URL, title, readable text, bounded accessibility nodes, viewport, and PNG snapshot |
Actions | Navigate, click, type, scroll, and allowlisted key presses |
Human view | The same Xvfb display through loopback-only x11vnc and noVNC |
Ownership | One explicit UUID session with expiry, vision budget, and idempotent cleanup |
Authority | Observer/controller separation when authenticated; strict local loopback mode otherwise |
MCP | Nine stdio tools from either client ( |
Navigation | HTTP(S)-only validation across requested, redirected, and browser-initiated navigation |
Request and response shapes, limits, and stable error codes: docs/API.md.
Architecture
flowchart LR
Agent["Agent client"] -->|bounded JSON API| API["FastAPI"]
API --> Guard["authority + navigation policy"]
Guard --> Session["single-session manager"]
Session --> Chrome["Patchright + headed Google Chrome"]
Chrome --> State["text · accessibility · PNG"]
State --> Agent
Chrome --> Display["shared Xvfb display"]
Display -->|loopback noVNC| Human["Human observer / takeover"]The session manager owns the page, browser context, temporary profile, timers, counters, and
cleanup. The API and the live view are different interfaces to that shared resource, not two
independent automation paths. See docs/ARCHITECTURE.md.
Agent Browser v0.2.3 is source-first and self-hosted. It is not a hosted service, and the v0.x noVNC surface is unauthenticated and meant for numeric loopback on a machine you control. No Chrome-containing image, image tar, or public layer cache is distributed unless separate redistribution authorization is documented.
Security boundary
API and noVNC listen on numeric loopback by default; noVNC remains loopback-only in the v0.x line.
Remote API clients require a separately operated same-host HTTPS reverse proxy, an exact trusted loopback peer, strict Host validation, and distinct strong observer/controller tokens.
Destination validation rejects credentials, unsupported schemes, blocked address classes, unsafe redirects, and DNS rebinding. Browser egress is pinned through an owned TCP proxy.
Non-proxied WebRTC UDP is disabled so it cannot silently bypass the TCP egress boundary.
Inputs, outputs, interactions, timeouts, lifetimes, and screenshot budgets are bounded.
Cleanup converges on session end, expiry, launch failure, application shutdown, and process failure.
Trust assumptions and residual risks are spelled out in docs/SECURITY.md.
Report vulnerabilities privately through SECURITY.md — please do not open a public
security issue.
Source recovery and exclusions
The source-recovery rule is reuse general browser behavior, not private domain code.
Lifecycle, structured-state, interaction, and cleanup patterns may be adapted from authorized
references; ATS/trading integrations, broker or account selectors, order actions, secrets,
and credential injection are excluded from the public core. Provenance status is tracked in
docs/SOURCE-RECOVERY.md.
What it does not do
No hosted cloud service, cloud control plane, or production remote-hosting claim.
No bundled LLM or default model calls, account system, dashboard, credential vault, or credential injection.
No CAPTCHA bypass, anti-detection guarantee, stealth claim, or proxy rotation.
No arbitrary JavaScript, shell, filesystem, upload, clipboard, download, or raw CDP API.
No multi-session pool, ATS integration, trading integration, or brokerage behavior.
Roadmap
Shipped. Both clients and their CLI are published as aether-browser, version for version,
on npm from clients/node and
on PyPI from clients/python. Since
0.2.0 both also serve the MCP server.
Two tracks are open, each with an issue, and each is a good first contribution:
Multi-session worker pool — explicit isolation and capacity semantics.
Session trace and recording export — with clear privacy controls.
These are candidates, not shipped features.
Contributing
Start with CONTRIBUTING.md, the
Code of Conduct, and the current API contract. Small,
well-tested changes that keep the authority boundary narrow are very welcome — the two roadmap
issues above are the best place to start. Security reports go through the private process in
SECURITY.md, never a public issue.
License and third-party notices
Aether-owned source code is licensed under the Apache License 2.0. Google Chrome is
separately licensed under Google's Chrome terms and is not
covered by Aether's Apache license; dependencies, system packages, fonts, and web assets also
remain under their respective terms. See THIRD_PARTY_NOTICES.md.
Aether is not affiliated with or endorsed by Google. The v0.x distribution target is source that
builds locally; this repository does not distribute a prebuilt Chrome-containing image.
Available Tools
9 toolsbrowser_clickB
Click a CSS selector, or an x/y point in the viewport. Provide one, not both.
Inputs: x, y, selector.
browser_closeA
End the session and release the browser. Idempotent. Call this when the task is finished so the single session slot is free.
Inputs: no named parameters.
browser_openA
Start the one headed Chrome session and return the live view URL. Give that URL to the human: they can watch this exact session, and take over in it, while you drive. Safe to call twice — it reuses the session that is already open.
Inputs: no named parameters.
browser_pressC
Press one allowlisted key or combination. Allowed: Enter, Escape, Tab, Backspace, Delete, Space, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, Control+A, Control+Z, Control+Shift+Z, Meta+A, Meta+Z, Meta+Shift+Z.
Inputs: key (required).
browser_readA
Read the current page: title, URL, readable text and a bounded accessibility tree. Prefer this over a screenshot — it is structure, not pixels, and it does not spend a vision step unless you ask for the image.
Inputs: include_screenshot.
browser_scrollC
Scroll the page by a nonzero pixel delta.
Inputs: delta_x, delta_y.
browser_statusA
Report whether the runtime is up, whether a session is open, how many vision steps remain, and the live view URL to hand to a human.
Inputs: no named parameters.
browser_typeA
Type text into a CSS selector, or at an x/y point. Text is sent byte for byte. Do not use this for a secret a human should enter — ask them to take over in the live view instead.
Inputs: text (required), x, y, selector.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a distinct purpose, but browser_open and browser_navigate could be confused since both initiate a session and navigate to a URL. The descriptions clarify the difference (open creates/reuses session, navigate goes to URL), but an agent might still misfire.
All tool names follow a consistent snake_case verb_noun pattern with the 'browser_' prefix. This is predictable and readable.
Nine tools is well-scoped for a browser automation server, covering essential actions like open, navigate, read, click, type, press, scroll, status, and close. No obvious bloat or missing core operations.
The surface covers the full browser lifecycle and common interactions (open, navigate, read, click, type, press, scroll, status, close). Minor gaps include no explicit wait or screenshot tool (though read can return an image), and no form submission or download handling, but these are workaroundable.
Maintenance
Related MCP Connectors
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Browz hosted MCP (free public beta): let an AI app drive your own Browz browser profiles from anywhere. Connect https://mcp.gobrowz.com/mcp and sign in with your Browz account (OAuth) or an agent token. Each call is relayed to the Browz app on your computer, which must be online with Remote control on and have a hardware security chip (Mac Secure Enclave or TPM 2.0). 17 tools: profiles, tabs, navigate, snapshot, act, wait, screenshot. Cookies, downloads and stored sign-ins stay on your computer.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to control and interact with the user's real Chrome browser session, leveraging existing logins, cookies, and extensions for AI-driven automation.5MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to drive a real, logged-in Chrome browser for web automation tasks like navigation, clicking, typing, and screenshotting.MIT
- AlicenseBqualityCmaintenanceEnables MCP clients to drive a real Chromium browser for automation, including navigation, JavaScript execution, CDP commands, network capture, and multi-tab control.7GPL 3.0
- AlicenseAqualityCmaintenanceEnables MCP clients to drive a real cloud Chrome browser to read blocked pages, fill forms, take screenshots, and hand off control to a person for logins or CAPTCHAs.16MIT