Private Alpha RC1 Local-first No cloud No analytics Origin-only

Secure local co-browsing control plane

BrowserBridge

Secure co-browsing between AI agents and your local browser.

RC1 demonstrates native messaging, pairing/session/scope policy, panic signaling, read-only active-tab metadata, approval-gated active-tab navigation, and a tamper-evident local audit chain.

Download RC1 Getting Started Security Boundaries

What BrowserBridge does

A visible, permissioned bridge between agents and your local browser.

BrowserBridge is a local-first secure browser control plane for AI agents. It connects agent harnesses to a user's real browser through native messaging, paired client identity, exact scopes, approval gates, panic controls, and local audit records.

The private alpha is intentionally narrow: it proves the security architecture before expanding live browser capability.

Why it exists

Agent ecosystems need browser access without invisible control.

User-owned sessions

Work with the user's local browser session instead of forcing workflows into cloud browsers.

Human-visible interaction

Keep connection state, approvals, panic, and recovery visible to the user.

Compatibility without bypasses

Target MCP-compatible harnesses without stealth, anti-detection, or CAPTCHA bypass behavior.

Current private alpha capabilities

Small live surface, full policy path.

RC1 keeps browser access limited while exercising the controls that future capabilities must pass through.

Transport

Native messaging path

Manifest V3 extension-to-companion status, panic, approval transport, and active-tab messages.

Observation

Read-only active-tab metadata

Origin-only metadata. No full URL, DOM, screenshot, page storage, cookie, or form access.

Action

Approval-gated active-tab navigation

Navigation is limited to validated origins and requires scope, session, tab, panic, audit, and approval checks.

Safety

Panic and recovery path

Panic blocks future action paths and is carried over the native messaging channel.

Policy

Pairing, sessions, scopes, approvals

Named paired clients, public-key identity, short-lived sessions, exact scopes, and one-time approvals.

Audit

Tamper-evident local audit chain

Local redaction-before-write audit events with hash-chain verification and export commands.

Live capability status

Clear runtime states, no hidden automation.

BrowserBridge tools distinguish fresh live metadata from unavailable live state and explicit demo mode. Production harnesses should never receive stale mock-shaped tabs.

Live Active Tab

Fresh extension metadata exists and returns origin-only tab data.

MCP Only

MCP is reachable, but the extension/native path has no fresh metadata.

Pending Approval

Navigation remains one-time, approval-gated, client-bound, and tab-bound.

Panic Mode

Panic blocks action paths and clears pending approvals fail-closed.

Security-first architecture

Native messaging is transport, not permission.

A successful handshake never grants browser capability. Every live path still depends on paired identity, valid session, exact scope, tab target validation, one-time approval, panic checks, and audit.

Local by default

Companion and MCP surfaces are loopback-only by default. Trusted tailnet MCP binds require explicit opt-in.

Minimal extension permissions

RC1 uses only nativeMessaging and activeTab, with no host permissions or content scripts.

Redacted evidence

Audit records avoid raw tokens, pairing codes, credentials, typed input, full URLs, queries, and fragments.

What it explicitly does not do

RC1 is not general browser automation.

These limits are intentional. They keep the alpha focused on a reviewable security model before any broader live control is designed.

Live click Live type DOM reads Screenshots Content scripts Host permissions Broad tabs permission Full URL persistence Unauthenticated remote listeners SSH/Tailscale activation Cloud services Analytics Stealth or anti-detection CAPTCHA bypass

Trusted tailnet testing

Remote MCP bind is explicit.

BrowserBridge MCP HTTP is loopback-only by default. Private alpha testers can opt in to a non-loopback bind for trusted tailnet lab validation with --allow-remote. Authentication, exact scopes, approvals, panic checks, and audit still apply.

browserbridge-mcp http \
  --host 100.66.42.21 \
  --port 7332 \
  --allow-remote

Never expose BrowserBridge MCP directly to the public internet.

Install path

Download, verify, load, then start MCP.

Start from the latest public R2 artifact or a trusted private checkout. The extension load path, native doctor, MCP command, and Hermes validation commands are printed by the installer.

Full path: Getting Started and Operator Install/Update.

Source checkout install/update

git clone https://github.com/MahdiHedhli/browserbridge.git
cd browserbridge
./scripts/install-or-update.sh doctor
./scripts/install-or-update.sh update --skip-start

Load Chrome from packages/extension/dist, then run native:doctor before writing a native host manifest.

Supported and target integrations

Profiles describe connection shape. They do not grant capability.

Hermes
OpenClaw
Claude Desktop
Browser Use
Playwright MCP
Codex-compatible MCP clients

Audit and panic controls

Local evidence before broader capability.

The unified audit bus records companion, MCP, native messaging, approval, transport, and security-failure events through one local ingestion path. Redaction happens before persistence, then records are chained with hashes for tamper-evidence.

Panic is fail-closed: it blocks new action paths and prevents approval reuse from becoming a capability bypass.

Release verification

Verify RC1 before manual harness validation.

Source repo remains private. Public downloads are hosted via R2, with stable latest links and versioned artifacts for repeatable verification.

Latest download: latest.tar.gz

Verify public latest

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

Roadmap

Security gates remain ahead of capability expansion.

M0-M10Foundation, specs, mock policy path, and integration profiles.
M11-M17Native messaging trust boundary and unified local audit event bus.
M18-M22Tamper-evident audit, secure store abstraction, native status/panic, active-tab metadata, and approval-gated navigation.
M23-RC1Private alpha packaging, smoke tests, release verification, and onboarding docs.
NextAdapter hardening, installer polish, and security review before any click/type design.

Troubleshooting

Recover safely without widening permissions.

Getting Started Onboarding Security boundaries macOS quickstart Install/update Alpha smoke test Release verification Troubleshooting Reset and recovery