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 to ~12 MB idle).

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; human hold delays 55–125 ms
Cloudflare Turnstile	Detects the interstitial, locates the checkbox via the DOM and clicks it with the real X11 mouse
RAM discipline	`--renderer-process-limit=1`, JS heap capped at 256 MB, tab reset after each fetch, auto-hibernation after idle (default 60 s) ⇒ ~12 MB resting
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.17

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.17
File	Size	Uploaded
browser_agent_server-1.0.17.tar.gz	144.1 kB	Oct 11, 2026	Details

Built distribution (wheel)

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

Total release size: 188.6 kB

Release files / browser_agent_server-1.0.17.tar.gz

Download URL	browser_agent_server-1.0.17.tar.gz
Size	144.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`6d22b9f564a32ef644f71ebf9095d23a320b3f7475a057fd3e3c8f171e5d238a`
BLAKE2b-256 checksum How to use checksums	`f3e44dffb0f01ab5a63dfd752c50925416360ad0f83a0e48b547f1fe4a083324`
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/d659d5351c58264d8ba4e67477971bf82f7e9f07

Workflow

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

Artifact

Subject: browser_agent_server-1.0.17.tar.gz
SHA-256 checksum: 6d22b9f564a32ef644f71ebf9095d23a320b3f7475a057fd3e3c8f171e5d238a Verifying attestations

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

Download URL	browser_agent_server-1.0.17-py3-none-any.whl
Size	44.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`637ff2ccfd0565fe8d99d4334e84464f222bcd5e231a682b0f08f7e021342d9a`
BLAKE2b-256 checksum How to use checksums	`09a98c6270e7788bff0389fbe2d2f174a75d5d38bdaad159244b9c7852e9da6b`
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/d659d5351c58264d8ba4e67477971bf82f7e9f07

Workflow

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

Artifact

Subject: browser_agent_server-1.0.17-py3-none-any.whl
SHA-256 checksum: 637ff2ccfd0565fe8d99d4334e84464f222bcd5e231a682b0f08f7e021342d9a Verifying attestations