Auto Browser

Give your AI agent a real browser, with a human in the loop.

Auto Browser is an MCP-native browser control plane for authorized workflows. It gives MCP clients, LLM agents, and operators a shared Playwright browser with human takeover, reusable auth profiles, approvals, audit trails, and local-first deployment.

Works with:

• Claude Code, Codex (CLI, IDE extension, and app), Google Antigravity, Cursor, and VS Code, connected directly over HTTP
• Claude Desktop, through the bundled stdio bridge
• any MCP client that can talk HTTP or stdio
• direct REST callers when you want curl-first control

Why Auto Browser

• MCP-native from day one. The browser surface is already packaged as an MCP server instead of bolted on after the fact.
• Human takeover when the web gets brittle. noVNC keeps the same live session available when a person needs to step in.
• Login once, reuse later. Save named auth profiles and reopen fresh sessions that are already signed in.
• Local-first by default. Run the full stack on your own box with Docker Compose, or use Codespaces for a quick hosted demo.
• Safety rails built in. Approvals, operator identity, PII scrubbing, Witness receipts, and policy presets are all part of the product surface.
• Evidence you can hand to someone else. Witness receipt chains are Ed25519-signed, and an exported bundle verifies with scripts/verify_witness_bundle.py — which imports nothing from this project, so a recipient need not run or trust this controller to check it. The signing key sits beside the receipts, so for evidence that survives a compromised box, pin a head hash you recorded earlier or ship the receipts off the box (details).
• We audit ourselves in public. docs/audits/2026-08-execution-audit.md documents an adversarial audit of this repo that found safety controls which reported success while doing nothing, with reproductions, the fixes, and the gates that close the class.
• Governed skill induction. Verified browser traces can become staged skill candidates with provenance that is signed when a mesh identity is configured — and checked on read, not just produced — plus verifier adapters and review-only graduation — agents that prove they can repeat themselves correctly, not just act once.

Good Fits

• internal dashboards and admin tools
• operator-assisted QA and browser debugging
• login-once, reuse-later account workflows
• brittle sites where a human may need to recover the flow
• MCP-powered agent workflows that need a real browser, not just HTML fetches

Not the Goal

• CAPTCHA solving
• unauthorized scraping or account automation
• deceptive identity shaping or bypass tooling

What You Get

Quickstart

git clone https://github.com/LvcidPsyche/auto-browser.git
cd auto-browser
docker compose up --build

That is enough for local development with the default settings.

Optional:

cp .env.example .env
make doctor

Run make doctor from a normal terminal with local Docker access and permission to open localhost sockets.

Open:

• API docs: http://127.0.0.1:8000/docs
• Operator dashboard: http://127.0.0.1:8000/dashboard, which includes the queue of actions waiting on your approval
• Visual takeover: http://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scale

All published ports bind to 127.0.0.1 by default.

Prebuilt images

Every release is also published to GHCR, so you can skip the build:

docker compose -f docker-compose.yml -f docker-compose.images.yml up -d

AUTO_BROWSER_IMAGE_TAG picks the version: latest (the default), a release such as 1.10.1, or edge for the current main. The images are linux/amd64, and each carries an SBOM and a build provenance attestation (gh attestation verify oci://ghcr.io/lvcidpsyche/auto-browser-controller:latest -R LvcidPsyche/auto-browser). The controller image leaves out the agent CLIs; for *_AUTH_MODE=cli, build from source with INSTALL_AGENT_CLIS=true.

Try It in Codespaces

Codespaces provisions the stack automatically. The dashboard and noVNC tabs are usually ready in about 90 seconds.

First Useful Demo

The highest-signal flow in this repo is:

1. create a session
2. log in manually if the site needs a human
3. save the session as a named auth profile
4. open a new session from that auth profile
5. continue work without reauthing

Start here:

• examples/login-and-save-profile.md
• examples/README.md

Minimal session creation:

curl -s http://127.0.0.1:8000/sessions \
  -X POST \
  -H 'content-type: application/json' \
  -d '{"name":"demo","start_url":"https://example.com"}' | jq

Minimal observation:

curl -s http://127.0.0.1:8000/sessions/<session-id>/observe | jq

Recent Changes

1.10.1

• Rebuilt Docker images with updated dependencies (Pillow 13.0.0). Image tags now publish only from a main commit whose CI run succeeded.

1.10.0

• Operators can no longer reach each other's work. With named credentials (API_BEARER_TOKENS), saved auth state, exported archives, harness runs, skill candidates, memory profiles, uploads, MCP resource lists and controller-wide approvals belong to the operator who made them.
• ALLOWED_HOSTS holds wherever a page ends up: after a redirect, a tab switch, a cookie write, or a page that navigates itself.
• Witness verification rejects a chain with its signatures stripped, and the top-level valid now covers signatures. Read the upgrade notes in the changelog before upgrading.
• Fixes for the Playwright export, stealth mode, REST error statuses, text-only agent steps, private-key scrubbing and the dashboard's error reporting, plus an opt-in FORCE_GOVERNED_APPROVALS.

1.9.1

• Prebuilt Docker images on GHCR (thanks @FRFlo): run a release without building it. See Prebuilt images.

1.9.0

• Operators no longer share sessions. With named credentials (API_BEARER_TOKENS), a session belongs to the operator who created it, as auth profiles already did.
• Every setting in .env reaches the controller. Compose used to forward only the keys it listed, so settings like API_BEARER_TOKENS and PII_SCRUB_* were ignored. Check your .env before upgrading.
• Governed approvals run, a page stuck in a script loop can no longer hang the controller, and the Claude and OpenAI providers work on current models.
• Security fixes for approvals, navigation, TOTP autofill, PII scrubbing and witness bundle verification (GHSA-37hm-f6gf-q7vx).

1.8.1

• Sturdier sessions and stores. Actions that ran are no longer reported as failed when the page navigates right after, an approved action runs at most once, MAX_SESSIONS holds under concurrent creates, and sessions, tabs, cron jobs and the JSON stores no longer leak or lose writes.
• The stdio MCP bridge survives a controller restart and reports auth and rate-limit errors instead of hanging. The SDK, bridge and LangChain adapters can send an operator id for controllers with REQUIRE_OPERATOR_ID=true.
• Faster actions and observations, fewer browser round trips per observation, and a controller image without the test tooling.
• Security fixes for the noVNC socket, TOTP autofill, auth-profile paths, approvals and witness receipts. create_session with totp_secret now needs totp_hosts or a start_url.

See CHANGELOG.md for the full release history.

MCP Clients

Auto Browser exposes:

• an HTTP MCP endpoint at http://127.0.0.1:8000/mcp
• convenience endpoints at http://127.0.0.1:8000/mcp/tools and http://127.0.0.1:8000/mcp/tools/call
• a stdio bridge: uvx auto-browser-mcp from PyPI, or scripts/mcp_stdio_bridge.py in a repo checkout

Clients that speak MCP over HTTP connect directly. With Claude Code or Codex:

claude mcp add --transport http auto-browser http://127.0.0.1:8000/mcp
codex mcp add auto-browser --url