Auto Browser

What LvcidPsyche/auto-browser does

LvcidPsyche/auto-browser coordinates Playwright browser sessions for MCP clients, operators, and direct REST callers. It is intended for authorized workflows such as internal dashboards, administrative tools, browser debugging, and flows where automation may need human assistance. The browser remains available to an operator through a noVNC interface, so a person can recover a brittle flow without starting over.

Authentication can be saved as named profiles and reused when creating later sessions. The project also includes approval gates, operator identity headers, audit events, PII scrubbing, protection profiles, and Witness receipts. Signed receipt chains can be exported and checked with the standalone verification script.

How it works

The stack runs locally with Docker Compose. The controller exposes an HTTP API, API documentation, an operator dashboard, and a noVNC endpoint. MCP clients can connect directly over HTTP, while Claude Desktop can use the bundled stdio bridge. REST callers can control the same system with tools such as curl.

A typical workflow is to create a session with a starting URL, observe it, complete a login manually when required, save the session as an auth profile, and open a fresh session using that profile. Browser activity is backed by Playwright. Optional per-session isolation is available through the deployment configuration.

Setup and configuration

For a local installation, clone the repository and run:

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

The default published ports bind to 127.0.0.1. After startup, the API documentation is available at http://127.0.0.1:8000/docs, the operator dashboard at http://127.0.0.1:8000/dashboard, and the visual takeover page at http://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scale.

Copy .env.example to .env when you need configuration beyond the defaults. make doctor checks the local setup and should be run from a terminal with Docker access and permission to open localhost sockets. Prebuilt Linux amd64 images are available through GHCR, and GitHub Codespaces can provision the stack automatically.

Tools and capabilities

• Create and observe browser sessions through the HTTP API or MCP.
• Inspect screenshots, DOM summaries, OCR excerpts, and network activity.
• Control tabs and handle downloads.
• Take over an active browser through noVNC.
• Save named authentication profiles and reuse them in new sessions.
• Gate actions for approval and record operator and audit information.
• Scrub PII and generate signed Witness receipt chains for exported evidence.
• Connect through HTTP, stdio, REST, Docker Compose, or Codespaces.

Limitations and notes

The project is designed for authorized browser workflows, not CAPTCHA solving, unauthorized scraping, account automation, deceptive identity shaping, or bypass tooling. The prebuilt images target linux/amd64. For evidence intended to withstand a compromised host, receipt bundles should be moved off the machine or anchored with a previously recorded head hash, because the signing key is stored beside the receipts. Agent CLI authentication modes require an image built with INSTALL_AGENT_CLIS=true rather than the default controller image.