Scope
01 / 05
Everything an agent needs. #
Built agent-first: extraction over pixels, stable refs over coordinates, failures you can catch instead of hangs. Three commitments shape the whole engine: it blocks when unsure, it hands the page to a human when a human is needed, and it leaves evidence for everything it did.
| Command | Covers |
|---|---|
| read | Structured page reads. Prose via read_page(), or read_structure(): every element with its rect and selector; fields carry label, constraints, state and validity. |
| act | Selector interaction. click_element() and set_value() — real pointer events, React/Vue-safe writes. |
| wait | SPA-aware timing. Wait for selectors and readiness — no sleeps, no flaky scripts. |
| observe | Console capture. Page messages and network errors arrive as events. |
| files | Downloads. Fetched straight to disk, without page cookies. |
| survive | Fast failure, not hangs. A dead engine surfaces instantly; ephemeral profiles give every run a clean slate. |
| block | Adblock built in. EasyList-based, refreshed weekly. |
| gpu | Rendering. CPU by default — starts anywhere; --gpu opts into hardware. Screenshots on demand, per tab. |
| compat | SPA-ready. React 18 and Vue 3 render and react; IntersectionObserver, IndexedDB, Web Animations, WebGL and WebGL2 (via ANGLE, no GPU needed), clipboard, DecompressionStream; requestIdleCallback and crypto.subtle digests via built-in shims where Servo omits them. |
| secure | Token-gated attach. Unauthenticated sockets get nothing — not even events. |
| intercept | Fail-closed interception. Requests held for an allow / deny / respond decision; unanswered means denied after 5 s. |
| auth | Challenges surfaced, not swallowed. Auth and file-picker events; missing credentials fail closed. |
| evidence | Net evidence. Every fetch/XHR recorded in a ring buffer, in every frame. |
| frames | Frame tree. List frames and walk same-origin ones; cross-origin frames report their url only. |
| fill | Form filling. A whole form in one round trip, with type-aware writes. |
| submit | Submit and read the outcome. Runs the page's validation, then reports url, alerts and invalid fields. |
| point | Shared references. Stable refs and numbered screenshot boxes: the agent says "click 7" and the human knows which one that is. |
| proxy | Upstream proxy routing. browser_start(proxy=...) routes all http/https traffic through a CONNECT tunnel (basic auth in the URL, per-engine rotation); document_status reports the main document's real HTTP status so a block serving a fake 404 is distinguishable from a dead page. |
| handoff | Humans take over in a real native window. Start MCP with headed:true; direct mouse and keyboard input keep working while agent mutations are d. CAPTCHA support still depends on Servo compatibility. |
| trust | Fail-closed by design. Persistent profiles, evidence shots, an append-only action log, a credential store and a confirm gate on payment submits. |
Protocol
02 / 05
The entire protocol, in full. #
JSON over loopback. One client, no hidden state — the opposite of CDP's 1000+ endpoints. Events:
- Commands
- 22
- MCP tools
- 42
- Binary
- ~120 MB
- CDP endpoints
- 0
- Dependencies
- 0
SDK
03 / 05
Three ways in. #
Same engine underneath; pick the integration you already have.
| Surface | Covers |
|---|---|
| mcp | Model Context Protocol server with 42 tools, stdlib only. Any MCP-capable agent — Claude, Kai, your own — drives Browserr with zero integration code. |
| python | driver.py wraps the raw protocol: navigation, extraction, form filling, screenshots. No dependencies. |
| raw | Anything that can write JSON lines to a socket. Bindings in any language are an afternoon. |
Position
04 / 05
Where it sits in 2026. #
Chromium wrappers are the default; alternative engines are the bet. Browserr's edge is the local, trust-first, human-in-the-loop.
| | Browserr | Lightpanda | Obscura | Chromium headless |
|---|---|---|---|---|
| engine | **Servo** | own (Zig) | own (Rust) | Blink |
| js engine | SpiderMonkey | own | own | V8 | | mcp-native | yes, 42 tools | no | partial | via wrappers | | protocol size | 22 commands | CDP-compatible | own + CDP | 1000+ endpoints | | footprint | one ~120 MB binary | ~16× less than Chromium | ~30 MB | ~200 MB+ | | web compat | Servo 0.8 (text, docs, forms, SPAs) | growing | growing | full | | human handoff | native window, , wait_for_user | headless only | headless only | via wrappers | | trust layer | evidence, action log, confirm gate | no | no | no | | network policy | fail-closed, held to a decision | CDP opt-in | CDP opt-in | CDP opt-in |
Install
05 / 05
Get Browserr in seconds. #
One package per platform: the engine binary, Python SDK, and the MCP server.
Windows x64
Download the zip, unpack anywhere, and point your agent at the MCP server. CPU rendering works out of the box; pass --gpu for hardware rendering.
Linux x64 / ARM64
Download the tarball, unpack anywhere, and point your agent at the MCP server. Works headless without a GPU; ARM64 covers the Raspberry Pi 4/5.
macOS (Apple Silicon)
Download the tarball, unpack anywhere, and point your agent at the MCP server. Works headless out of the box.
↓ Download for macOS Start
Start driving the web with your agents. #
Free, open source, no account, no telemetry. Runs on every machine.