Auto Browser
Give your AI agent a real browser with a human in the loop — an open-source, MCP-native browser control plane for authorized workflows.
Evidence shows concrete least-privilege defaults: all ports bind 127.0.0.1, default curated MCP tool profile, elevated harness operations require MCP_TOOL_PROFILE=full (2). Approval gates, audit events, PII scrubbing, encrypted auth state, and signed Witness receipts are asserted only in the README; the controller/policy implementation was not in evidence, and SECURITY.md itself admits a prior vulnerability where safety controls reported success while doing nothing (GHSA-32ph), so these claims score 1, not 2. Dependency security is well-evidenced: pip-audit, npm audit against lockfile, and pin-parity gates in CI (2). External effects are inherent to browser automation; the allowlist is claimed, not shown (1). Rollback is claimed only for the shadow-browse path (1). Attribution: MIT license (JAI Studios) and published audit/advisory records exist, but publisher is unverified (2).
The README, SECURITY.md, CI workflows, and client tests corroborate each other: CI comments explain concrete past failures fixed (unittest silently skipping pytest-style tests, pin drift, missing SDK coverage gates), and tests verify errors map to AutoBrowserError instead of leaking raw httpx exceptions (2). Dependency availability is supported by Docker Compose, uvx zero-setup bridge, and lockfile installs (2). Failure-message improvements (field-level argument errors, cold-start guidance, handler passthrough) are documented in v1.5.0 notes and backed by regression tests (2). All judgments are static; no execution evidence exists.
Audience and scenarios are well covered: Good Fits / Not the Goal sections name target uses and explicit exclusions; works with Claude Desktop, Cursor, any MCP client, and raw REST (3). Capability boundaries have a dedicated section cross-corroborated by SECURITY.md's out-of-scope list (2). Trigger precision is thin: the curated profile is claimed to improve tool selection but the actual tool list and descriptions were not in evidence (1). Environment fit spans local, Codespaces, and many model providers (2; not higher because the actual configuration surface is unverified here).
Information architecture is excellent: Repo Guide, Documentation Map, and Common Commands tables map paths to purposes clearly (3). Install notes are command-level concrete: git clone + docker compose up, pip/uvx, .env.example, make doctor (3). Naming stability is CI-enforced via version parity, bridge-copy parity checks, and deprecated-alias warnings (2). Examples and FAQ are referenced by path but their contents were not in evidence (2). Known limitations are candidly documented through public self-audits admitting real vulnerabilities (2). MIT license text is present (3). Versioning/changelog is supported by tag-version parity gating and changelog extraction in release.yml, but CHANGELOG.md itself was not shown (2). Maintenance responsibility has a security-handling process and triage-gating script, but the publisher is unverified and the project appears single-maintainer (2).
Output usability: observe presets including a cheap text mode, three access channels (REST/SDK/MCP), and client tests verifying API shapes and parameter serialization (2). Marginal value: HITL takeover, signed receipt chains, and an independently runnable bundle verifier differentiate from generic browser MCP servers, though only the verifier script path is concretely checkable here (2). Cost-benefit: a full Docker stack is heavy; the text preset is a plausible cost mitigation but unverified by execution (2).
Claim traceability is strong: nearly every README claim points to a concrete path (scripts, docs, examples), and the audit doc openly admits failure with fixes and closing gates (2). Cross-source corroboration holds: SECURITY.md GHSA entries match the README's self-audit narrative, and CI comments match what the tests verify (e.g., the stream_events ResponseNotRead regression) (2). Facts and inference are mostly separated, but marketing badges (grade A, mcptoplist) and future-dated (2026) audit claims are mixed into the narrative without independent confirmation (2).
- This static review could not verify the actual implementation of approval gates, PII scrubbing, encryption, or Witness signing; the project has a documented history of safety controls that reported success while doing nothing (GHSA-32ph), so verify these controls behave as claimed before deployment.
- For production, set API_BEARER_TOKEN, REQUIRE_OPERATOR_ID, AUTH_STATE_ENCRYPTION_KEY, etc. as the README instructs; defaults are localhost-only, and a past advisory (GHSA-xmh3) involved an unauthenticated API exposure in a Codespaces overlay.
- Publisher identity is unverified; evaluate supply-chain trust for the PyPI packages (auto-browser-client, auto-browser-mcp) independently.
- Browser automation is inherently externally-facing; test allowlist behavior and the STEALTH_ENABLED=false claim in a controlled environment first.
What does this agent do, and when should you use it?
Auto Browser is a self-hosted, MCP-native browser control plane that gives MCP clients, LLM agents, and operators a shared Playwright browser with human takeover. The stack has three parts: a browser-node running Chromium, Xvfb, x11vnc, and noVNC; a FastAPI controller exposing REST, MCP over HTTP, a stdio bridge, and policy rails such as approvals and audit; and a data directory for runtime artifacts, auth state, and audit logs. Humans can take over the same live session via noVNC when a site flow gets brittle, and named auth profiles let a session log in once and be reused later. Safety features include approval gates, operator identity, PII scrubbing, and Ed25519-signed Witness receipt chains. On the model side it ships first-class adapters for OpenAI, Claude, and Gemini plus a generic OpenAI-compatible adapter covering OpenRouter, Grok, DeepSeek, MiniMax, and self-hosted Ollama/vLLM endpoints. The whole stack deploys locally with Docker Compose, with all published ports bound to 127.0.0.1 by default.
End-to-end flow: after docker compose up --build, create a Playwright session via POST /sessions with a JSON body containing name and start_url; observe pages with GET /sessions/<id>/observe (screenshots, DOM summaries, OCR excerpts, interactables, plus a zero-cost text preset added in v1.5.0). LLMs call tools like browser.create_session and browser.find_elements (which takes a text/regex query as of v1.5.0) through the MCP endpoint at http://127.0.0.1:8000/mcp or the stdio bridge uvx auto-browser-mcp; a person can take over the same session at any time via noVNC at port 6080. After logging in once, the session can be saved as a named auth profile and reused by new sessions. The controller enforces approval gates, operator identity headers, audit events (readable via the browser://audit/events MCP resource), PII scrubbing, and Witness receipt chains whose exported bundles verify with the standalone script scripts/verify_witness_bundle.py. A Stage 0 convergence harness runs task contracts, records tamper-checked traces, and produces staged skill candidates with signed provenance.
- Ops or support teams driving internal dashboards and admin tools where agents execute but humans approve critical steps
- QA engineers debugging brittle sites who need to recover a failing flow manually over noVNC
- Login-once, reuse-later account workflows using named auth profiles
- Claude Desktop or Cursor users whose agents need a real browser, not just HTML fetches
- Compliance-sensitive teams needing approvals, PII scrubbing, and independently verifiable signed receipt chains
- Self-hosters who want any OpenAI-compatible model, including local Ollama/vLLM, to drive the browser
What are this agent's strengths and limitations?
- MCP-native design: the browser surface ships as an MCP server from day one (HTTP endpoint plus stdio bridge), working out of the box with Claude Desktop, Cursor, and any MCP client, with REST for curl-first callers
- Human takeover plus reusable auth: noVNC lets a person step into the same live session, and named auth profiles enable login-once reuse — capabilities many pure-automation tools lack
- Concrete, verifiable safety rails: approval gates, operator identity, PII scrubbing, and Ed25519-signed Witness receipt chains whose verification script imports nothing from the project, so recipients need not trust the controller
- Model-agnostic: first-class OpenAI/Claude/Gemini adapters, a generic OpenAI-compatible adapter (OpenRouter, Grok, DeepSeek, MiniMax, self-hosted endpoints), plus a publicly documented adversarial self-audit in docs/audits/
- Non-trivial deployment: the full stack requires Docker Compose running Chromium, Xvfb, x11vnc, noVNC, and a FastAPI controller — not a single-binary solution
- Production requires explicit configuration: defaults target local development; exposing beyond localhost means setting a bearer token, Fernet encryption key, operator ID, rate limiting, and more yourself
- Feature gating by profile: convergence-harness write tools and graduation need
MCP_TOOL_PROFILE=fullor direct REST; the default curated profile omits them - Playwright versions are CI-enforced to match exactly between the pip controller and npm browser-node; a one-sided bump cannot merge and can crash-loop compose deployments
- Explicitly excludes CAPTCHA solving, unauthorized scraping, and bypass tooling — not suitable if you need those
How do you install or deploy this agent?
1) Clone and start: git clone https://github.com/LvcidPsyche/auto-browser.git && cd auto-browser && docker compose up --build. 2) Optional readiness check: cp .env.example .env && make doctor (requires local Docker access). 3) Python 3.10+ for optional host-side tests. SDKs and bridges are also on PyPI: pip install auto-browser-client, pip install auto-browser-langchain, uvx auto-browser-mcp. For production, set at least APP_ENV=production, API_BIND_SCOPE=exposed, API_BEARER_TOKEN, REQUIRE_OPERATOR_ID=true, AUTH_STATE_ENCRYPTION_KEY (44-char Fernet key), and REQUIRE_AUTH_STATE_ENCRYPTION=true; or apply a preset with COMPLIANCE_TEMPLATE=strict or balanced.
How do you use this agent?
After startup, open API docs at http://127.0.0.1:8000/docs, the operator dashboard at http://127.0.0.1:8000/dashboard, and noVNC takeover at http://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scale. Create a session: curl -s http://127.0.0.1:8000/sessions -X POST -H 'content-type: application/' -d '{"name":"demo","start_url":"https://example.com"}'. Observe: curl -s http://127.0.0.1:8000/sessions/<session-id>/observe. MCP calls: POST {"name":"browser.create_session","arguments":{...}} to http://127.0.0.1:8000/mcp/tools/call, or configure the stdio bridge uvx auto-browser-mcp in Claude Desktop / Cursor. The default MCP tool profile is curated; set MCP_TOOL_PROFILE=full for the complete surface including harness.* tools. Configure model providers via *_API_KEY / *_BASE_URL / *_MODEL in .env.
How does this agent compare with similar options?
The README positions itself against browser automation that is bolted onto agent frameworks after the fact, contrasting its MCP-native, self-hosted, human-in-the-loop approach, but the source names no specific competitors, so no factual comparison is possible.
FAQ
Do I have to pay or use a specific model vendor?
What runtime and permissions are required?
What happens when the agent gets stuck or a site flow breaks?
How large is the default MCP tool surface, and how do I get all tools?
curated, kept compact for better tool selection. Set MCP_TOOL_PROFILE=full to expose the complete internal surface (including convergence-harness write operations), or call REST directly.Can audit evidence be independently verified by a third party?
scripts/verify_witness_bundle.py, which imports nothing from the project — the recipient need not run or trust this controller.