maestro-browser-bridge 1.18.0

Local browser bridge for Remote AI Maestro — runs a Playwright-managed Chromium and exposes BROWSER_* commands over WebSocket.

maestro-browser-bridge

Local browser bridge for Remote AI Maestro.

The bridge is the companion app you install on the same laptop where you keep your real browser. It launches a Playwright-managed Chromium in an isolated profile and exposes it over a WebSocket so an AI agent running inside a Maestro sandbox can drive it — navigate, click, type, screenshot, read DOM, capture console logs.

This is the Phase 2 counterpart to the simpler Phase 1 maestro browser open <url> command, which only pops URLs in your already-open browser via the frontend's window.open. The bridge gives Claude (or any agent) real browser control without ever touching your logged-in Chrome profile.

Why a separate process

The AI agent runs on a remote machine (or an EC2 sandbox) but the browser to be controlled lives on your local desktop. There is no other process that runs on the user's actual laptop in a known-good location — the agent daemon runs on whichever machine the sandbox is bound to, which may be EC2. So we ship a dedicated bridge process that runs on the user's laptop, maintains an outbound WebSocket to the relay, and translates BROWSER_* messages into Playwright calls.

The bridge is per-user (one bridge per laptop) — distinct from the agent daemon, which is per-machine. Relay routing maps user_id → bridge.

Install

pip install maestro-browser-bridge

# Pre-download the Playwright Chromium binary (~200MB)
playwright install chromium

# Configure once
maestro-browser-bridge configure \
  --relay-url wss://relay.thesavvydeveloper.com \
  --user-id YOUR_USER_UUID \
  --user-token YOUR_BRIDGE_TOKEN

# Start
maestro-browser-bridge start

--detach is wired but not yet implemented; for now run the bridge in the foreground (or wrap it in your own service manager — launchd / systemd unit shipping is planned).

Status

This package is the scaffold for the Phase 2 work tracked in _reference/11_BROWSER_CONTROL.md and implementation_plan.md's "BC — Browser Control (Phase 2)" section. The protocol models, dispatch shell, and CLI surface are in place; the actual Playwright handlers raise NotImplementedError and will be wired in subsequent commits (BC.1.2 in the plan).

Development

# Editable install with test deps (from the repo root)
pip install -e ./bridge[test]

# Run tests
cd bridge && pytest

# Smoke check the CLI
maestro-browser-bridge --version
maestro-browser-bridge --help

References

• Architecture & wire protocol: _reference/11_BROWSER_CONTROL.md
• Milestone plan: _reference/12_BROWSER_PHASE2_PLAN.md
• Pip package contract: implementation_plan.md § BC.1

License

MIT