by LvcidPsyche
Give your AI agent a real browser — with a human in the loop. Open-source MCP-native browser agent.
# Add to your Claude Code skills
git clone https://github.com/LvcidPsyche/auto-browserLast scanned: 5/17/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-17T06:45:55.041Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
30 days in the Featured rail · terms & refunds

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:
See CHANGELOG.md for the full release history.
| 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 |
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:
http://127.0.0.1:8000/docshttp://127.0.0.1:8000/dashboardhttp://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scaleAll published ports bind to 127.0.0.1 by default.
Codespaces provisions the stack automatically. The dashboard and noVNC tabs are usually ready in about 90 seconds.
The highest-signal flow in this repo is:
Start here:
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
Auto Browser exposes:
http://127.0.0.1:8000/mcphttp://127.0.0.1:8000/mcp/tools and http://127.0.0.1:8000/mcp/tools/callscripts/mcp_stdio_bridge.pyThe default MCP tool profile is curated, which keeps the browser surface compact for better tool selection. If you want the full internal tool surface, set:
MCP_TOOL_PROFILE=full
Raw tool-call example:
curl -s http://127.0.0.1:8000/mcp/tools/call \
-X POST \
-H 'content-type: application/json' \
-d '{
"name":"browser.create_session",
"arguments":{
"name":"demo",
"start_url":"https://example.com"
}
}' | jq
Client setup guides:
docs/mcp-clients.mdexamples/claude-desktop-setup.mdexamples/cursor-mcp-setup.mdexamples/claude_desktop_config.jsonAuto Browser ships a Stage 0 convergence harness for Agent Skill Induction. It runs a structured task contract, records tamper-checked traces, verifies completion, and writes a staged skill candidate with signed provenance. Generated skills are staged only — promotion stays explicit and reviewed.
Read-only inspection tools (harness.list_runs, harness.get_status, harness.get_trace) are exposed in the default curated MCP tool profile so agents can introspect harness state without elevated access. Convergence runs, drift checks, candidate management, and graduation require MCP_TOOL_PROFILE=full, or can be invoked directly over REST.
Start with docs/convergence-harness.md. A deterministic local smoke is:
python -m controller.harness.run --contract evals/contracts/example_read.json --mock-final-url https://example.com --mock-final-text "Example Domain"
For MCP clients, set MCP_TOOL_PROFILE=full to expose the harness.* tools.
For a real private deployment, set at least:
APP_ENV=production
API_BEARER_TOKEN=<strong-random-secret>
REQUIRE_OPERATOR_ID=true
AUTH_STATE_ENCRYPTION_KEY=<44-char-fernet-key>
REQUIRE_AUTH_STATE_ENCRYPTION=true
REQUEST_RATE_LIMIT_ENABLED=true
METRICS_ENABLED=true
STEALTH_ENABLED=false
COMPLIANCE_TEMPLATE can apply a preconfigured posture at startup:
| Preset | Auth Encryption | Operator ID | PII Scrub | Isolation | Max Session Age |
|---|---|---|---|---|---|
strict |
required | required | all layers | docker_ephemeral |
4h |
balanced |
- | required | network + text | shared | 24h |
Both presets require upload approvals and enable Witness receipts. Startup writes the applied policy to /data/compliance-manifest.json. The legacy names (HIPAA, SOC2, GDPR, PCI-DSS) still work as deprecated aliases and emit a warning at startup.
Example:
COMPLIANCE_TEMPLATE=strict docker compose up
For deployment details, hosted Witness notes, CLI auth modes, and reverse-SSH guidance, see:
flowchart LR
User[Human operator] -->|watch / takeover| noVNC[noVNC]
LLM[OpenAI / Claude / Gemini] -->|shared tools| Controller[Controller API]
Controller -->|Playwright protocol| Browser[Browser node]
noVNC --> Browser
Browser --> Artifacts[(screenshots / traces / auth state)]
Controller --> Artifacts
Controller --> Policy[Allowlist + approval gates]
Core components:
browser-node/ runs Chromium, Xvfb, x11vnc, and noVNCcontroller/ exposes the FastAPI controller, MCP transport, policy rails, and orchestration endpointsdata/ holds runtime artifacts, auth state, approvals, audit logs, and optional CLI cachesscripts/ contains local helpers for doctor, smoke tests, bridges, and release checks| Path | What It Contains |
|---|---|
controller/ |
controller API, MCP transport, tests, and packaging |
browser-node/ |
browser runtime and Playwright connection layer |
examples/ |
copy-paste flows and MCP client setup |
integrations/langchain/ |
LangChain, LangGraph, and CrewAI adapters |
docs/ |
architecture, deployment, hardening, and launch docs |
scripts/ |
doctor, |