BrowserRig

BrowserRig — Agents, meet your real browser

BrowserRig lets trusted coding agents run Playwright against your existing Chromium-family browser. It uses your real browser profile, including logged-in sessions and installed extensions, instead of launching a separate headless browser.

BrowserRig is the independent open-source product—not an authorization middle layer for another browser-agent ecosystem. It is derived from the MIT-licensed upstream driver while owning its CLI, npm, extension, and Store identity.

Why BrowserRig

It is built for the awkward gap between browser automation and a person's daily browser:

Your real, signed-in browser. Reuse the Chrome window, cookies, sessions, and extensions you already have.
No blocking remote-debugging approval. BrowserRig does not connect to Chrome's browser-wide remote-debugging endpoint, so it does not trigger the recurring Allow remote debugging? dialog.
No toolbar click for the active tab. session adopt --active finds, attaches, and adopts the active tab in the last-focused browser window in one command.
Background work that keeps your focus. A normal execute creates a background tab in the same browser profile instead of switching the visible tab or launching another browser.
A complete local driver, not an agent wrapper. The CLI, Playwright execute sessions, MCP server, recording, network capture, and human handoff remain available without bundling an LLM or requiring a hosted service.

How BrowserRig compares

BrowserRig combines an open-source, CLI/skill-first driver with durable access to the signed-in browser you already use. The comparison below focuses on that core workflow.

Capability	BrowserRig	Kimi WebBridge	agent-browser	Chrome DevTools MCP
Open-source core	✅	❌	✅	✅
CLI / skill-first	✅	✅	✅	❌
MCP-first; tool schemas consume context
Reconnect to your signed-in Chrome without another browser approval	✅	✅	❌
Reconnects and browser restarts can require another “Allow remote debugging?” click	❌
Each auto-connect attempt requires Remote Debugging approval

The extension still uses Chrome's debugger API to carry CDP commands. The difference is the transport and authorization scope: extension attachment instead of Chrome's browser-wide remote-debugging connection. Chrome may show its standard non-blocking debugging infobar while a tab is attached, but no per-tab approval click is required.

Agent (DSH plugin, CLI, or MCP) -> local relay -> browser extension -> your browser

The driver runs locally and does not contain an LLM or make planning decisions. Its primary interface is code: an agent sends a Playwright snippet and receives the result, logs, warnings, and a summary of what changed.

Quick Start

BrowserRig requires Node.js 22.22.0 or newer and a Chromium-family browser such as Chrome, Brave, Edge, Arc, or Chromium.

Setup has two required parts: connect BrowserRig to the agent runtime you use, then install the browser extension. DeepSeek Harness uses the native DSH bundle; other coding agents can use the CLI skill or MCP server.

1. Connect your agent

DeepSeek Harness

The root browserrig package follows DSH's official bundle installation model. Install it into the DSH profile you run, then inspect the composed layer:

dsh plugin --profile web add browserrig
dsh --profile web --dump-config

This route needs neither a global browserrig CLI nor a separately installed BrowserRig skill. The bundle carries its matching package-local CLI runtime, six typed browserrig_* tools, and concise operating guidance. It binds one persistent BrowserRig session to each DSH agent session without exposing or asking the model to remember BrowserRig session IDs.

CLI and skill-driven agents

Install the independent package globally:

npm install --global browserrig

This installs browserrig for CLI and skill-driven agents and browserrig-mcp for MCP clients.

The packaged skill teaches coding agents how to inspect before acting, preserve session identity, handle human-only steps, and recover from browser failures. Install it with the skills CLI:

npx skills add Castor6/BrowserRig --skill browserrig -g

Choose the agents you use when prompted. The global -g installation makes the skill available across projects.

Castor6/BrowserRig is BrowserRig's independent repository identity. BrowserRig does not edit agent configuration itself. To inspect or install the skill manually, print the exact bundled text:

browserrig skill

Optional MCP server

The skill and MCP server do different jobs. The skill teaches the workflow; MCP exposes BrowserRig as tools. Agents that can run shell commands need only the skill. Add MCP when your client prefers MCP tools.

For OpenCode:

// opencode.json
{
  "mcp": {
    "browserrig": {
      "type": "local",
      "command": ["browserrig-mcp"]
    }
  }
}

For Claude Code:

claude mcp add browserrig -- browserrig-mcp

CLI and MCP clients share the detached relay, but each execute session keeps its own default page and persistent JavaScript state. Restarting an MCP process does not stop the relay or interrupt an active CLI session.

2. Install the extension

Install BrowserRig from the Chrome Web Store, then optionally pin its toolbar button for manual attach/detach. Store installs receive extension updates automatically after each new version passes Chrome Web Store review.

For source development or a browser that cannot use the Store listing, load the packaged development build instead:

Print the extension directory for the installation route you chose:

# DeepSeek Harness profile (replace web if you use another profile)
printf '%s\n' "${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/browserrig/extension/dist"

# Global npm installation
printf '%s\n' "$(npm root --global)/browserrig/extension/dist"

Open chrome://extensions or your browser's equivalent, such as brave://extensions.
Enable Developer mode.
Select Load unpacked and choose the printed directory.
Optionally pin the BrowserRig toolbar button for manual attach/detach.

3. Run your first browser command

Start the configured DSH profile and ask its agent to use BrowserRig:

dsh --profile web

For a direct CLI installation, verify it with:

browserrig execute 'await page.goto("https://example.com"); return { title: await page.title(), url: page.url() }'

Both routes start the same detached local relay when needed and open a background tab in your existing browser profile. Direct CLI calls print a readable session ID with the exact --session command needed to continue; the DSH plugin keeps that continuity internal. The relay listens on 127.0.0.1:19990 and stays running between calls.

A successful run returns the Example Domain title, a generated session ID, and a continuation command. browserrig status then reports the extension as connected.

Check the installation at any time with:

browserrig doctor
browserrig status

doctor and status are read-only. They report a stopped relay but never start one. Use browserrig serve only for foreground debugging.

Native DeepSeek Harness Integration

The DSH bundle is a thin, native adapter over BrowserRig rather than a second browser driver or an MCP wrapper. It contributes these tools directly to DSH:

browserrig_execute runs Playwright JavaScript in the DSH session's persistent page and returns structured values, logs, warnings, aftermath, and DSH image attachments when available.
browserrig_adopt_active adopts the user's active signed-in tab directly.
browserrig_status reports readiness and only this DSH session's projected browser state.
browserrig_reset resets that session without closing an adopted user tab.
browserrig_journal reads its recent BrowserRig execute history.
browserrig_issue_report records a sanitized BrowserRig product or operational issue without exposing the internal session id.

Each DSH agent session maps durably to one BrowserRig session at the configured relay endpoint. First use creates the mapping atomically; an explicitly missing BrowserRig session is replaced once, while unrelated DSH tasks remain isolated. Only the stable session-not-found code permits that replacement; active-worker, ownership, endpoint, persistence, and other failures preserve the mapping. Internal BrowserRig IDs and the global target list are not returned to the model.

The adapter invokes the CLI shipped in the same npm package with fixed argument arrays, validated JSON envelopes, bounded output, and DSH cancellation. There is no arbitrary shell or CLI passthrough, no separate global executable to drift out of version, and ambient CLI session or target selectors cannot override the DSH task binding. There is also no duplicate click/fill/navigation micro-tool layer. Direct CLI, MCP, and library users remain independent of DSH.

Experimental WebMCP

Enable native website tool discovery in the environment of the agent calling BrowserRig (off by default):

export BROWSERRIG_EXPERIMENTAL_WEBMCP=true
browserrig execute 'await page.goto("https://googlechromelabs.github.io/webmcp-tools/demos/pizza-maker/"); return page.title()'

The execute response includes a webmcp discovery field with tool ids, names, descriptions, input schemas, and frame identities. Use the returned session id to continue. For an existing user tab, adopt it first. Discovery covers the current session-owned page, including its attached iframe targets.

const { tools } = await webmcp.list();
const tool = tools.find(tool => tool.name === "set_pizza_size");
if (!tool) throw new Error("The page has no set_pizza_size tool");
const result = await webmcp.call(tool.id, { size: "Small" });
return { result, size: await page.locator("#size-text").innerText() };

Set the same environment variable in an MCP server's env configuration or before launching DSH. Each execute request carries its own setting, so it also works with an already-running shared relay. No additional MCP micro-tools or extension update is needed.

Definitions are included automatically on first discovery and after changes. Unchanged responses carry changed: false without repeating the definitions. webmcp.list({ offset, limit }) explicitly refreshes a page of definitions, also included in that execute's discovery field. Follow nextOffset to page through large lists. Automatic output is limited to 25 tools / 128 KiB; explicit lists allow up to 100 tools. The registry retains up to 256 tools / 1 MiB, with a 64 KiB limit per definition, and reports omittedTools when capped.

Tool ids expire on registration changes, document navigation, detach, and reconnect. Re-list before using an old id. Calls return Chrome's Completed, Canceled, or Error status; verify the page outcome as well. Calls accept { timeoutMs, signal } (30 seconds by default, up to 10 minutes). Declarative forms that require manual submission automatically enter the existing human handoff flow, with a 10-minute default. Cancellation is cooperative and does not undo website changes. Inputs and outputs are limited to 1 MiB, and each execute can start up to 32 calls. Normal execute-value limits still apply to values returned from scripts; select relevant fields from large tool outputs.

Read-only sessions can discover tools but cannot invoke them, even when a website marks a tool read-only. Website descriptions and outputs are untrusted content, not instructions or permission to perform actions.

Native WebMCP requires a compatible Chrome and an enabled website. A site with a valid Origin Trial enrollment can enable it without a user changing browser flags. unsupported means the native CDP domain could not be used; unavailable reports a connection or ownership problem. available with no tools means no native tools were discovered, which can include a page that has not enabled the API. BrowserRig does not enable Chrome experiments or convert a site's polyfill into native WebMCP.

For source development, SMOKE_CASE=execute-webmcp pnpm smoke exercises native discovery, calls, iframe isolation, stale handles, navigation, and manual-form handoff against the public Chrome demos. This case is opt-in and requires a compatible browser and valid demo Origin Trial enrollment.

TypeScript Client

The package also exports an Effect client for applications that need structured browser-authenticated requests without executing generated JavaScript:

npm install browserrig effect@4.0.0-beta.97

import { BrowserRigClient } from "browserrig"
import { Effect, Schema } from "effect"

const program = Effect.gen(function* () {
  const client = yield* BrowserRigClient.make()
  const browserSession = yield* client.ensureSession({ id: "my-app" })
  const account = yield* browserSession.authenticatedOrigin({
    origin: "https://app.example.com",
    startUrl: "/account",
  })

  const sensitive = yield* account.json({
    path: "/api/session",
    method: "POST",
    body: {},
    response: Schema.Struct({ accessToken: Schema.String }),
    sensitive: true,
  })
  const credentials = BrowserRigClient.reveal(sensitive)

  const profile = yield* account.json({
    path: "/api/profile",
    response: Schema.Struct({ name: Schema.String }),
  })
  return { credentials, profile }
})

Requests use window.fetch in the session's current page, so ambient browser cookies stay in the browser. Paths must be same-origin, redirects are blocked, responses are bounded, and mutations are never retried automatically. Set sensitive: true to receive Redacted; sensitive requests bypass execute journals and are rejected while session network capture is active. Reveal a sensitive result with BrowserRigClient.reveal; this keeps unwrapping in the same Effect runtime that created the redacted value, including when an application and BrowserRig resolve separate Effect package instances. Client construction waits through a bounded extension reconnect window even when the matching relay was already running. A session summary reports connected: true only when its Playwright transport and live default page are both available. Use resetSession(id) to replace a persisted session generation that is no longer connected before creating a new authenticated-origin capability.

Work in Sessions

A bare execute creates a fresh session. Pass its ID to continue with the same page and state:

browserrig session new docs
browserrig execute --session docs 'await page.goto("https://example.com/docs"); state.visits = (state.visits ?? 0) + 1; return state.visits'
browserrig execute --session docs 'return { url: page.url(), visits: state.visits }'
browserrig journal --session docs

The journal is a best-effort local activity record stored under ~/.browserrig/sessions//journal.jsonl. It includes bounded script and result previews and remains after session deletion. Do not embed passwords, tokens, or other credentials directly in execute code.

Single expressions return automatically, so this shorter form also works:

browserrig execute --session docs 'await page.title()'

Use --file script.js for longer programs and --json for a machine-readable result envelope. Delete the session when you f

browserrig

安装

说明文档