browser-agent

🔗 Companion project: @vernikr/browser-agent-mcp — the MCP server that exposes this daemon to LLM agents (Claude Code, Cursor, Freebuff…). The two projects are developed together and speak the HTTP contract in docs/api.md.

Real headful Chrome on Xvfb with a hardware-level X11 mouse. One localhost daemon gives any project, script, or AI agent on a Linux box a genuine desktop browser: steered over real XTEST input events on randomized Bézier paths, with zero-leak CDP (no Runtime.enable), Cloudflare Turnstile auto-solve, and RAM discipline for tiny VPSes (auto-hibernates when idle — browser-agent doctor reports what it actually costs).

Why not Playwright/CDP directly: mainstream automation stacks call Runtime.enable / Debugger.enable on connect — the primary headless-detection vector. This daemon's CDP client refuses those methods by construction and reads the DOM via DOM.getOuterHTML; all mouse/keyboard input goes through the X server, so clicks are isTrusted: true hardware events.

Install & provision (server, Ubuntu 24.04)

curl -LsSf https://astral.sh/uv/install.sh | sh     # if uv is missing
uv tool install browser-agent-server
sudo browser-agent setup --with-chrome              # apt deps + google-chrome-stable + systemd unit
sudo browser-agent doctor                           # self-check

No systemd (container, WSL, a supervisor of your own)? The same install works — --no-unit skips the unit file and you run the daemon yourself:

uv tool install browser-agent-server
sudo browser-agent setup --no-apt --no-unit         # chrome only; deps already in the image
browser-agent doctor                                # self-check
browser-agent serve &                               # foreground/background under your supervisor

Use it three ways:

browser-agent fetch "https://example.com" --text        # CLI
curl -s 127.0.0.1:8765/status                           # HTTP API (any language)

from browser_agent import BrowserClient                 # Python SDK

client = BrowserClient()
page = client.fetch("https://example.com")
print(page["title"], len(page["text"]))

Connect from your workstation (agents)

Point the MCP bridge at this daemon — details and ready-made agent configs live in the companion repo:

pnpm dlx @vernikr/browser-agent-mcp init --client claude-code

What you get

Capability	Detail
Real Chrome, never headless	`google-chrome-stable` headed on on-demand `Xvfb` (1280×720x24) + `openbox`
Stealth CDP	Hand-rolled RFC-6455 client; `Runtime.enable`/`Console.enable`/`Debugger.enable` refused by construction
Human-like input	X11 XTEST mouse on randomized cubic Bézier curves with ease-in/out pacing and Gaussian micro-jitter; a human-scale pause between press and release
Cloudflare Turnstile	Detects the interstitial, locates the checkbox via the DOM and clicks it with the real X11 mouse
RAM discipline	one renderer, a bounded JS heap, the tab reset after each fetch, and auto-hibernation after an idle period — see the env table for the timeout and `browser-agent doctor` for what it costs
One at a time	Global mutex: 1 tab across all callers
Interfaces	CLI `browser-agent`, HTTP API `127.0.0.1:8765`, Python SDK `browser_agent.BrowserClient`
Live view	`browser-agent vnc start` + SSH-forwarded VNC
Optional WARP route	Auto-retry blocked pages through a local SOCKS5 proxy (`127.0.0.1:40000`)

Docs

docs/deployment.md — provisioning, systemd, memory limits, WARP, VNC logins
docs/api.md — HTTP contract (v1)
docs/architecture.md — how and why it works
docs/security.md — trust boundaries (loopback-only, no auth)
docs/troubleshooting.md — symptom → cause → action

For AI agents

Install one-liner: uv tool install browser-agent-server && sudo browser-agent setup --with-chrome && browser-agent doctor No-systemd host (container/WSL): uv tool install browser-agent-server && sudo browser-agent setup --no-apt --no-unit && browser-agent serve & Self-check: browser-agent doctor --json (exit 0 = host ready; every failed check carries a fix command you can run). Companion MCP for agent hosts: vernikr/browser-agent-mcp.

Platform support

Linux/X11 only (Xvfb, XTEST). Works great on a 1 vCPU / 1 GB RAM VPS. macOS/Windows workstations should run the MCP bridge and talk to a Linux host running this daemon.

License

MIT — see LICENSE.

Metadata

Release files for browser-agent-server 1.0.20

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for browser-agent-server 1.0.20
File	Size	Uploaded
browser_agent_server-1.0.20.tar.gz	147.0 kB	Oct 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for browser-agent-server 1.0.20
File	Interpreter	ABI	Platform	Reset
browser_agent_server-1.0.20-py3-none-any.whl 44.5 kB Oct 11, 2026	Python 3	none	any	Details

Total release size: 191.5 kB

Release files / browser_agent_server-1.0.20.tar.gz

Download URL	browser_agent_server-1.0.20.tar.gz
Size	147.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`99eef370a4016e1d7124e6a9fde1ebf870387688fc6cc787321cb80114acbd15`
BLAKE2b-256 checksum How to use checksums	`2136ecbc05f41c86220a931ec98356072423e0a455bb9a22e0d04404b7ab8673`
Upload date	Oct 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/vernikr/browser-agent
Publishing commit: github.com/vernikr/browser-agent/tree/47f46e30e1c2ef9b22aa2834276e08d968d9fd5a

Workflow

Publishing configuration: github.com/vernikr/browser-agent/blob/47f46e30e1c2ef9b22aa2834276e08d968d9fd5a/.github/workflows/release.yml
Publishing logs: github.com/vernikr/browser-agent/actions/runs/38144629092/attempts/1

Artifact

Subject: browser_agent_server-1.0.20.tar.gz
SHA-256 checksum: 99eef370a4016e1d7124e6a9fde1ebf870387688fc6cc787321cb80114acbd15 Verifying attestations

Release files / browser_agent_server-1.0.20-py3-none-any.whl

Download URL	browser_agent_server-1.0.20-py3-none-any.whl
Size	44.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`338ce10fe9e802605bd878bfb4df545947ddfbaaebacb577296a42c52b31e204`
BLAKE2b-256 checksum How to use checksums	`b0b761613a3807a1af53033cfc0ff5ee041688105bb27b9a85c7d66e713e59c9`
Upload date	Oct 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/vernikr/browser-agent
Publishing commit: github.com/vernikr/browser-agent/tree/47f46e30e1c2ef9b22aa2834276e08d968d9fd5a

Workflow

Publishing configuration: github.com/vernikr/browser-agent/blob/47f46e30e1c2ef9b22aa2834276e08d968d9fd5a/.github/workflows/release.yml
Publishing logs: github.com/vernikr/browser-agent/actions/runs/38144629092/attempts/1

Artifact

Subject: browser_agent_server-1.0.20-py3-none-any.whl
SHA-256 checksum: 338ce10fe9e802605bd878bfb4df545947ddfbaaebacb577296a42c52b31e204 Verifying attestations