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 indocs/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
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 loginsdocs/api.md— HTTP contract (v1)docs/architecture.md— how and why it worksdocs/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
Self-check: browser-agent doctor --json (exit 0 = host ready).
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.
1 maintainer
Metadata
1 maintainer
Release files for browser-agent-server 1.0.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| browser_agent_server-1.0.8.tar.gz | 109.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| browser_agent_server-1.0.8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 144.3 kB
Release files / browser_agent_server-1.0.8.tar.gz
| Download URL | browser_agent_server-1.0.8.tar.gz |
|---|---|
| Size | 109.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
edca59ca50d562f0027ef1cbe2da91ffd929f890ffe58352fef49b6cd0c4bc73
|
|
BLAKE2b-256 checksum How to use checksums |
221914c89246c22eb47bf851c4f77d38199103b6292de551ee6e4e28012fb76b
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.
Transparency logRelease files / browser_agent_server-1.0.8-py3-none-any.whl
| Download URL | browser_agent_server-1.0.8-py3-none-any.whl |
|---|---|
| Size | 34.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
06165239b1c95a39ce58e6763db9404f9250f4cf3a399e20881e4e49696fff6f
|
|
BLAKE2b-256 checksum How to use checksums |
65cb8bf15e2bf2f7ca3344f9756a7f7b7abfb71330787fc1744cd3edd0d079c0
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.
Transparency log
