Metadata-Version: 2.5
Name: browser-agent-server
Version: 1.0.1
Summary: Real headful Chrome on Xvfb with a hardware-level X11 mouse, Cloudflare Turnstile auto-solve and zero-leak CDP. Localhost HTTP API + CLI + Python SDK.
Project-URL: Homepage, https://github.com/vernikr/browser-agent
Project-URL: Repository, https://github.com/vernikr/browser-agent
Project-URL: Issues, https://github.com/vernikr/browser-agent/issues
Author: vernikr
License: MIT
License-File: LICENSE
Keywords: automation,browser,chrome,cloudflare,mcp,stealth,turnstile,x11
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: trafilatura<3,>=1.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# browser-agent

> 🔗 **Companion project:** [`@vernikr/browser-agent-mcp`](https://github.com/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`](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)

```bash
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:

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

```python
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:

```bash
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`](docs/deployment.md) — provisioning, systemd, memory limits, WARP, VNC logins
- [`docs/api.md`](docs/api.md) — HTTP contract (v1)
- [`docs/architecture.md`](docs/architecture.md) — how and why it works
- [`docs/security.md`](docs/security.md) — trust boundaries (loopback-only, no auth)
- [`docs/troubleshooting.md`](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`](https://github.com/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](https://github.com/vernikr/browser-agent-mcp) and talk to a Linux host running this daemon.

## License

MIT — see [LICENSE](LICENSE).
