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.

中文说明

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. Cross-device control works over Tailscale (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. The in-browser UI and the messages returned to agents are currently in Chinese; English localization is planned.

Platform support and verification

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. 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.

Related MCP server: Omotai Runtime

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.

• 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.

• Across devices and to anyone: control a Mac's browser from another device on your Tailscale network (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).

• 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.

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 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:

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 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 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.

• Linux has no UI helper yet.

Documentation

• Installation & configuration

• Architecture

• MCP tool reference

• Security model and limitations — read this before connecting your everyday profile

• Chrome technical notes — what Chrome 136+ allows and forbids for automation

• FAQ

Uninstall

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 — Copyright (c) 2026 nicgzlfly. Runtime dependencies and their licenses: THIRD_PARTY_NOTICES.md. Report security issues privately — see SECURITY.md. Changes: CHANGELOG.md; contributing: CONTRIBUTING.md.