Auto-Browser

- Read a page without paying for pixels.The newtextobservation preset returns the accessibility outline, extracted text, and interactables with no screenshot and no OCR — the cheapest way for an agent to read a page. SetPERCEPTION_PRESET_DEFAULT=textto make it a deployment-wide default.
- Find a string on the page in one call.browser.find_elementsnow takes aquery(plain text or regex, case-insensitive) instead of a CSS selector and returns each match with surrounding context — no full observe needed to check one value.
- Errors agents can act on.Invalid tool arguments report field-level details, handler messages pass through instead of a generic failure, and the MCP bridge's cold-start error now says exactly how to start the controller.
- Any OpenAI-compatible model can drive the browser.A single generic adapter serves every model reachable over an OpenAI/chat/completionsendpoint. New providers:openrouter(one key → ~every frontier model),xai(Grok),deepseek,minimax, andopenai_compatible(custom base URL for self-hosted Ollama / vLLM / LM Studio, Azure, Together, Groq, Fireworks, …). Vision + function-calling with a content-parse fallback for endpoints that ignoretool_choice.
- browser://audit/eventsMCP resource.List and read recent audit events across sessions directly over MCP.
- Playwright pin parity enforced in CI.The controller (pip) and browser-node (npm) Playwright versions must match exactly — a single-side bump can no longer merge and crash-loop compose deployments.
- On PyPI.pip install auto-browser-clientfor the SDK,pip install auto-browser-langchainfor the LangChain/LangGraph/CrewAI adapters, anduvx auto-browser-mcpto run the MCP stdio bridge with zero setup. Releases publish via PyPI trusted publishing (OIDC) on tag push.

- browser_manager.pyis now a pure facade + composition root(1,284 → 769 lines), with domain logic extracted intoapp/browser/services/.
- Fork state exports are encrypted at restand shadow-browse state never touches disk.
- Download capture tasks can no longer be garbage-collected mid-flight, shadow-browse failures roll back cleanly, and page listeners survive object-id reuse.
- Release gates in CIenforce dependency audits, fixture evals, client tests, Python wheel builds, and the 80% controller coverage gate on Python 3.11 and 3.14.

- 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

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

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.

Runmake doctorfrom a normal terminal with local Docker access and permission to open localhost sockets.

- API docs:http://127.0.0.1:8000/docs
- Operator dashboard:http://127.0.0.1:8000/dashboard
- Visual takeover:http://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scale

All published ports bind to127.0.0.1by 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:
- create a session
- log in manually if the site needs a human
- save the session as a named auth profile
- open a new session from that auth profile
- continue work without reauthing

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

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

The default MCP tool profile iscurated, which keeps the browser surface compact for better tool selection. If you want the full internal tool surface, set:

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