microsoft/amplifier-browser-bridge

microsoft/amplifier-browser-bridge

Description: Browser Bridge for the Amplifier project

Language: Python

License: MIT

Stars: 0

Forks: 0

Open issues: 0

Created: 2026-08-09T23:51:40Z

Pushed: 2026-08-10T03:51:24Z

Default branch: main

Fork: no

Archived: no

README:

Amplifier Browser Bridge

Amplifier Browser Bridge lets an AI agent running on one device observe and drive a user's real, logged-in Microsoft Edge browser on another device -- over the user's own Tailscale tailnet. The agent is a second operator sharing a live browsing session, not a robot driving a disposable browser it launched for itself.

No vendor product does this today: Claude in Chrome, Edge Copilot Mode, Gemini in Chrome, and Playwright MCP's extension mode all run the control plane on the machine the human is sitting at. Driving the browser on a phone from a workstation across the room -- or across the country -- is the gap this project fills among vendor-shipped tools.

This claim narrows to exclude one real prior-art project: `browser-relay` (MIT) already does cross-device browser control today, via a public Cloudflare Worker relay authenticated by a bearer Device ID that its own README calls *"a capability -- anyone with it can control this browser."* This project does not claim to be first; its honest differentiator is replacing that public relay with the user's own Tailscale tailnet -- no third-party relay in the path, no long-lived bearer capability traveling the public internet, device-level network ACLs instead of a single shared secret. See docs/designs/browser-bridge.md section 9 for the full positioning against browser-relay, Playwright MCP, and every vendor tool above.

Status

Early. Phases 1-3 of a 6-phase build order are committed; this is not yet a finished product.

| Phase | What it covers | Status | |---|---|---| | 1. Hub + extension, one device, one tab | snapshot -> click -> read, proves the pipe | Done | | 2. Addressing | Multi-device, multi-window, multi-tab targeting | Done | | 3. Tier model + queue | Non-blocking dispatch to intermittently-connected devices | Done | | 4. Agent surfaces | Python lib, CLI, MCP server, Amplifier tool module | Done | | 5. Policy engine | Denylist, confirmation gates, audit log | Done | | 6. CDP escalation | Trusted input events, background-tab screenshots, soft-detach | Built, never run against a real Edge browser |

What that means concretely:

• Proven end-to-end: the wire protocol, hub dispatch and queueing, the CLI, the MCP server,

the Amplifier tool module, and the policy engine all have passing automated tests (uv run pytest tests/, uv run pytest modules/tool-browser-bridge/tests/ -- see "Testing" below) and, for the agent surfaces, a documented real run against a live hub (docs/AGENT_SURFACES.md, "Verified end-to-end").

• Measured on real hardware, not assumed: every load-bearing transport and platform

constraint in the design doc -- MV3 service worker lifetime, Android Doze behavior, background tab screenshot support, MagicDNS reliability -- was measured against real Edge installs on macOS and Android, not taken from documentation (docs/designs/browser-bridge.md section 2).

• Built but never exercised on a real browser: chrome.debugger (CDP) escalation for

trusted input events and any-tab screenshot capture on desktop. The full path exists and is unit-tested (cdp.py, hub.py's _ensure_cdp_attached, background.js's cdpAttach, tests/test_cdp.py): a trusted or capture_hidden arg escalates that one tab on demand, and the hub soft-detaches after 20s idle so the debugger banner clears. What has *not* happened is a run of it against a real Edge install -- so the banner behavior in [docs/DEBUGGER_BANNER.md](docs/DEBUGGER_BANNER.md) is derived from Chromium source, not observed here. Without either arg, dispatch stays injection-only: synthetic input is not isTrusted, and screenshot only reaches the tab that is already active. CDP network interception is not implemented at all.

• Not yet published: this repository has no packaged release, no CI history, and has not

been submitted to the Edge Add-ons store. Everything above is verified in-repo, not in production use.

Security posture

This software controls a user's real, authenticated browser session. Before evaluating or deploying it, read [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) for the full threat model. In brief:

• The per-device shared token is the load-bearing boundary for most deployments -- not the

tailnet. Tailscale's own default ACL policy allows every device on your tailnet to reach every other device on every port; unless you've written a restrictive ACL (starting point: [docs/tailscale-acl-example.hujson](docs/tailscale-acl-example.hujson)), the tailnet is not a meaningful boundary by itself. amplifier-browser-bridge doctor reports this and your bind-address exposure on every run.

• amplifier-browser-bridge hub binds 127.0.0.1 by default (safe, loopback-only); amplifier-browser-bridge init

auto-detects this machine's Tailscale IP as a cross-device-capable default and warns loudly if a wildcard bind (0.0.0.0) is ever chosen instead.

• A per-device shared token is a second, narrower boundary on top of tailnet identity, because

tailnet identity is per-*device*, not per-*application*. Token comparison is constant-time. One token controls every device connected to a hub unless you hand-provision per-device ones (auth.py's TokenStore supports this; init does not auto-provision them yet).

• Consent is enforced structurally, at a single choke point in the hub (PolicyEngine.evaluate),

never by prompting the model to behave -- a prompt-injected agent can *want* a different target, it cannot *address* one policy has not permitted.

• Everything the agent does is written to an audit log. See [docs/POLICY.md](docs/POLICY.md) for

exactly what the denylist and confirmation gates do and do not catch -- both sections end with an honest list of known gaps.

Quickstart

Why the setup is this long

Three of the steps below -- run your own hub, hold your own token, address it by your own Tailscale IP -- exist for exactly one reason: the connection between the agent and your browser runs over your own network, with nothing in the path but your own devices. The nearest alternative you could pick instead,...