Bruster

bruster

Native webview browser driven by an agent over JSON lines on stdio.

WKWebView · WebKitGTK · WebView2. A small Rust executable using native browser runtimes. No Node required.

Install · Quickstart · MCP · Protocol · API · Performance

bruster uses native browser engines, installed separately where required. Its Rust controller reads and writes JSON lines on stdin and stdout; rendering also uses browser helper processes. This design is good for agents, scripts, and test harnesses. The --mcp option exposes every method as a tool.

Why bruster?

• No Chromium. bruster uses WKWebView on macOS, WebKitGTK on Linux, and WebView2 on Windows. It uses wry to control them.
• Small controller. One small release executable, with a separately installed native browser runtime. The complete runtime footprint includes its libraries and helper processes.
• Agent support. MCP support with --mcp. Screenshots return as image content, and page events return as notifications.
• Cross-platform. Prebuilt for macOS (arm64, x86_64), Linux (x86_64, arm64), and Windows (x86_64).
• Practical API. Navigate, snapshot, click, fill forms, drag, upload, take screenshots, inspect the network and console, manage tabs, and keep a session with --profile.
• Deterministic and safe. Each call is one line-based JSON request and response. beforeunload is disarmed, and dialogs never block.
• Fast. A persistent HTTP cache and profiles make repeat visits faster. The first tab loads about:blank while the agent starts.

[!TIP] Live benchmarks compare Bruster with the latest stable Playwright, Puppeteer, and agent-browser after every merge to main: startup, navigation, extraction, screenshots, total process memory, and installed runtime files. See benchmark setup and methodology.

Install

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/aliilyas/bruster/main/install.sh | sh

The script installs the correct build for your OS and CPU into ~/.local/bin.

Prebuilt releases

Download archives for all platforms from the Releases page.

From source

cargo build --release

[!NOTE] Linux requirements. WebKitGTK 4.1 is necessary at run time. Install it with one of these commands: apt install libwebkit2gtk-4.1-0, apk add webkit2gtk-4.1, or dnf install webkit2gtk4.1. If the system has no desktop session, bruster starts again under xvfb-run -a when DISPLAY is not set.

Quickstart

Run bruster in its native protocol mode:

bruster

Then send JSON objects, one per line:

{"id":1,"method":"navigate","params":{"url":"https://example.com"}}
{"id":2,"method":"snapshot"}
{"id":3,"method":"click","params":{"ref":"e2"}}
{"id":4,"method":"close"}

You receive the results and events on stdout:

{"event":"load","tab":1,"url":"https://example.com/"}
{"id":1,"result":{"url":"https://example.com/"}}
{"id":2,"result":{"url":"https://example.com/","title":"Example Domain","elements":[...]}}
{"id":3,"result":null}

MCP

With --mcp, bruster uses the Model Context Protocol on stdio. Every native method becomes a tool. Screenshots return as image content, and page events return as notifications.

Common MCP client configs

// opencode (opencode.json), Claude Desktop (claude_desktop_config.json),
// Cursor (.cursor/mcp.json), Windsurf, Zed
{ "mcpServers": { "bruster": { "command": "bruster", "args": ["--mcp", "--quiet"] } } }

claude mcp add bruster -- bruster --mcp --quiet          # Claude Code
codex mcp add bruster -- bruster --mcp --quiet           # Codex CLI

// VS Code (.vscode/mcp.json)
{ "servers": { "bruster": { "type": "stdio", "command": "bruster", "args": ["--mcp", "--quiet"] } } }

--mcp keeps the windows off-screen. Add --visible to see the browser. --hidden is not true headless mode: on Linux, WebKitGTK still requires an X11/Wayland display or Xvfb. When no display is set, Bruster automatically tries xvfb-run; install Xvfb if it is unavailable.

On Linux, hidden/MCP mode skips the desktop session bus to avoid waiting for unavailable desktop portals. Set BRUSTER_USE_SESSION_BUS=1 if you need desktop session integration in hidden mode. --visible uses the normal session bus.

Run

bruster [--mcp] [--hidden|--visible] [--quiet] [options]

Window and color controls

Native commands and MCP tools minimize and maximize target the specified tab (or the current tab), return "minimized" or "maximized", and persist the requested window mode. Each mode replaces the previous one. minimize hides the native window (rather than iconifying it); maximize restores visibility and maximizes. In hidden/MCP mode both commands are accepted and saved, but windows stay off-screen for rendering.

dark and light persist a color preference independently of window mode and apply it to all existing tabs, new tabs, and subsequent navigations. The portable page-level fallback sets the root CSS color-scheme (including native controls and default page colors); it does not emulate prefers-color-scheme media queries or recolor a site's explicit colors. Custom --init-script scripts still run.

Preferences are stored outside WebView data. With --profile PATH, metadata is a sibling of the canonical profile directory, named PATH.bruster-window.json. Without a profile, the file is:

• Linux: $XDG_STATE_HOME/bruster/window.json, falling back to $HOME/.local/state/bruster/window.json.
• macOS: $HOME/Library/Application Support/bruster/window.json.
• Windows: %LOCALAPPDATA%/bruster/window.json.

Settings are profile-wide; the last successful command wins. Missing or malformed metadata uses defaults, and legacy window-only state files are still accepted. Persistence failures return protocol errors. OS window-manager changes are not saved. close shuts down the server and all tabs; close_tab or closing a window through the OS closes only that tab. Closing stdin also shuts down the server.

Linux uses software rendering. Hidden views skip off-screen GTK painting while remaining mapped for layout, animation, and native screenshots. Set BRUSTER_PAINT_HIDDEN=1 to enable those window paints. Hidden mode also defaults WEBKIT_DISABLE_DMABUF_RENDERER=1 to avoid an unnecessary graphics transport probe; an explicitly supplied value (including 0) takes precedence.

Automatic Xvfb launches disable GLX. BRUSTER_XVFB_ARGS overrides the server arguments (default: -screen 0 1280x1024x24 -nolisten tcp -extension GLX). Set BRUSTER_NO_XVFB=1 to prevent automatic Xvfb startup.

Tests

tests/run_all.sh [--rounds N] [--no-e2e] runs the full suite. The suite does a build, unit tests, smoke tests, edge tests, a leftover-process check, an MCP launch check, and end-to-end tests. On Linux, run the script under xvfb-run -a. CI builds and tests every platform. CI also publishes release archives on v* tags.

The Linux desktop-portal startup regression requires D-Bus, python3-dbus, and python3-gi:

cargo build --release --locked
xvfb-run -a /usr/bin/python3 tests/startup_portal.py target/release/bruster

Protocol

One JSON object per line, in both directions. Elements are addressed by {"selector": "css"} or by {"ref": "eN"} from the last snapshot/find. With format: "text", a snapshot returns one line per element:

https://example.com/
Example Domain
e1 heading "Example Domain"
e2 text "This domain is for use in..."
e3 link "Learn more" href=https://iana.org/help/example-domains
e4 checkbox "Remember me" checked=false

[!NOTE] Same-origin hrefs lose the origin in the text format. Alert and prompt dialogs never block. bruster answers them as the current dialog setting specifies, and reports them as dialog events. beforeunload handlers are disarmed.

Calls routed through the page runtime (eval, url, title, snapshot, interactions and other DOM tools) have an outer request_timeout in milliseconds, defaulting to at least 30000 ms (or the requested timeout/time plus 5000 ms, whichever is longer). This deadline includes time spent waiting for navigation. Set it explicitly for unusually long operations. A timeout stops waiting for the reply; it does not interrupt JavaScript already running in the page. In particular, an infinite loop can make a web process unresponsive and may require restarting bruster. Late replies are discarded. Navigation uses its own timeout; native operations such as screenshots do not use request_timeout. MCP represents null results as the text null.

API

Events

ready, navigating, load, tab_opened, tab_closed, dialog (type, message, accept), tls_error (Linux), load_failed, and download (Linux).

Limits

• Input uses synthetic DOM events (isTrusted is false). You do not get :hover styles, native <select> popups, or OS-level shortcuts.
• Network and console logs are patched in the page and reset on navigation. Network entries for fetch/XHR include status and an index; other resources use performance timings and may lack status or method. The document request is not included. Logs contain no request bodies. Use --proxy for real interception.
• Cross-origin iframes are out of reach. Same-origin iframes and open shadow roots work.
• Use HTTP(S) URLs for navigation. data: and file: URLs are unsupported; serve local pages over localhost instead.
• bruster does not intercept native file choosers. Use upload instead of a click on a file input.
• Without --profile, cookies and storage last for one session.
• Full-page screenshots are capped at 16000 px. On macOS, very tall pages can be cut when they are higher than the screen.
• WebKitGTK screenshots capture page content without non-overlay scrollbars, so their width can be narrower than the window viewport.
• On Windows (WebView2), screenshot has no clip. --quiet does nothing. The Linux-only flags have no effect.
• With --hidden, WebKit timer throttling can make setTimeout-driven pages slow.

Development

• bin/bruster runs the development build from this checkout.
• tests/run_all.sh runs the build, unit tests, smoke tests, edge tests, the MCP launch check, and end-to-end tests.
• CI (.github/workflows/ci.yml) builds all platforms, runs the tests, and publishes release archives on v* tags.
• Benchmarks: scripts/bench_compare.py compares five configurations; scripts/bench_footprint.py inventories runtime files and scripts/bench_report.py validates and publishes results. See setup and methodology.

License

MIT License