Auto Browser: an MCP-native browser control plane with human takeover

The problem Auto Browser addresses: agents that can read HTML but cannot operate a session

Most agent stacks can fetch a page and parse it. That breaks the moment a workflow depends on being logged in, on a tab that has to stay open, or on a step a person has to perform once and then never again. Auto Browser is aimed at that gap. The README calls it "an MCP-native browser control plane for authorized workflows" and lists internal dashboards, admin tools, operator-assisted QA and login-once account workflows as good fits. The intended user is an engineer wiring an MCP client such as Claude Desktop or Cursor into a real Playwright browser, not someone who wants a headless scraper. The project is explicit about what it refuses to be: CAPTCHA solving, unauthorized scraping or account automation, and deceptive identity shaping are all under "Not the Goal". That boundary is the most useful thing in the README, because it tells you quickly whether you are in scope.

How the controller, browser-node and MCP bridge fit together

The stack is three cooperating pieces. A controller serves the REST API and MCP endpoint on port 8000 and owns sessions, approvals, auth profiles and audit events. A browser-node container runs the Playwright server, which the controller connects to over a websocket endpoint written to a file on a shared volume. The same container serves noVNC on port 6080, which is what makes human takeover possible: a person opens the VNC page and drives the live session the agent was using. MCP clients reach the controller either over HTTP or through a bundled stdio bridge (`uvx auto-browser-mcp`), so a client that only speaks stdio still works. The compose file shows the coupling clearly: the controller waits on `depends_on: service_healthy`, and the browser-node healthcheck requires three things at once, a non-empty endpoint file, a connection accepted on port 9223, and noVNC still answering on 6080. The comment in docker-compose.yml explains why: an earlier check looked only at 6080, so a dead Chromium could report healthy for as long as websockify survived. That is a real design lesson, not marketing.

Installing Auto Browser and running the login-and-reuse-profile flow

The README's quickstart is three commands and needs no configuration for local development. Run them from a normal terminal with Docker access. The stack publishes its ports on 127.0.0.1 by default.

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

Once the containers are up, three URLs matter. The API docs are at `http://127.0.0.1:8000/docs`, the operator dashboard at `http://127.0.0.1:8000/dashboard`, and visual takeover at `http://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scale`. The README notes that `make doctor` should be run from a normal terminal with local Docker access and permission to open localhost sockets, and that optional configuration starts by copying the example environment file.

cp .env.example .env
make doctor

The highest-signal workflow in the repo is documented in `examples/login-and-save-profile.md`: create a session, log in manually through noVNC if the site needs a person, save the session as a named auth profile, open a new session from that profile, and continue without reauthenticating. That sequence is the reason to run this instead of a plain Playwright script. If you only need to read a page, the v1.5.0 release notes describe a cheaper path: setting `PERCEPTION_PRESET_DEFAULT=text` returns the accessibility outline, extracted text and interactables with no screenshot and no OCR.

Approvals, operator identity and the limits of the shared bearer token

The safety surface is where Auto Browser makes its strongest claims, and also where the documentation is most honest about the weak spots. `.env.example` documents two authentication modes. `API_BIND_SCOPE=loopback` is the default and is what lets the stack run with no token at all. Set it to `exposed` and the controller refuses to start without an `API_BEARER_TOKEN` of at least 32 characters. Named credentials go in `API_BEARER_TOKENS` in the form `alice:token-a,bob:token-b`; a request authenticating with one of those has a verified operator identity, so the `X-Operator-Id` header can no longer claim to be someone else. The example file states plainly that the shared bearer token still works but cannot tell operators apart, so identity stays self-asserted. If your audit trail needs to attribute an action to a person, the shared token is the wrong choice. `REQUIRE_APPROVAL_FOR_UPLOADS=true` is on by default, and `ALLOWED_HOSTS` defaults to a short list including localhost, so a fresh install will not reach arbitrary sites until you change it.

The self-audit finding you should read before trusting the safety controls

The README links `docs/audits/2026-08-execution-audit.md`, described as an adversarial audit of the repository that "found safety controls which reported success while doing nothing", with reproductions, fixes and the gates that close the class. A project that publishes that finding is doing something most do not. It is also a warning. Controls that report success while doing nothing are exactly the failure mode that matters for approvals and audit trails, because the operator sees a green result and stops looking. Treat the audit document as required reading before you rely on any specific control, and check whether the fix for the control you depend on is covered there. The same applies to the Witness receipts: the README says the chains are Ed25519-signed and that an exported bundle verifies with `scripts/verify_witness_bundle.py`, which imports nothing from the project, so a recipient does not need to run or trust the controller to check it. That independence is the property worth testing yourself, because it is the difference between evidence and a log file.

Auto Browser versus Playwright directly, and when a plain fetcher wins

The comparison people search for is Auto Browser against Playwright. They are not competitors at the same layer. Playwright is the browser automation library; Auto Browser runs a Playwright server inside a container and puts a controller, an approval layer, an identity model, auth-profile storage and an MCP endpoint in front of it. If you already have a Playwright script that works, adding this stack buys you the operator dashboard, noVNC takeover, named auth profiles and signed receipts, and costs you a Docker Compose deployment plus a controller you now have to keep in sync. The release notes mention one concrete cost of that coupling: Playwright pin parity is enforced in CI so the pip controller and the npm browser-node must match exactly, because a single-side bump could previously merge and crash-loop compose deployments. For a task that is genuinely just fetching and parsing HTML, an HTTP client plus a parser is less machinery and has no browser process to wedge. Auto Browser earns its place when a human might need to step in, or when you need to prove afterwards what the agent did.

Maintenance, release cadence and what the MIT licence leaves to you

The last push to the default branch was on 2026-08-09, the same day v1.7.0 was released, following v1.6.1 and v1.6.0 earlier that month. The repository is not archived. Releases publish to PyPI through trusted publishing (OIDC) on tag push, and CI enforces dependency audits, fixture evals, client tests, wheel builds and an 80 percent controller coverage gate on Python 3.11 and 3.14. The licence is MIT, which is permissive and places no copyleft obligation on your own code, though it also means no warranty and no support commitment from the maintainers; that is a statement about the licence text, not legal advice. The upgrade cost that is visible in the repository is the Playwright version pairing between the pip controller and the npm browser-node, plus the compose healthcheck contract. Upgrading one side without the other is the failure the CI gate exists to prevent, so pin both and read CHANGELOG.md between versions. Docker Compose also carries several overlay files (`docker-compose.isolation.yml`, `docker-compose.host-subscriptions.yml`, `docker-compose.codespaces.yml`), and the Makefile exposes matching targets such as `up-isolation` and `up-reverse-ssh`; each combination is a separate configuration you are maintaining.

Editorial conclusion

Adopt Auto Browser if your agents need a real browser on sites you are authorized to use, and you want approvals, operator identity and verifiable audit receipts in the same stack. Skip it if you need CAPTCHA solving, unauthorized scraping, or a pure HTML fetcher with no browser process. Before trusting it, read docs/audits/2026-08-execution-audit.md, which records safety controls that reported success while doing nothing, then run make doctor and watch the browser-node healthcheck, since it is the gate that decides whether the controller starts at all.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes