AI Browser

AI Browser

中文读者请看这里： README-CN.md（3 分钟速读 + 中文安装指引）

A real browser whose only operator is your agent.

It reads pages as a semantic tree instead of screenshots, acts through trusted browser input — and because it is a normal, visible Electron window, a human can reach for the mouse at any time.

A noisy real-world feed (300+ accessibility nodes) becomes a typed structure — then one ui.act switches the feed and the tree changes with it. Every call is a raw JSON-RPC message over one WebSocket: no SDK, no coordinates.

Reproduce: npm start then node examples/feed-tree.mjs

Human + agent, same browser, same socket. The agent drives, then simply stops and watches; a person clicks an article in the real window, the agent notices the new tab on its next read, and continues on the page the human chose. No lock, no hand-off API.

Try it yourself: npm start then node examples/human-takeover.mjs — click anything when it says YOUR TURN .

What it is. An Electron app that exposes its tabs over two equivalent interfaces — an MCP server (17 browse_* tools) and a raw WebSocket JSON-RPC API (ws://localhost:9223, methods ui.*). Your agent navigates, reads a structured semantic tree (role / label / value / states / actions), and clicks or types by data-ai-id. Reading never goes through a screenshot and there is no OCR — that's the point of the tree. browse_screenshot exists, but as a *diagnostic* for the cases the tree can't see (overlays, canvas, mis-rendered layout), not as the read path.

What it is not. It is not headless. The window really opens, really renders, and stays interactive — see Letting a human step in. Nor does it "co-drive" with you: the hand-off is a conversation between the agent and the user, not a browser API.

Security note. The WebSocket server binds loopback only and **refuses any handshake that carries

an Origin header** — that's what a browser always sends, so a page running inside AI Browser (or

any other browser) cannot drive the control plane, while Node/CLI/MCP clients (which send no

Origin) work normally. There is still no token: a local process running as you can connect.

Do not expose port 9223 beyond loopback.

(AI_BROWSER_WS_ALLOW_ORIGIN=1 disables the check — debug only, it re-opens the page → browser path.)

Sandbox is off by default, deliberately. Chromium's OS sandbox cannot initialise in restricted

shells (IDE terminals, some CI), where it fails with `sandbox initialization failed: Operation not

permitted` and the app exits before any of our code runs — so there is no error to report, just a

silent quit. AI_BROWSER_SANDBOX=1 turns it on; if the app then quits instantly with no output at

all, that's this — unset the variable. Renderers are still isolated from the page either way

(contextIsolation:true, nodeIntegration:false); this switch is about the OS layer under them.

---

Install

Install the prebuilt package unless you have a reason not to. Option A is one file you double-click: no Node.js, no dependency tree, no build step. Source install (Option C) pulls a ~276 MB node_modules plus a ~100 MB Electron engine download on top — only use it when no package fits your platform, the package misbehaves, or you specifically need to run from source.

Option A — macOS install package (recommended)

Grab AI-Browser- -arm64.dmg from GitHub Releases (~110 MB to download, ~245 MB on disk — most of it is the bundled Chromium engine, which *is* the product). Open the dmg, drag AI Browser to /Applications, launch it. Done.

Two things to know before you download it:

• It is not notarized. macOS Gatekeeper will refuse to open it on the first try. Right-click the app → Open, confirm once, and it runs normally afterwards. (A paid Apple Developer account is what removes this step; until then, this is the honest cost.)
• Only macOS `arm64` and Windows `x64` are built. Linux has no package yet — see Compatibility.

Option A2 — Windows installer

Grab AI-Browser- -win32-x64-Setup.exe from the same Releases page (~79 MB). Run it and click through: it installs per user to %LOCALAPPDATA%\Programs\AI Browser (no admin prompt, no UAC), creates the Start Menu entry and a Desktop shortcut by itself, and offers to launch the browser when it finishes. Uninstall is a normal entry in Settings → Apps; it removes the program and both shortcuts but leaves ~/.ai-browser alone, so your profiles and logins survive a reinstall.

Two things to know:

• It is not code-signed. SmartScreen may show "Windows protected your PC" → More info → Run anyway. (A code-signing certificate is what removes this step.)
• The installer is a plain NSIS wizard, so you can pick the install location; the default is the per-user path above.

Agents still connect through the MCP server (Option B below), and the two channels cooperate: when the packaged app is already running, the MCP server finds it on port 9223 and reuses it instead of spawning a second copy of Electron — one browser, one login session, whichever way you start it. So "package for the engine + npx for the MCP bridge" is the normal agent setup too.

Option B — npx (the agent channel)

The package is published as @glittering0717/ai-browser; no clone needed:

npx -y @glittering0717/ai-browser --help

To open the visible browser window directly:

npx -y @glittering0717/ai-browser start

Requires Node ≥ 18 and a desktop session (this is a GUI app). If a launch needs its own engine, the first run prepares it (~100 MB, downloaded once). npm ≥ 11 blocks dependency install scripts by default — the launcher detects that and runs Electron's own downloader itself, so nothing extra is needed. If the download from GitHub releases is slow or blocked (common on mainland-China networks), point it at a mirror:

ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npx -y @glittering0717/ai-browser start

Option C — from source (fallback)

Use this when there is no package for your platform, the package gives you trouble, or you need to modify the code. It is the heaviest of the three: npm install pulls the full dependency tree (~276 MB), then the Electron engine (~100 MB) on top.

git clone https://github.com/Glittering/ai-browser.git

cd ai-browser npm install

If the Electron binary download is slow or fails outright, use the mirror:

ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm install

Or make it sticky by creating a .npmrc in the project root:

electron_mirror=https://npmmirror.com/mirrors/electron/

Confirm the binary actually landed before blaming anything else — a missing binary still leaves you with an "install that succeeded":

ls node_modules/electron/dist

To check the install end to end:

npm start

A 1280×800 window opens and the terminal prints AI Browser WS server listening on ws://localhost:9223. (The first tab opens on the default start page; ignore it and navigate away.)

To build the package yourself:

npm install

node scripts/build_dmg.cjs # current arch node scripts/build_dmg.cjs --arch arm64 # or x64

Output lands in dist/. The script uses @electron/packager plus macOS's built-in hdiutil (no external binary downloads); the reasoning — including why electron-builder refuses to build this project — is documented in docs/DEPENDENCY_AND_DISTRIBUTION_AUDIT.md.

---

Connect your agent

Add this to your MCP client's config file — Claude Desktop's config, ~/.cursor/mcp.json, or a project-level .mcp.json:

{

"mcpServers": { "ai-browser": { "command": "npx", "args": ["-y", "@glittering0717/ai-browser", "mcp"] } } }

A ready-made copy sits in examples/mcp-config.json. From-source users can instead point command: "node" at /absolute/path/to/ai-browser/src/main/mcp_server.js.

You do not need to start the browser yourself. On the first browse_* call the MCP server probes port 9223; if nothing is listening it spawns Electron detached and waits up to 30 seconds for the WebSocket server (the very first call may additionally spend time preparing the engine). If you would rather keep one long-lived window shared by every client, launch the AI Browser app you installed in Option A (or run npx -y @glittering0717/ai-browser start, or npm start from source) — a second launch just focuses the existing window.

examples/AGENT_INSTRUCTIONS.md has a copy-paste prompt you can drop into a CLAUDE.md, Cursor Rule, or any system prompt; it teaches the tool loop, the token-saving params, and when to ask a human. Agents installing this themselves (Cline, etc.) can read the short machine-oriented llms-install.md instead of this README.

---

The MCP tools

Source of truth: src/main/mcp_tools.js. There are 17 — a deliberately small surface, since every tool schema is injected into your agent's context on every turn.

| `browse_scroll