> browser-rs — agent setup runbook
> Source: https://browser-rs.lukaloehr.com/setup.txt
> Project: https://github.com/luka-loehr/browser-rs
> Made by Luka Löhr — https://lukaloehr.com

You are installing browser-rs for the user: a Rust MCP server that gives agents
a bundled Chromium with Playwright MCP's tools plus faster ways to read pages
and a live hand-off to the user.

--------------------------------------------------------------------------------
RULES
--------------------------------------------------------------------------------

- Work autonomously, but ask before changing an existing MCP entry.
- Back up the MCP config before editing it and say where the backup is.
- Verify with a real page. An entry in a config file is not evidence it works.
- A Rust toolchain is required. If `cargo` is missing, point at https://rustup.rs
  and stop; do not install a toolchain without asking.
- Keep the checkout somewhere stable: the MCP entry points at the binary inside
  it.

================================================================================
STEP 0 — ASK THIS FIRST, ALONE
================================================================================

    "Which MCP client should browser-rs be added to — Claude Code, Claude
     Desktop, or something else? And do you already use a browser MCP server
     (for example Playwright MCP) that it should replace or sit next to?"

Wait for the answer.

================================================================================
STEP 1 — CHECK THE MACHINE
================================================================================

    uname -sm
    cargo --version

macOS (Apple Silicon or Intel) is tested. Linux x86_64 / arm64 uses the same
code but is untested: say so. Windows is not supported: stop and tell the user.

================================================================================
STEP 2 — BUILD
================================================================================

    git clone https://github.com/luka-loehr/browser-rs ~/browser-rs
    cd ~/browser-rs && cargo build --release

The binary is ~/browser-rs/target/release/browser-rs (about 9.5 MB).

================================================================================
STEP 3 — INSTALL CHROMIUM ONCE (optional, otherwise it happens on first use)
================================================================================

    ~/browser-rs/target/release/browser-rs install

This downloads Chrome for Testing: chrome-headless-shell (~99 MB) for headless
work and the full browser (~191 MB). They are cached in
~/Library/Caches/browser-rs (macOS) or ~/.cache/browser-rs (Linux).

================================================================================
STEP 4 — REGISTER THE SERVER
================================================================================

Claude Code:

    claude mcp add browser-rs ~/browser-rs/target/release/browser-rs

Add `-- --caps all` at the end for cookies, storage, network mocking, tracing,
video, PDF and testing tools (79 tools instead of 34).

Other clients, in mcpServers:

    "browser-rs": { "command": "/ABSOLUTE/PATH/browser-rs/target/release/browser-rs" }

If the user keeps Playwright MCP too, both work side by side; the tool names are
the same, so tell the user which server they are calling.

================================================================================
STEP 5 — VERIFY WITH A REAL PAGE
================================================================================

Restart or reconnect the client, then call:

    browser_navigate  { "url": "https://example.com", "snapshot": "none" }
    browser_text      { "lead": 1 }

Expect "Navigated to https://example.com/ (HTTP 200)" and the page's first
paragraph. Report both results and elapsed_ms to the user.

================================================================================
STEP 6 — TELL THE USER HOW TO WORK WITH IT
================================================================================

- It runs headless: no window appears.
- When a login, 2FA or CAPTCHA needs a person, the agent calls browser_handoff:
  a tab opens in the user's own browser with the live page; they act, then
  click "Done — hand back to agent". Nothing reloads.
- Limits in that view: native dropdowns and file pickers are not drawn by
  headless Chromium, and passkeys do not work (use a code or password).