browser-agent-server 1.0.0__py3-none-any.whl

browser_agent_server-1.0.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: browser-agent-server
+Version: 1.0.0
+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).

browser_agent_server-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+browser_agent/__init__.py,sha256=YPQ6SBFXoAni-FWe1zwyvZjYkIv2SAbMjqVJ_9qhDUM,4570
+browser_agent/chrome.py,sha256=J8XNMZ-WZnh37Ms7jdzaNXz_kBh1XaKCpxuknornM78,23429
+browser_agent/cli.py,sha256=DNJzJednC0UkMKC8oz6TpIu6SG-kFo4ba3-0399lLJ0,18618
+browser_agent/server.py,sha256=ELGebWieDjwOv2GBOKuPV-n2R_aaevJPanvCQgUDRTs,10013
+browser_agent/vision_agent.py,sha256=g0r68mXiT5Yj4lMQVNpNny5TeGyqPeQRoQsCrjuemQo,6576
+browser_agent/x11_input.py,sha256=gIcqTVI5G-PCVQSII3Hblr2p9ZYPukkOhrphyCGlDqI,9542
+browser_agent/data/browser-agent.service,sha256=UVwkaJ6PulivAh09bCeWaPtdiVtfnERZWxe6zB2weJ8,803
+browser_agent_server-1.0.0.dist-info/METADATA,sha256=qBzpcQOhCz6jU1uQLNBd61gFG3GitQ__tDnZGFUC4Eg,5093
+browser_agent_server-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+browser_agent_server-1.0.0.dist-info/entry_points.txt,sha256=UAxTht6mKig6IcWZ5VzGzhIauEB11Kn0-5LopJkArTM,57
+browser_agent_server-1.0.0.dist-info/licenses/LICENSE,sha256=Ac7u3EmsgsGa5fEVltTYwg9FD1DzqDontGH6o8X0WWM,1064
+browser_agent_server-1.0.0.dist-info/RECORD,,

browser_agent_server-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

browser_agent_server-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+browser-agent = browser_agent.cli:main

browser_agent_server-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vernikr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.