Auto Browser is an open-source, MCP-native browser agent control plane designed for authorized workflows. It lets MCP clients, LLM agents, and operators share the same Playwright browser, and provides human takeover, reusable authentication profiles, approvals, audit trails, and local-first deployment capabilities.
【Main capabilities】
- MCP-native: The browser operation surface is packaged as an MCP server from the start, rather than added on afterward.
- Human takeover: When a web workflow runs into problems, noVNC lets an operator step into the same live session.
- Log in once, reuse afterward: Named authentication profiles can be saved, and new sessions opened afterward can start already logged in.
- Local-first: By default, the full stack can run on your own machine with Docker Compose, and Codespaces can also be used for a quick hosted demo.
- Safety guardrails: Built-in approvals, operator identity, PII redaction, Witness receipts (Ed25519 signatures), and policy presets.
- Transferable evidence: The Witness receipt chain is Ed25519-signed, and exported evidence bundles can be verified with scripts/verify_witness_bundle.py. This script does not import anything from this project, so the recipient can verify it without running or trusting this controller.
- Public self-audit: docs/audits/2026-08-execution-audit.md records an adversarial audit against this repository, including the discovered issue of security controls "reporting success but not actually taking effect," reproduction steps, fixes, and gates to prevent similar issues from recurring.
- Governed skill induction: Verified browser trajectories can become staged skill candidates with provenance information; when a grid identity is configured, provenance is signed and verified on read (not just on generation), and validator adapters and a review-only promotion process are also provided.
【How to use】 Auto Browser exposes the following interfaces: HTTP MCP endpoint http://127.0.0.1:8000/mcp；便捷端点 http://127.0.0.1:8000/mcp/tools and http://127.0.0.1:8000/mcp/tools/call；stdio bridge can use the PyPI-available uvx auto-browser-mcp, or scripts/mcp_stdio_bridge.py in a repository checkout.
Any MCP client that supports communication over HTTP or stdio is supported, as are REST callers using curl directly. Clients mentioned as being able to connect directly over HTTP include Claude Code, Codex (CLI, IDE extension, and app), Google Antigravity, Cursor, and VS Code; Claude Desktop connects through the built-in stdio bridge. Google Antigravity can use the raw MCP configuration (MCP Servers → Manage MCP Servers → View raw config) or ~/.gemini/config/mcp_config.json, and reads serverUrl rather than url. For instructions on Cursor, VS Code, bearer token, and pairing with a web search MCP server, see docs/mcp-clients.md.
The default MCP tool set is curated mode: the 20 tools needed by a browsing agent (sessions, observation and screenshots, execute_action, page and download reading, tabs, authentication profiles, human takeover). Diagnostics, audit, harness, and management tools are in the full configuration and are exposed only when MCP_TOOL_PROFILE=full is set.
Service address: API documentation http://127.0.0.1:8000/docs；操作员仪表盘 http://127.0.0.1:8000/dashboard（包含等待审批的操作队列）；可视化接管 http://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scale。所有发布端口默认绑定到 127.0.0.1.
Prebuilt images are published on GHCR, so the build can be skipped: AUTO_BROWSER_IMAGE_TAG can specify the version (latest by default, a release such as 1.9.1, or edge for the current main). The image is linux/amd64 and comes with an SBOM and build provenance attestation. The controller image does not include the agent CLI; if you need *_AUTH_MODE=cli, build from source with INSTALL_AGENT_CLIS=true.
[Use cases] Internal dashboards and admin tools, operator-assisted QA and browser debugging, account workflows that log in once and are reused, websites that are prone to issues and need manual recovery flows, and MCP agent workflows that need a real browser (rather than only HTML scraping).
[Limitations and compliance] Explicitly not for: CAPTCHA cracking, unauthorized scraping or account automation, deceptive identity shaping, or bypass tools.
Session isolation: by default all sessions share one Chromium process and one noVNC desktop (SESSION_ISOLATION_MODE=shared_browser_node). Cookies and storage are isolated per session, but when a human takes over one session they can see other sessions' windows. When sessions belong to different people, accounts, or trust domains, use make up-isolation to provide each session with its own browser container and takeover interface (docker_ephemeral); see docs/session-isolation-audit.md for details.
Production deployment: with APP_ENV=production, the controller will refuse to start if required settings are missing, and will list the missing items in the startup log. COMPLIANCE_TEMPLATE can apply a preconfigured posture at startup; both presets require upload approval and enable Witness receipts, and at startup the applied policy is written to /data/compliance-manifest.json. The old names (HIPAA, SOC2, GDPR, PCI-DSS) can still be used as deprecated aliases, but a warning is emitted at startup. For more deployment details, managed Witness instructions, CLI authentication mode, and reverse SSH guidance, see docs/deployment.md and docs/production-hardening.md.
[Architecture overview] Core components: browser-node/ runs Chromium, Xvfb, x11vnc, and noVNC; controller/ exposes the FastAPI controller, MCP transport, policy guardrails, and orchestration endpoints; data/ stores runtime artifacts, authentication state, approvals, audit logs, and an optional CLI cache; scripts/ contains local helper scripts for doctor, smoke tests, bridging, and release checks. Model providers: first-class adapters are provided for OpenAI, Claude, and Gemini (API or CLI); in addition, a generic OpenAI-compatible adapter can drive any model accessed through an OpenAI /chat/completions endpoint. Except for text-only models, all providers use vision (screenshots). See *_API_KEY / *_BASE_URL / *_MODEL in .env.example for settings.
