browserr

A Servo-based browser engine built for AI agents: headless by default, with an optional native interactive window for human handoff.

Browserr is an alternative to embedding Chromium in an agent stack: a single engine binary (Rust + Servo) that renders pages, blocks ads, and exposes a small loopback protocol. It is built around three commitments: block when unsure, hand the page to a human when a human is needed, and leave evidence for everything it did.

Rendering is CPU by default; --gpu opts into hardware rendering. --headed opens a real interactive native window and requires a desktop with graphics support. It runs on Windows, Linux (x64/ARM64) and macOS.

Agents drive it through a Python SDK or through any MCP-capable client. The automation surface is deliberately small: the entire protocol is auditable in an afternoon, unlike CDP.

Why Browserr

Most agent browsers embed Chromium and speak CDP behind the scenes. Browserr is a purpose-built engine for the job instead, with the product decisions that follow from owning the whole stack:

• Fail-closed by default. When Browserr is unsure, it blocks instead of guessing. Intercepted requests are held for a decision and denied after 5 s. Auth challenges with no stored credentials are refused outright. Submitting a payment or CAPTCHA page needs an explicit human confirm.
• Humans are part of the workflow, not a fallback. detect_handoff() spots CAPTCHAs, one-time codes and payment fields. pause() hands the page to a person while the agent keeps watching; wait_for_user returns the moment control can come back. Annotated screenshots number every element, so a human and an agent can point at the same e7.
• Every action leaves evidence. Timestamped screenshots plus an append-only action log, per profile. Credentials are stored per host and never written to logs, so a big claim is backed by a saved screenshot instead of a promise.
• Runs where Chromium cannot. CPU rendering by default: instant start on GPU-less machines, containers, CI runners and a Raspberry Pi 4/5 (ARM64 builds included).
• MCP-native, not wrapper-native. All 42 tools surface directly to any MCP-capable agent. No CDP quirks, no driver downloads, no version drift.
• SPA-ready. Modern JS syntax, fetch/WebSockets/Workers, custom elements, shadow DOM, React 18 + Vue 3 verified rendering, plus IntersectionObserver, IndexedDB, Web Animations, WebGL2, crypto.subtle digests and requestIdleCallback (the last two via built-in shims where servo omits them).
• Honest about its limits. Web compatibility is bounded by Servo 0.8: text, documents, search, forms and common SPA patterns work well; DRM video, WebRTC and service-worker-dependent offline apps do not. If you need those, or fleet scale or residential proxies, a cloud provider is still the better tool. Browserr wins on local, trust-first, human-in-the-loop work.

Features

Page engine

• Servo 0.8 rendering, CPU by default (instant start on GPU-less machines, containers, CI); --gpu opts into hardware GL with automatic CPU fallback
• SPA compatibility: React 18 and Vue 3 render and react; all modern ES syntax; fetch/WebSockets/Workers/custom elements/shadow DOM; IntersectionObserver, IndexedDB, Web Animations, WebGL and WebGL2 (via ANGLE, so it works on GPU-less machines too), clipboard and DecompressionStream; requestIdleCallback and crypto.subtle digests (SHA-1/256/384/512) via built-in shims where servo omits them
• Tabs, navigation, per-tab history, zoom, pointer/wheel/keyboard input
• JavaScript evaluation with results returned as JSON
• On-demand screenshots of the active tab; the SDK saves them as PNG
• Console capture: page messages plus network and TLS load errors
• Downloads fetched straight to disk, without page cookies
• EasyList-based adblock, refreshed weekly

Reading pages

• read_page(): token-cheap prose extraction
• read_structure(): every interactive element with its rect, selector and a stable ref (e7); fields carry label, constraints, state and validity; shadow DOM included. Refs are scoped to each read_structure() snapshot; after navigation or a refresh, read again. MCP reports stale refs as errors

Acting on pages

• Selector interaction: click_element, set_value (React/Vue-safe), wait_for_selector
• Ref interaction: click_ref, set_field, fill_form - stable refs, no selector fragility; a whole form in one round trip, with type-aware writes that fire input/change/blur once so page validators run
• Submit cycle: submit_form runs the page's own validation, then read_outcome reports the url, alert texts and invalid fields
• File uploads: picker events answered with local file paths

Network control

• Fail-closed interception: requests are held for an allow / deny / respond decision; unanswered requests deny after 5 s
• Net evidence: every fetch/XHR recorded in a ring buffer, in every frame
• Auth challenges surface as events; wrong or missing credentials fail closed
• Frame tree listing (cross-origin frames report their url only)

Human in the loop and trust

• detect_handoff(): spots CAPTCHAs, one-time codes, empty passwords, payment fields and consent walls
• pause() / resume(): mutating actions fail loudly while a human has control; reads keep working. MCP browser_wait_for_user completes only on navigation or an observed handoff clearing, never on a clean first scan
• Real human handoff: browser_start({headed: true}) shows the native window; mouse and keyboard input still work while MCP actions are paused
• Annotated screenshots: every element boxed and numbered by ref, so an agent and a human point at the same element
• Persistent profiles: logins survive sessions
• Evidence: timestamped screenshots plus an append-only action log; credentials are never logged
• Credential store: auth challenges answered automatically for known hosts, denied for unknown ones
• Confirm gate: submitting a payment or CAPTCHA page needs an explicit human confirm

Operations

• ping health check; fast failure when the engine dies
• Ephemeral throwaway profiles for per-run isolation
• Concurrent driver clients over --driver-port, optional token authentication

Requirements

• Python 3.10+ for the SDK and MCP server (standard library only)
• Rust stable only if you build from source

Install

Download the archive for your platform from releases and unpack it anywhere (no admin rights, no installer). You get:

engine(.exe)      the headless browser engine
libEGL.dll        ANGLE GL for WebGL (Windows archives only)
libGLESv2.dll     must stay next to engine.exe
driver.py         Python SDK (stdlib only)
browserr_mcp.py   MCP server (stdlib only)
mcp_wrap.cmd      Windows MCP launcher (cmd wrapper)
README.md, LICENSE

Requirements: Python 3.10+ on PATH. driver.py finds the engine binary next to itself; override with BROWSERR_ENGINE=/path/to/engine.

Connect an MCP client (Kai, Claude Desktop, ...)

Add the Browserr server in your client's MCP settings:

{
  "mcpServers": {
    "browserr": {
      "command": "python",
      "args": ["C:/path/to/browserr/browserr_mcp.py"],
      "cwd": "C:/path/to/browserr"
    }
  }
}

On Windows, you can also point the command at the bundled wrapper:

{
  "mcpServers": {
    "browserr": {
      "command": "C:/path/to/browserr/mcp_wrap.cmd",
      "cwd": "C:/path/to/browserr"
    }
  }
}

The server spawns its own engine (ephemeral profile) on first tool use; browser_stop shuts it down. To share one engine across sessions, start it yourself with a driver port and attach instead:

engine --ephemeral --driver-port=7412 --driver-token=secret

{ "mcpServers": { "browserr": {
    "command": "python",
    "args": ["C:/path/to/browserr/browserr_mcp.py", "--port", "7412", "--token", "secret"]
} } }

Use the Python SDK

import sys; sys.path.insert(0, "tools")
from driver import Driver, save_png

d = Driver(ephemeral=True)          # spawns the engine, throwaway profile
try:
    d.navigate("https://example.com"); d.wait_load(); d.wait_ready()
    print(d.eval_js("document.title"))       # results returned as JSON
    title, text = d.read_page()              # token-cheap prose
    structure = d.read_structure()          # headings/buttons/inputs/...
    d.set_value("#q", "search terms")         # React/Vue-safe
    d.click_element("#go")                    # scrolls into view, real pointer
    w, h, bgra = d.screenshot(); save_png("shot.png", w, h, bgra)
    print(d.ping())                          # {'tabs': 1, 'active': 0}
finally:
    d.close()                                 # socket close = engine exit

Run the MCP server directly

python tools\browserr_mcp.py              # headless, ephemeral profile, MCP on stdio
python tools\browserr_mcp.py --port 7412  # attach to an engine started with --driver-port

Build from source

cargo build --release --manifest-path engine\Cargo.toml

Package a distributable (builds into dist\ and zips it):

powershell -File scripts\package.ps1

Architecture

engine/   Servo webviews (one per tab), CPU-default rendering (--gpu for
          hardware GL), request interception (adblock), automation
          protocol, driver port.
tools/    driver.py (Python SDK), browserr_mcp.py (MCP server), tests.
scripts/  dist/package/ci for Windows (ps1) and Linux (sh).

Protocol

Commands are newline-delimited JSON, tab-addressed, over a