{ "markdown": "

\n \"Pixel-art\n

\n\n

Agent Browser

\n

See what your agent sees.

\n\n

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

\n\n

\n \"CI\"\n \"npm:\n \"PyPI:\n \"Source\n \"Python\n \"Self-hosted\"\n

\n\n

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

\n\n---\n\n

\n \"An\n

\n\n

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

\n\n---\n\n## Why this exists\n\nMost browser tooling for agents hands the model a browser you cannot see. When it misreads a page\nor stalls on a login, all you get is a transcript and a guess.\n\nAgent Browser runs **one headed Chrome session**. Your agent drives it through a small JSON API,\nand a live view of that **same** session sits open in front of you. When the agent gets stuck, you\ntake over in the window it is already using — then hand it back.\n\nStart the runtime:\n\n```bash\ndocker compose up --build\n```\n\nThen reach it however you like:\n\n```bash\nnpm install aether-browser # TypeScript\npip install aether-browser # Python\nclaude mcp add agent-browser -- npx -y aether-browser mcp # any MCP client\n```\n\n## Quickstart\n\nOne command, on **Docker Engine for Linux** with Compose v2. It builds from the source checkout\nand starts Xvfb, x11vnc, noVNC, and the API — the stack that owns a single headed Chrome session.\nBoth user-facing listeners bind to numeric loopback.\n\n```bash\ndocker compose up --build\n```\n\nOnce health responds, open the live view at\n[`127.0.0.1:6080/vnc.html`](http://127.0.0.1:6080/vnc.html) and check the API from another terminal:\n\n```bash\ncurl -fsS http://127.0.0.1:8092/browser/health | jq .\n```\n\n`Ctrl+C` stops it.\n\n> **The first build takes several minutes.** It installs the hash-locked Python environment, then\n> uses Patchright to install the current Google Chrome Stable package. The exact browser version is\n> captured with each accepted image, so rebuilding the same source later may pick up a newer Stable.\n\n> **Linux host networking is deliberate.** It keeps the unauthenticated v0.x noVNC surface on\n> numeric loopback. Docker Desktop and remote-host deployment are outside this quickstart.\n\n## The API in four calls\n\nWith the runtime healthy and `curl` plus `jq` installed. Local loopback needs no bearer token by\ndesign — read the [authority contract](docs/API.md#transport-and-authority) before you change the\ndeployment shape.\n\n```bash\n# Open the session. This is the browser you are about to watch.\nSESSION_ID=\"$(curl -fsS -X POST http://127.0.0.1:8092/browser/session/create \\\n -H 'Content-Type: application/json' \\\n -d '{\"api_version\":\"v1\"}' | jq -er '.session_id')\"\n\n# Go somewhere. The page changes in the live view as this runs.\ncurl -fsS -X POST http://127.0.0.1:8092/browser/navigate \\\n -H 'Content-Type: application/json' \\\n -d \"{\\\"api_version\\\":\\\"v1\\\",\\\"session_id\\\":\\\"${SESSION_ID}\\\",\\\"url\\\":\\\"https://example.com\\\"}\" \\\n | jq '{status, final_url, title, readable_text}'\n\n# Read it back as structure, not pixels.\ncurl -fsS -X POST http://127.0.0.1:8092/browser/snapshot \\\n -H 'Content-Type: application/json' \\\n -d \"{\\\"api_version\\\":\\\"v1\\\",\\\"session_id\\\":\\\"${SESSION_ID}\\\"}\" \\\n | jq '{status, url, title, sequence, vision_steps_remaining}'\n\n# Give the browser back.\ncurl -fsS -X POST http://127.0.0.1:8092/browser/session/end \\\n -H 'Content-Type: application/json' \\\n -d \"{\\\"api_version\\\":\\\"v1\\\",\\\"session_id\\\":\\\"${SESSION_ID}\\\"}\" | jq .\n```\n\nWhat that did: `session/create` started one headed Chrome session and returned its UUID plus the\nlocal view URL. `navigate` validated the destination, pinned the allowed addresses, and changed the\npage on the shared display. `snapshot` returned bounded text, accessibility state, viewport\nmetadata, counters, and a PNG of that same page. At no point did the API and the human view create\ncompeting browsers — they met at one owned session.\n\nThe same flow ships as [`examples/curl.sh`](examples/curl.sh).\n\n## Use it from an MCP client\n\nAny MCP client — Claude Code, Claude Desktop, Cursor, Windsurf — can drive the session while you\nwatch, and take over when it gets stuck.\n\n```bash\nclaude mcp add agent-browser -- npx -y aether-browser mcp\n```\n\nAlready have the Python client? `aether-browser mcp` serves the same nine tools.\n\n
\nConfig-file clients (Claude Desktop, Cursor, Windsurf)\n\n```json\n{\n \"mcpServers\": {\n \"agent-browser\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"aether-browser\", \"mcp\"]\n }\n }\n}\n```\n
\n\n**Nine tools** — `browser_open` · `browser_navigate` · `browser_read` · `browser_click` ·\n`browser_type` · `browser_press` · `browser_scroll` · `browser_status` · `browser_close`\n\n`browser_open` hands back the live view URL, and every response after it repeats that URL, so you\nalways know where to look. On connect, the server tells the model to stop and ask for a takeover at\na login, a payment, or a 2FA prompt rather than guessing — the loop in the recording above.\n\nSetup and limits: [`docs/MCP.md`](docs/MCP.md).\n\n## Node and TypeScript client\n\nThe same API from Node, with types and cleanup you cannot forget:\n\n```bash\nnpm install aether-browser\n```\n\n```ts\nimport { AgentBrowser, withSession } from 'aether-browser'\n\nconst browser = new AgentBrowser({ controllerToken: process.env.AGENT_BROWSER_CONTROLLER_TOKEN })\n\nawait withSession(browser, async (session) => {\n const page = await session.navigate('https://example.com')\n await session.click({ selector: '#login' })\n await session.type({ selector: '#user', text: 'ada' })\n console.log(page.title, session.viewUrl)\n})\n```\n\n`withSession` always ends the session, including when your callback throws, so a crash cannot leave\nthe single slot occupied. No runtime dependencies, and it runs anywhere that can reach the server.\nIt carries a small CLI too: `npx aether-browser doctor` tells you what is missing before a first\nrun, and `up` builds and starts the runtime on a Linux host.\n\nSee [`clients/node/README.md`](clients/node/README.md).\n\n## Python client\n\nThe same client, same name, same commands, released version for version with the npm package:\n\n```bash\npip install aether-browser\n```\n\n```python\nimport os\n\nfrom aether_browser import AgentBrowser, session\n\nbrowser = AgentBrowser(controller_token=os.environ[\"AGENT_BROWSER_CONTROLLER_TOKEN\"])\n\nwith session(browser) as live:\n page = live.navigate(\"https://example.com\")\n live.click(selector=\"#login\")\n live.type(\"ada\", selector=\"#user\")\n print(page[\"title\"], live.view_url)\n```\n\nThe `session` context manager always ends the session, including when the body raises. No runtime\ndependencies — the transport is `urllib` from the standard library — ships type hints, and runs on\nPython 3.10 or newer, anywhere that can reach the server. Same CLI as the npm package:\n`aether-browser doctor`, `up`, `status`, `open`, `down`.\n\nSee [`clients/python/README.md`](clients/python/README.md).\n\n## What makes it different\n\n- **One session, two participants.** The agent acts through JSON. You watch the same display, and\n take the controls whenever you want them.\n- **Structure before pixels.** Readable text and a bounded accessibility tree come back before you\n spend a vision step on a screenshot.\n- **A small control surface.** The v0.x API exposes explicit browser actions — not a shell, not\n arbitrary JavaScript, not raw DevTools.\n- **Model-agnostic and self-hosted.** Bring the framework you already use, and keep the browser on\n hardware you control.\n\n## What it does today\n\n| Capability | v0.x contract |\n|---|---|\n| Browser | One headed Google Chrome Stable session launched through Patchright |\n| State | URL, title, readable text, bounded accessibility nodes, viewport, and PNG snapshot |\n| Actions | Navigate, click, type, scroll, and allowlisted key presses |\n| Human view | The same Xvfb display through loopback-only x11vnc and noVNC |\n| Ownership | One explicit UUID session with expiry, vision budget, and idempotent cleanup |\n| Authority | Observer/controller separation when authenticated; strict local loopback mode otherwise |\n| MCP | Nine stdio tools from either client (`aether-browser mcp`), no extra dependencies |\n| Navigation | HTTP(S)-only validation across requested, redirected, and browser-initiated navigation |\n\nRequest and response shapes, limits, and stable error codes: [`docs/API.md`](docs/API.md).\n\n## Architecture\n\n```mermaid\nflowchart LR\n Agent[\"Agent client\"] -->|bounded JSON API| API[\"FastAPI\"]\n API --> Guard[\"authority + navigation policy\"]\n Guard --> Session[\"single-session manager\"]\n Session --> Chrome[\"Patchright + headed Google Chrome\"]\n Chrome --> State[\"text · accessibility · PNG\"]\n State --> Agent\n Chrome --> Display[\"shared Xvfb display\"]\n Display -->|loopback noVNC| Human[\"Human observer / takeover\"]\n```\n\nThe session manager owns the page, browser context, temporary profile, timers, counters, and\ncleanup. The API and the live view are different interfaces to that shared resource, not two\nindependent automation paths. See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).\n\n> [!IMPORTANT]\n> **Agent Browser v0.2.2 is source-first and self-hosted.** It is not a hosted service, and\n> the v0.x noVNC surface is unauthenticated and meant for numeric loopback on a machine you control.\n> No Chrome-containing image, image tar, or public layer cache is distributed unless separate\n> redistribution authorization is documented.\n\n## Security boundary\n\n- API and noVNC listen on numeric loopback by default; noVNC remains loopback-only in the v0.x line.\n- Remote API clients require a separately operated same-host HTTPS reverse proxy, an exact\n trusted loopback peer, strict Host validation, and distinct strong observer/controller tokens.\n- Destination validation rejects credentials, unsupported schemes, blocked address classes,\n unsafe redirects, and DNS rebinding. Browser egress is pinned through an owned TCP proxy.\n- Non-proxied WebRTC UDP is disabled so it cannot silently bypass the TCP egress boundary.\n- Inputs, outputs, interactions, timeouts, lifetimes, and screenshot budgets are bounded.\n- Cleanup converges on session end, expiry, launch failure, application shutdown, and process\n failure.\n\nTrust assumptions and residual risks are spelled out in [`docs/SECURITY.md`](docs/SECURITY.md).\nReport vulnerabilities privately through [`SECURITY.md`](SECURITY.md) — please do not open a public\nsecurity issue.\n\n### Source recovery and exclusions\n\nThe source-recovery rule is **reuse general browser behavior, not private domain code**.\nLifecycle, structured-state, interaction, and cleanup patterns may be adapted from authorized\nreferences; ATS/trading integrations, broker or account selectors, order actions, secrets,\nand credential injection are excluded from the public core. Provenance status is tracked in\n[`docs/SOURCE-RECOVERY.md`](docs/SOURCE-RECOVERY.md).\n\n## What it does not do\n\n- No hosted cloud service, cloud control plane, or production remote-hosting claim.\n- No bundled LLM, account system, dashboard, credential vault, or credential injection.\n- No CAPTCHA bypass, anti-detection guarantee, stealth claim, or proxy rotation.\n- No arbitrary JavaScript, shell, filesystem, upload, clipboard, download, or raw CDP API.\n- No multi-session pool, ATS integration, trading integration, or brokerage behavior.\n\n## Roadmap\n\n**Shipped.** Both clients and their CLI are published as `aether-browser`, version for version,\n[on npm](https://www.npmjs.com/package/aether-browser) from [`clients/node`](clients/node) and\n[on PyPI](https://pypi.org/project/aether-browser/) from [`clients/python`](clients/python). Since\n`0.2.0` both also serve the MCP server.\n\nTwo tracks are open, each with an issue, and each is a good first contribution:\n\n1. [Multi-session worker pool](https://github.com/AetherAI3/agent-browser/issues/14) — explicit\n isolation and capacity semantics.\n2. [Session trace and recording export](https://github.com/AetherAI3/agent-browser/issues/15) —\n with clear privacy controls.\n\nThese are candidates, not shipped features.\n\n## Contributing\n\nStart with [`CONTRIBUTING.md`](CONTRIBUTING.md), the\n[`Code of Conduct`](CODE_OF_CONDUCT.md), and the current [`API contract`](docs/API.md). Small,\nwell-tested changes that keep the authority boundary narrow are very welcome — the two roadmap\nissues above are the best place to start. Security reports go through the private process in\n[`SECURITY.md`](SECURITY.md), never a public issue.\n\n## License and third-party notices\n\nAether-owned source code is licensed under the [Apache License 2.0](LICENSE). Google Chrome is\nseparately licensed under [Google's Chrome terms](https://www.google.com/chrome/terms/) and is not\ncovered by Aether's Apache license; dependencies, system packages, fonts, and web assets also\nremain under their respective terms. See [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).\nAether is not affiliated with or endorsed by Google. The v0.x distribution target is source that\nbuilds locally; this repository does not distribute a prebuilt Chrome-containing image.\n\n

Agent Browser · See what your agent sees.

\n", "bytes": 15107, "sha": "b9f5fcc258ef55ef067c4be219ab35c05c01f396c938f7a9e6ae3ffaa362de28", "repo_slug": "aetherai3/agent-browser", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_aetherai3_agent_browser_bd04fe29/readme" }