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

The Phase 2 work tracked in _reference/11_BROWSER_CONTROL.md and implementation_plan.md's "BC — Browser Control (Phase 2)" section is implemented, not just scaffolded. All 16 BROWSER_COMMAND actions have real Playwright handlers in maestro_browser_bridge/handlers.py:

navigate, click, type, keypress, scroll, screenshot, read_dom, console_logs, list_tabs, allowlist_add, upload, wait_for, select_option, dismiss_dialog, collect_toasts, eval_js

(the last six — upload through eval_js — are the Phase 2.1 additions for Play Console / general lazy-UI automation: file upload, waits, native + Material-UI dropdowns, dialog dismissal, toast collection, and arbitrary page.evaluate.)

Also shipped: a security layer (security.py — pause/resume kill switch, per-host navigate allowlist, rate limiting) exposed via three extra CLI commands not mentioned above — pause, resume, bridge-status — which talk to the running daemon over its own loopback WebSocket (BRIDGE_CONTROL, 127.0.0.1 only, never over the relay). The package is published to PyPI by the release pipeline (publish-bridge job), so pip install maestro-browser-bridge (see Install, above) is a real, working install path today, not aspirational.

Still genuinely unimplemented (stubs, matching their CLI help text): --detach on start, the stop command, and install-service (launchd/systemd, tracked as BC.1.4) — for now the bridge only runs in the foreground.

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