# Getting Started BrowserBridge is a local-first MCP browser control plane for AI agents. It connects paired, scoped MCP clients to a local Chrome extension and native companion so users can see runtime state, approvals, panic state, and audit evidence. BrowserBridge is not CDP, not a cloud browser, and not general browser automation. Harness commands such as `/browser connect` are not the BrowserBridge path unless a separate adapter translates them into BrowserBridge MCP calls. ## Current Private Alpha Supported in RC1: - native messaging extension-to-companion path - read-only active-tab metadata with origin-only URL disclosure - approval-gated active-tab navigation to validated `http` and `https` origins - paired client identity, short-lived sessions, exact scopes, tab routing, approvals, panic checks, and audit records - authenticated MCP over loopback by default, with explicit `--allow-remote` for trusted tailnet lab testing Explicitly absent: - live click - live type - DOM reads - screenshots - content scripts - host permissions - broad `tabs` permission - full URL persistence - unauthenticated remote listeners - cloud services or analytics - stealth, anti-detection, or CAPTCHA bypass behavior Extension permissions must remain exactly: ```json ["nativeMessaging", "activeTab"] ``` `host_permissions` must remain `[]`, and `content_scripts` must be absent. ## Requirements - macOS with Google Chrome - Node.js and `npx` - `pnpm` 9.15.0 or `npx pnpm@9.15.0` - a trusted local checkout or the public RC download - optional: Tailscale for trusted tailnet MCP testing ## Download Latest Stable public latest files: ```text https://pub-94e17e3158894cbba8864e5d1eab3045.r2.dev/downloads/latest.tar.gz https://pub-94e17e3158894cbba8864e5d1eab3045.r2.dev/downloads/latest.sha256 https://pub-94e17e3158894cbba8864e5d1eab3045.r2.dev/downloads/latest.manifest.json ``` Verify the checksum before using the artifact: ```sh curl -LO https://pub-94e17e3158894cbba8864e5d1eab3045.r2.dev/downloads/latest.tar.gz curl -LO https://pub-94e17e3158894cbba8864e5d1eab3045.r2.dev/downloads/latest.sha256 curl -LO https://pub-94e17e3158894cbba8864e5d1eab3045.r2.dev/downloads/latest.manifest.json shasum -a 256 -c latest.sha256 ``` `latest.manifest.json` records the current commit, SHA-256, extension permissions, unsupported capabilities, docs version, and resultKind semantics. ## Clone Or Update For a source checkout: ```sh git clone https://github.com/MahdiHedhli/browserbridge.git cd browserbridge ./scripts/install-or-update.sh doctor ./scripts/install-or-update.sh update --skip-start ``` For a plan-only dry run: ```sh ./scripts/install-or-update.sh dry-run ``` For trusted tailnet MCP testing: ```sh ./scripts/install-or-update.sh update \ --host \ --port 7332 \ --allow-remote \ --skip-start ``` Non-loopback hosts are refused without explicit `--allow-remote`. ## Load The Extension 1. Open `chrome://extensions`. 2. Enable Developer Mode. 3. Click `Load unpacked`. 4. Select `packages/extension/dist`. 5. Confirm permissions are only `nativeMessaging` and `activeTab`. The service worker being inactive is normal when idle. Service worker registration failure, bare `@browserbridge/*` import errors, host permission drift, or content scripts are not normal. Validate the extension bundle: ```sh npx pnpm@9.15.0 --filter @browserbridge/companion exec browserbridge-companion \ native:validate-extension-dist --path packages/extension/dist ``` ## Native Host Setup After Chrome shows the extension id, generate a reviewed install plan: ```sh npx pnpm@9.15.0 --filter @browserbridge/companion exec browserbridge-companion \ native:install-plan \ --os macos \ --extension-id \ --companion-path "$PWD/packages/companion/dist/companion/src/native-host-bin.js" ``` Then run diagnostics: ```sh npx pnpm@9.15.0 --filter @browserbridge/companion exec browserbridge-companion \ native:doctor --os macos --extension-id --pretty ``` Use `native:repair-plan` for suggested commands. It prints a plan and does not write without explicit confirmation. ## Start MCP Loopback default: ```sh npx pnpm@9.15.0 --filter @browserbridge/mcp-server exec browserbridge-mcp \ http --host 127.0.0.1 --port 7332 ``` Trusted tailnet: ```sh npx pnpm@9.15.0 --filter @browserbridge/mcp-server exec browserbridge-mcp \ http --host --port 7332 --allow-remote ``` Remote MCP remains authenticated. Pairing, sessions, exact scopes, approvals, panic, tab routing, and audit still apply. ## Verify Status Run local checks: ```sh npx pnpm@9.15.0 check npx pnpm@9.15.0 build npx pnpm@9.15.0 alpha:smoke npx pnpm@9.15.0 public:scan -- --target artifacts/public-site ``` When no fresh extension metadata exists, MCP read tools should return `resultKind=live_unavailable`, not stale mock-shaped tabs. When the extension has fresh active-tab metadata, read tools should return `resultKind=live_success` with origin-only tab data. `mock_success` is allowed only in explicit demo mode. ## Hermes Hermes should connect through BrowserBridge MCP over the trusted tailnet, not through CDP. Expected validation: - `browserbridge_status` reports the current BrowserBridge build commit - `browserbridge_tabs_list` returns `live_unavailable` when metadata is absent - `browserbridge_observe` returns `live_unavailable` when metadata is absent - no stale mock-shaped tabs appear in production mode - no tokens appear in argv, logs, docs, or config See [BrowserBridge MCP harness](integrations/browserbridge-mcp-harness.md) and [Hermes integration](integrations/hermes.md). ## Codex The safe Codex path is documented and has a local safety skeleton, but it is not yet claimed as a fully validated Codex MCP server. ```sh BROWSERBRIDGE_SESSION_TOKEN="" \ node scripts/adapters/browserbridge-codex-mcp.mjs --doctor --json ``` Do not use the old untracked local helper unless it is redesigned to eliminate token-in-argv risk. See [BrowserBridge Codex integration](integrations/browserbridge-codex.md). ## OpenClaw OpenClaw support is documented only and not yet validated. OpenClaw `/browser connect` CDP is not BrowserBridge MCP. Use the validation checklist in [BrowserBridge OpenClaw integration](integrations/browserbridge-openclaw.md). ## Troubleshooting - Service worker inactive: normal idle Chrome state. - Service worker registration failed: rebuild/package issue. - Bare `@browserbridge/*` import: extension bundle issue. - Native host forbidden: extension id or manifest origin mismatch. - `live_unavailable`: no fresh extension metadata; not a failure by itself. - Stale tabs: clear runtime cache and restart the active harness adapter. Useful commands: ```sh ./scripts/install-or-update.sh doctor npx pnpm@9.15.0 --filter @browserbridge/mcp-server exec browserbridge-mcp runtime:clear-cache --confirm npx pnpm@9.15.0 --filter @browserbridge/companion exec browserbridge-companion audit:unified:verify ``` ## Uninstall Or Reset Print safe reset steps: ```sh ./scripts/install-or-update.sh uninstall-helper ``` See [Uninstall](uninstall.md) and [Reset and recovery](reset-recovery.md). ## Logs And Audit BrowserBridge keeps diagnostics local. Audit records are redacted before persistence and verified through the unified audit chain. Do not paste session tokens, pairing codes, auth headers, cookies, credentials, private keys, raw public keys, full URLs, query strings, fragments, or secret-like values into issues. Report harness validation results with the `BrowserBridge harness validation` issue template.