LvcidPsyche/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.
- **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
| Browser Control | Operator Safety | Deployment and Integration |
| --- | --- | --- |
| Playwright-backed sessions with screenshots, DOM summaries, OCR excerpts, tab controls, downloads, and network inspection | approval gates, operator identity headers, audit events, PII scrubbing, Witness receipts, and protection profiles | MCP over HTTP, bundled stdio bridge, REST API, Docker Compose, Codespaces, auth profiles, and optional per-session isolation |
Quickstart
That is enough for local development with the default settings.
Optional:
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:
AUTO_BROWSER_IMAGE_TAG picks the version: latest (the default), a release such as 1.9.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