# Browser Mesh

Let AI agents drive a real Chrome — your everyday profile or a dedicated one — through MCP, with a visible control overlay, scoped grants, site policies, an emergency stop, and human confirmation for anything that raises privileges.

[中文说明](README.zh-CN.md)

> **Status:** early (0.1.0). Hosts a browser on macOS, Linux and Windows (Windows is a preview: the core host path has run on one real Windows laptop) — see the table below and [docs/install.md](docs/install.md#windows). Cross-device control works over Tailscale ([docs/networking.md](docs/networking.md)); it has been tested with two instances on one machine and with a Mac controlling a Windows host. Any device can also control a host's browser with just the [controller client](docs/networking.md#controlling-from-windows--linux). The in-browser UI and the messages returned to agents are currently in Chinese; English localization is planned.

## Platform support and verification

| Host | What has been exercised | Limits before release |
|---|---|---|
| macOS | Browser control and the extension, with the screen unlocked and locked; native confirmation; the optional UI helper against Chrome 156's **Chinese** interface (password bubble, site permissions including location) | The UI helper's English labels have not been seen on macOS (they have on Windows); only the fixed actions listed in [installation](docs/install.md#browser-ui-helper) are implemented |
| Linux | Debian container + Xvfb: install/uninstall, daemon, Native Messaging path, confirmation gate, clipboard and screen capture | Chrome with the extension has not been exercised on Linux. Wayland desktop integration is not established by the Xvfb test; X11 privilege changes are refused by default |
| Windows | On a real Windows laptop with Chrome: installation (logon task, Native Messaging registration); the Windows Hello confirmation gate; a dedicated profile controlled locally (new tab, navigate, snapshot, find, read text, typing Chinese and clicking, screenshots, emergency stop and lifting it with Windows Hello); control from a Mac through the [controller client](docs/networking.md#controlling-from-windows--linux) (list / open / close tabs, read text, screenshots; the first connection approved with Windows Hello); stopping the logon task (`schtasks /End`), starting it again, and reinstalling over a running daemon. On GitHub Actions `windows-latest`: all unit tests, and the browser-UI helper end to end (25/25, the runner's **English** Chrome) | Preview. Not yet run on a real machine: the UI helper, uninstall, Windows as a controller, your everyday Chrome profile with the extension, clipboard and full-screen capture |

Windows still needs real-machine checks for the items above, plus Task Scheduler restart-on-failure. Windows file access lacks `O_NOFOLLOW`; its checks are not the same as POSIX. See the [Windows checklist](docs/install.md#windows). The browser UI helper is implemented on macOS and Windows; Linux AT-SPI is not implemented.

Browser-interface actions require granting Accessibility permission to the separate macOS UI helper. Multi-account autofill selection, keeping a dangerous download, and cancelling the print dialog are **not currently provided**.

These are implementation and test-status statements, not a completed security audit or a claim that every platform is production-ready.

## What it does

- **MCP server** (stdio and Streamable HTTP on `127.0.0.1`) exposing 45 tools: tabs, navigation, accessibility snapshots with element refs, screenshots, click / type / fill forms / keys / scroll / hover, JS evaluation, dialogs, console logs, browser lifecycle and windows.
- **Works with your everyday Chrome profile** via an MV3 extension + Native Messaging + `chrome.debugger` (Chrome 136+ forbids remote-debugging switches on the default profile, so this is the only way), or with a **dedicated profile** that the daemon launches over `--remote-debugging-pipe`. Never `--remote-debugging-port`.
- **You can see and interrupt it:** controlled tabs get a yellow frame, an animated virtual cursor and a status label. In *yield mode* human input pauses the agent; you hand control back with one click (「交还」). In *lock mode* a page overlay blocks accidental clicks and keys and offers 「接管」 (*take over*). This is best-effort interaction protection, not a boundary against hostile pages; the popup and CLI also provide emergency stop.
- **Grants and scopes:** tools use scopes (`read`, `act`, `storage`, `browser_admin`, `settings`, `system`, `cdp_raw`, `browser_ui`); `batch` checks each step's scope separately. Agents can request more and wait for your approval.
- **Site policies:** per-domain `allow` / `read_only` / `deny`. Password managers, payment dashboards and account-security pages are read-only by default; regional presets (banks, brokers, payment services) are opt-in.
- **Human confirmation gate:** lifting an emergency stop, issuing or approving grants, relaxing site rules and enabling lifecycle control of your everyday Chrome require host-side confirmation. macOS uses a native dialog; Windows uses Windows Hello; Linux requires a suitable graphical session. Unsupported confirmation environments refuse by default; see [security.md](docs/security.md#who-can-answer-the-dialog).
- **Settings and system access** (off by default): proxy, privacy, fonts, site permissions and any `chrome://settings` preference with recorded rollback; enterprise policies exported for an admin to install; files in directories you open, clipboard, full-screen capture — see [docs/settings.md](docs/settings.md).
- **Across devices and to anyone:** control a Mac's browser from another device on your Tailscale network ([docs/networking.md](docs/networking.md)), or help someone outside it who installs only the extension, over an end-to-end encrypted relay you open on demand ([docs/remote-support.md](docs/remote-support.md)).
- **Emergency stop and audit log:** one button detaches everything within milliseconds; every action is recorded in a local SQLite audit log (typed text is stored as length only).

## Quick start

Requirements: Google Chrome, Node.js ≥ 22.13, npm, and an interactive desktop session on a supported host. Start with a dedicated profile if you do not want to expose your everyday sign-ins. The commands below install a persistent daemon and register Native Messaging; they are not just a build step.

```bash
git clone <this repo> browser-mesh && cd browser-mesh
npm install
scripts/install.sh --chrome          # registers the native host + a LaunchAgent for the daemon
```

The installer above is for **macOS**. On **Linux**, use `node scripts/install.mjs --chrome` after `npm install`; on **Windows (preview)**, use `node scripts\install.mjs --chrome` in PowerShell. Instead of `--chrome`, use `--profile-dir DIR` to register a non-default Chrome user-data directory. See [installation](docs/install.md) for data locations, service controls and platform dependencies. Keep this checkout in its installed location: the native host and MCP command refer to it.

Then in Chrome: open `chrome://extensions`, enable **Developer mode**, click **Load unpacked** and select `packages/extension`.

Register the MCP server with your agent, e.g. Claude Code:

```bash
claude mcp add browser-mesh -- node "$PWD/packages/daemon/mcp-stdio.mjs"
# or HTTP:
claude mcp add --transport http browser-mesh http://127.0.0.1:47801/mcp
```

Check it is connected: `node packages/daemon/cli.mjs status`, or open <http://127.0.0.1:47801/status>.

Prefer not to let an agent touch your everyday profile? Skip loading the extension there and let the agent call `browser_launch` — it starts a dedicated profile under `~/Library/Application Support/BrowserMesh/profiles/` (requires the `browser_admin` scope, which you approve once).

## Security model in brief

- **High privilege, not a sandbox.** An everyday browser carries your signed-in sessions. The initial local wildcard grant enables `read` + `act`; choose `defaultGrant: null` before the first database is created, or revoke existing grants, if that is too broad. File, settings, clipboard and UI-helper access have additional opt-ins.
- **Trusted host account.** Processes with the same OS account can change the code, configuration and grant database. Local agent names are not separate OS identities. The policy/confirmation interfaces do not isolate malicious same-user shell access. Automation with Accessibility permission can also defeat a macOS confirmation dialog.
- **Limited network exposure.** HTTP MCP is loopback-only; the peer listener uses Tailscale. Peer identity is per device, not per person; grant only what you trust processes on that device to do. Remote support additionally requires the humans to compare the check code; encryption alone is not that verification.
- **Untrusted pages remain untrusted.** Site rules and grants reduce permitted operations; the overlay is not an anti-tampering boundary. Treat page text and pushed events as data, never instructions. Emergency stop prevents further dispatch but cannot undo a submission or another action already performed.
- **Audit data can be sensitive.** Text input is summarized rather than logged verbatim, but URLs, account-related metadata and operation summaries can still be private. Keep the runtime data directory out of source archives and public issue attachments.

Read the full [security model and limitations](docs/security.md) before connecting a personal browser. Use a separate profile or machine for higher-risk tasks; this preview does not claim isolation from a compromised host or browser.

## Known limitations

- Chrome's own interface (`browser_ui`, opt-in): handles the "Save password?" bubble and site permission requests. It cannot cancel the print dialog, pick between several saved accounts in the autofill dropdown, or press "Keep" on a dangerous download — see [install.md](docs/install.md#known-limitations-of-the-ui-helper) for why.
- With the macOS screen locked, web-page tools keep working, but `browser_ui`, full-screen capture and the confirmation dialog do not — see [install.md](docs/install.md#when-the-screen-is-locked-macos).
- Linux has no UI helper yet.

## Documentation

- [Installation & configuration](docs/install.md)
- [Architecture](docs/architecture.md)
- [MCP tool reference](docs/tools.md)
- [Security model and limitations](docs/security.md) — read this before connecting your everyday profile
- [Chrome technical notes](docs/chrome-notes.md) — what Chrome 136+ allows and forbids for automation
- [FAQ](docs/faq.md)

## Uninstall

```bash
scripts/uninstall.sh           # keeps your data (audit log, grants, config)
scripts/uninstall.sh --purge   # removes everything
```

Remove the extension from `chrome://extensions`.

On Linux or Windows use `node scripts/uninstall.mjs` (Windows accepts backslashes). `--purge` also removes runtime data; back up anything you want to keep first.

## License

[MIT](LICENSE) — Copyright (c) 2026 nicgzlfly. Runtime dependencies and their licenses: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Report security issues privately — see [SECURITY.md](SECURITY.md). Changes: [CHANGELOG.md](CHANGELOG.md); contributing: [CONTRIBUTING.md](CONTRIBUTING.md).