Skip to content
Back to search

browse

Let your AI agents use your real browser: an MCP server and a Chromium extension

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/anomalyco/browse with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/anomalyco/browse'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/anomalyco--browse/badge.svg)](/listings/anomalyco--browse)

HTML

<a href="/listings/anomalyco--browse"><img src="/api/listings/anomalyco--browse/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/anomalyco/browse.git && cd browse && bun run setup

`setup` builds the extension and the CLI, adds the `browse` MCP server to opencode, and pairs the extension with the local relay. Two steps are left for you:

1. **Load the extension.** `setup` opens your browser's extensions page, shows the `browse/dist` folder and copies its path. Turn on **Developer mode**, click **Load unpacked** and choose that folder (on macOS, press Cmd+Shift+G in the picker and paste), or drag the folder onto the page. `setup` waits until the extension connects. 2. **Restart opencode.**

That's it. Ask an agent to *"open news.ycombinator.com and tell me the top story"*.

**Or let your agent do it.** Paste this into opencode: *"Install browse from https://github.com/anomalyco/browse and follow its README."* The agent clones it, runs `setup` and tells you which folder to load; you still click **Load unpacked** and restart opencode.

Requirements: [Bun](https://bun.sh), Node.js 22.19+, a Chromium browser, and [opencode](https://opencode.ai) or another MCP client.

**Updating:** run `node cli/dist/cli.mjs update` in your `browse` folder (or ask your agent to update browse), then restart opencode. It pulls the new commits (fast-forward only, and never over local changes), rebuilds, and reloads the extension for you. The manual equivalent is `git pull && bun run setup`. When there's an update, `status`, `doctor`, the extension's status page and the agent (once per session) say so; browse checks the clone's remote at most every six hours. Set `OPENCODE_BROWSER_UPDATE_CHECK=0` to turn the check off.

There's nothing to sign in to. `setup` writes a pairing code into `dist/`, and the extension only obeys a relay that proves it knows that code (see [Security](#security)). A Chrome Web Store build has no pairing file: run `node cli/dist/cli.mjs pair` and paste the code on its status page (right-click the toolbar button, then **Options**).

> **Coming soon:** a Chrome Web Store listing and an npm package, so you can skip the clone.

Other MCP clients

`setup` writes the server into opencode's config. For other clients, add an stdio server that runs the built CLI:

{
  "browse": { "command": "node", "args": ["/path/to/browse/cli/dist/cli.mjs", "mcp"] }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 369 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <picture>
  2. <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.png">
  3. <img src="assets/banner-light.png" alt="browse: let your AI agents use your real browser. An isometric desk computer whose screen shows a web browser with an agent's tab group, cabled to a small relay box.">
  4. </picture>
  5. Let your AI agents use your real browser: your tabs, your logins, your extensions. A small native MCP server and a
  6. Chromium extension, for [OpenCode](https://opencode.ai), Claude Code, Codex, Cursor and any other MCP client.
  7. ---
  8. Agents get a `browse` MCP server. They open tabs in the background, read pages, click, type, take screenshots,
  9. capture network traffic and record the screen, in tabs grouped out of your way. When it's your turn (a login, a 2FA
  10. prompt, a payment), they hand the tab back to you and continue once you click **Continue**.
  11. It works in Chrome, Edge, Brave, Arc, Helium, Vivaldi, Opera and Chromium.
  12. ## Install
  13. ```sh
  14. curl -fsSL https://opencode.ai/browse/install | bash
  15. ```
  16. Or paste this into your agent: *"Set up browse so you can use my Chrome: run
  17. `curl -fsSL https://opencode.ai/browse/install | bash`"*. It sets browse up for the agent that ran it.
  18. Other ways to install, all of which end in the same `browse install`:
  19. | How | Command | Where `browse` lives, and what updates it |
  20. | --- | --- | --- |
  21. | Install script (macOS, Linux) | `curl -fsSL https://opencode.ai/browse/install \| bash` | `~/.local/bin/browse` (`$XDG_BIN_HOME` when set); updates itself |
  22. | Install script (Windows) | `irm https://opencode.ai/browse/install.ps1 \| iex` in PowerShell | `%USERPROFILE%\.local\bin\browse.exe`; updates itself |
  23. | npx, bunx | `npx @opencode/browse install` | copied to `~/.local/bin/browse` once; updates itself from then on |
  24. | npm | `npm i -g @opencode/browse`, then `browse install` | npm's global `browse`; browse runs `npm install -g` to update |
  25. | bun | `bun add -g @opencode/browse`, then `browse install` | `~/.bun/bin/browse`; browse runs `bun add -g` to update |
  26. | pnpm, yarn, volta | `pnpm add -g` / `yarn global add` / `volta install @opencode/browse`, then `browse install` | that manager's `browse`; updated with the same manager |
  27. There's always exactly one `browse`: a global package install is left to its package manager (nothing is copied next
  28. to it, and a leftover `~/.local/bin/browse` from an earlier install is removed), and agents run the same `browse` your
  29. terminal does. If `browse install` finds another `browse` on your PATH it tells you which one and how to remove it.
  30. The install script reads the channel's manifest from [Anomaly's release service](https://anoma.ly/release), downloads
  31. the binary for this computer and checks its size and SHA-256 before installing it. `--channel stable|beta|dev` picks
  32. the channel (`stable` by default); `--version <version>` installs a specific version from npm, checked against npm's
  33. published SHA-512 integrity. With npm, `@opencode/browse@dev` is the dev channel. The npm package is a small Node
  34. launcher (Node 22+) that runs the native binary npm installed for your platform.
  35. ### What `browse install` does
  36. 1. **Puts browse in place** (see above) and adds `~/.local/bin` to your PATH when it copied browse there
  37. (`--no-modify-path` skips that).
  38. 2. **Adds the browse MCP server to your agents.** In a terminal you get a picker: OpenCode and the agents found on this
  39. computer start checked (your last choice next time). Type to search all supported agents, ↑/↓ to move, Space or Tab
  40. to toggle, Enter to confirm. An agent running `browse install` sets up itself. Without a terminal OpenCode is the
  41. default. Edits keep the comments and formatting of each agent's config.
  42. 3. **Connects the extension.** If no browser has browse yet, install opens it in the Chrome Web Store; add it, and
  43. install pairs it once it's there. If a browser already has it, install opens its setup page with a one-time pairing
  44. code in the link, so it pairs without copying anything. Over SSH or without a display it prints a code instead.
  45. Then ask your agent to *"open news.ycombinator.com and tell me the top story"*. An agent that was already running
  46. needs a restart (or an MCP reload) to load browse.
  47. ```sh
  48. browse install -a claude codex # these agents, without asking (--agent; names below)
  49. browse install -a '*' # every supported agent, installed or not
  50. browse install -y # every agent found on this computer
  51. browse install --agent none # no agent: print the MCP entry to add by hand
  52. ```
  53. <details><summary>Supported agents and their user-level config files</summary>
  54. `CONFIG` is `$XDG_CONFIG_HOME` or `~/.config`. `APP` is `~/Library/Application Support` on macOS, `%APPDATA%` on
  55. Windows, or `CONFIG` on Linux. The paths below are defaults; a client's existing config or location override can apply.
  56. | Agent (flag) | User config | Format / server key |
  57. | --- | --- | --- |
  58. | [OpenCode](https://opencode.ai/v2/docs/mcp-servers) (`opencode`) | `CONFIG/opencode/opencode.json` or `.jsonc` | JSONC · `mcp.servers` |
  59. | [Claude Code](https://code.claude.com/docs/en/mcp-quickstart) (`claude`) | `~/.claude.json` | JSON · `mcpServers` |
  60. | [Claude Desktop](https://modelcontextprotocol.io/docs/develop/build-server) (`claude-desktop`) | `APP/Claude/claude_desktop_config.json` | JSON · `mcpServers` |
  61. | [Cursor](https://cursor.com/docs/context/mcp) (`cursor`) | `~/.cursor/mcp.json` | JSON · `mcpServers` |
  62. | [Codex](https://developers.openai.com/codex/mcp) (`codex`) | `~/.codex/config.toml` | TOML · `mcp_servers` |
  63. | [VS Code, including Copilot agent mode](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) (`vscode`) | `APP/Code/User/mcp.json` | JSONC · `servers` |
  64. | [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp) (`windsurf`) | `~/.codeium/windsurf/mcp_config.json` or existing `CONFIG/devin/mcp_config.json` (`APP/devin` on Windows) | JSON · `mcpServers` |
  65. | [Amp](https://ampcode.com/manual/mcp) (`amp`) | `~/.config/amp/settings.json` or `.jsonc` | JSONC · literal `amp.mcpServers` |
  66. | [Antigravity](https://antigravity.google/docs/cli/mcp) (`antigravity`) | `~/.gemini/config/mcp_config.json` | JSON · `mcpServers` |
  67. | [Augment (Auggie CLI)](https://docs.augmentcode.com/cli/integrations) (`augment`) | `~/.augment/settings.json` | JSON · `mcpServers` |
  68. | [Cline](https://docs.cline.bot/mcp/configuring-mcp-servers) (`cline`) | `~/.cline/data/settings/cline_mcp_settings.json`; also recognizes the existing VS Code extension file in `APP/Code/User/globalStorage/saoudrizwan.claude-dev/settings/` | JSON · `mcpServers` |
  69. | [CodeBuddy Code](https://www.codebuddy.ai/docs/cli/mcp) (`codebuddy`) | `~/.codebuddy/.mcp.json` (or existing `mcp.json`) | JSONC · `mcpServers` |
  70. | [Cortex Code](https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code-mcp) (`cortex`) | `~/.snowflake/cortex/mcp.json` | JSON · `mcpServers` |
  71. | [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/mcp-memory.md) (`dsh`) | `$DSH_HOME/cordis.patch.yml` (default `~/.dsh/cordis.patch.yml`) | YAML · `insert` patch row |
  72. | [Factory Droid](https://docs.factory.ai/cli/configuration/mcp) (`droid`) | `~/.factory/mcp.json` | JSON · `mcpServers` |
  73. | [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) (`gemini`) | `~/.gemini/settings.json` | JSON · `mcpServers` |
  74. | [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) (`copilot`) | `~/.copilot/mcp-config.json` | JSON · `mcpServers` |
  75. | [Goose](https://goose-docs.ai/docs/guides/config-file/) (`goose`) | `CONFIG/goose/config.yaml`; Windows: `APP/Block/goose/config/config.yaml` | YAML · `extensions` |
  76. | [Grok Build](https://docs.x.ai/build/settings) (`grok`) | `~/.grok/config.toml` | TOML · `mcp_servers` |
  77. | [Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) (`hermes`) | `~/.hermes/config.yaml` | YAML · `mcp_servers` |
  78. | [Junie](https://junie.jetbrains.com/docs/junie-cli-mcp-configuration.html) (`junie`) | `~/.junie/mcp/mcp.json` | JSON · `mcpServers` |
  79. | [Kilo Code](https://kilo.ai/docs/automate/mcp/using-in-cli) (`kilo`) | `CONFIG/kilo/kilo.json` (also `.jsonc`, `config.json`) | JSONC · `mcp` |
  80. | [Kimi Code CLI](https://moonshotai.github.io/kimi-cli/en/customization/mcp.html) (`kimi`) | `~/.kimi/mcp.json` | JSON · `mcpServers` |
  81. | [Kiro](https://kiro.dev/docs/mcp/configuration/) (`kiro`) | `~/.kiro/settings/mcp.json` | JSON · `mcpServers` |
  82. | [LM Studio](https://lmstudio.ai/blog/lmstudio-v0.3.17) (`lm-studio`) | `~/.lmstudio/mcp.json` | JSON · `mcpServers` |
  83. | [Mistral Vibe](https://docs.mistral.ai/vibe/code/cli/mcp-servers) (`vibe`) | `~/.vibe/config.toml` | TOML · `[[mcp_servers]]` |
  84. | [Pi](https://pi.dev/docs/latest/mcp) (`pi`) | `~/.pi/agent/mcp.json` | JSON · `mcpServers` |
  85. | [Qoder CLI](https://docs.qoder.com/cli/mcp-reference) (`qoder`) | `~/.qoder/settings.json` | JSON · `mcpServers` |
  86. | [Qwen Code](https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/) (`qwen-code`) | `~/.qwen/settings.json` | JSON · `mcpServers` |
  87. | [Roo Code (VS Code)](https://docs.roocode.com/features/mcp/using-mcp-in-roo) (`roo`) | `APP/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` | JSON · `mcpServers` |
  88. | Trae CN (`trae-cn`) | `APP/Trae CN/User/mcp.json` | JSON · `mcpServers` |
  89. | [Warp](https://docs.warp.dev/agents/capabilities/mcp) (`warp`) | `~/.warp/.mcp.json` | JSON · `mcpServers` |
  90. | WorkBuddy (`workbuddy`) | `~/.workbuddy/mcp.json` | JSON · `mcpServers` |
  91. | [Zed](https://zed.dev/docs/ai/mcp) (`zed`) | macOS: `~/.config/zed/settings.json`; Linux: `CONFIG/zed/settings.json`; Windows: `APP/Zed/settings.json` | JSONC · `context_servers` |
  92. </details>
  93. For any other stdio MCP client, run `browse mcp`:
  94. ```json
  95. { "mcpServers": { "browse": { "command": "/home/you/.local/bin/browse", "args": ["mcp"] } } }
  96. ```
  97. (`browse install --agent none` prints this with your path.) Re-running install updates the entries it wrote and
  98. leaves servers named browse that it didn't write alone.
  99. ### Pairing
  100. There's nothing to sign in to. Each browser pairs with browse once and gets a key of its own (see
  101. [Security](#security)). If pairing didn't happen by itself, run `browse install` again, or run `browse pair`: it
  102. prints a one-time code (`XXXX-XXXX`, good for 10 minutes) and waits. Open **Extensions → browse → Options**, expand
  103. **advanced** (or click **Pair with a code**), enter the code under **Pairing code** and click **Connect**. `browse pair
  104. --list` shows paired browsers; `browse pair --revoke <browser>` unpairs one.
  105. ### Browser on another computer
  106. When your agent runs on one machine and your browser on another (over Tailscale, say), browse runs next to the agent
  107. and the extension connects to it across the network:
  108. 1. On the agent's machine run `browse install --remote` (or `browse set hostname 0.0.0.0` after installing). browse
  109. then listens on every network, restarting the relay if it runs, and prints this machine's address and a pairing
  110. code. Other computers reach only the extension link; the HTTP API answers on `127.0.0.1` only.
  111. 2. In the browser, open browse's setup page, choose **Connect an agent on another computer** and enter the address and
  112. code (or use **Relay address** and **Pairing code** under **advanced** on the options page).
  113. The connection isn't encrypted by browse; use a network that is (Tailscale or WireGuard), not the open internet.
  114. `browse set hostname 127.0.0.1` goes back to this computer only.
  115. ### Updates
  116. **Updates are automatic.** Every relay checks at launch and then hourly, whatever the update setting, and installs the
  117. channel's release when it isn't the one running (a rollback reaches everyone too):
  118. - every install reads its channel's manifest from the release service (`stable`, or `dev`/`beta` for those builds),
  119. with `browse/<channel>/<version>/cli/<install kind>` as the User-Agent;
  120. - the install script's binary replaces `~/.local/bin/browse` with the manifest's tarball after checking its size and
  121. SHA-256;
  122. - global installs run the package manager that installed them (`npm install -g`, `bun add -g`, `pnpm add -g`,
  123. `yarn global add`, `volta install`) to install `@opencode/browse@<the manifest's version>` into the same place. A
  124. release reaches the service a few minutes before npm, so a package manager that doesn't have the version yet is
  125. retried quietly;
  126. - `npx`, `bunx`, `pnpm dlx` and `yarn dlx` runs resolve the package themselves: they only tell you another release is
  127. out.
  128. A relay browse started restarts on the new version when it's idle (one you run with `browse serve` in a terminal keeps
  129. running until you restart it); agent tabs stay open and come back. A running MCP server keeps
  130. working with the newer relay until the agent restarts it. `browse update` updates now and `browse update --check` only
  131. looks. Choose **Tell me** or **Off** under **updates** on the extension's options page, or run `browse update --mode
  132. notify|off` (`OPENCODE_BROWSER_AUTO_UPDATE=off` in the environment overrides both). Off still checks hourly, and
  133. installs nothing. To go back, rerun the install
  134. script with `--channel <channel>` or `--version <version>`, or install `@opencode/browse@<version>` with your package
  135. manager. The Chrome Web Store updates the extension.
  136. **Dev builds**: every push to `dev` publishes one: `curl -fsSL https://opencode.ai/browse/install | bash -s --
  137. --channel dev`, or `npx @opencode/browse@dev install`. The store extension works with dev builds. To try the dev
  138. extension too, download https://anoma.ly/release/browse/extension/dev/chromium, unzip it, turn on **Developer mode** on
  139. your browser's extensions page, click **Load unpacked**, pick the folder and run `browse pair` (`browse extension`
  140. prints these steps on the dev channel). Remove the store extension first so only one browse runs in that profile.
  141. ### Uninstall
  142. ```sh
  143. browse uninstall
  144. ```
  145. It removes browse from every agent config it was added to, stops the relay, deletes `~/.local/bin/browse` (for the
  146. install script and npx installs), the PATH line it added and browse's files. A global package stays with its package
  147. manager: uninstall prints the command (`npm rm -g @opencode/browse`, `bun remove -g @opencode/browse`, ...). Remove the
  148. extension from your browser to finish.
  149. ## Using it
  150. - **Tabs are the handle.** `navigate` without a `tab` opens a new background tab and returns its id; every other call
  151. passes that `tab`. Agents use the tab ids they opened or were given, and leave other tabs alone unless you ask.
  152. Tabs can be opened with options that stick: `group` (the tab group's title, and a handle to close them together),
  153. `allowedOrigins`, `readOnly`, `keepVisible`, `keepOpen` (never close it as idle) and `browser`. Popups a page opens
  154. become agent tabs too.
  155. - **Tabs keep their ids, and an agent can name one.** `tabs` with `action: "new"` and an `id` like `work-mail` opens
  156. that tab once: asking again returns the same tab without navigating it, and every tool takes `work-mail` as `tab`.
  157. The id lasts while the tab stays open: a relay restart or extension reload keeps it, and a browser restart loses it
  158. (opening that id again is a fresh tab). `tabs` lists each tab's id, url, title, group, last use and whether a call is
  159. running in it. A tab opened with `keepOpen: true` stays until an agent or you close it; every other tab closes when
  160. idle like the rest.
  161. - **Agents open their own tabs** in the background of the window you last used, grouped together and collapsed unless
  162. you're looking at one (you can turn that off). Agents can't switch you to their tabs or bring a window to the front.
  163. Tabs nobody touches for 10 minutes close by themselves (never while something runs on them). Closing agent tabs never
  164. quits the browser: on Windows and Linux, browse leaves a new tab (or window) behind when it would close the last one.
  165. - **Relay restarts keep agent tabs.** The relay saves the tabs agents opened and their options, and takes them back
  166. when it starts again (after an update, say).
  167. - **Hand an agent one of your tabs** by clicking the toolbar button on it. The badge shows **ON**; click again to take
  168. it back. While an agent works the badge reads **RUN**, and **WAIT** when it needs you. The button always works: a
  169. click while an agent runs takes the tab back. The browser's debugging bar (**Cancel**, or **OK** in some browsers)
  170. disconnects browse from every tab; browse shows a notification when that happens, and clicking the browse button on a
  171. tab lends it again. Chrome's own pages, the Web Store included, can't be lent.
  172. - **Handoffs:** the page shows a small card with the site's origin. Do the human part, then click **Continue** on the
  173. card or the toolbar button. While a tab is recorded you get a system notification instead of the card.
  174. - **Several browsers at once.** Each connected browser has an id (like `chrome-macbook`); `status` lists them, and new
  175. tabs open in the default browser unless `browser` names another.
  176. - **Settings** (the extension's options page, applied right away): where agent tabs open (your window or their own),
  177. grouping (one shared group, one per task, or none), whether browse collapses agent groups by itself or leaves them
  178. as you set them (a handoff still opens its group so you can find the tab), when idle tabs close (10, 30, 60 minutes
  179. or never), human-like input, and handoff notifications. Agents can read and change these with the `settings` tool
  180. when you ask them to.
  181. ## Tools
  182. OpenCode, which composes tools in code mode, gets the plain tools. Every other MCP client gets `execute`, `status` and
  183. `tabs`; `execute` runs JavaScript that can call all of them. The relay decides by the client's name
  184. (`OPENCODE_BROWSER_TOOLS=plain|execute|all` on the relay overrides it).
  185. | Tool | What it does |
  186. | --- | --- |
  187. | `navigate` | Open a page: without `tab`, in a new background tab whose id it returns |
  188. | `snapshot` | A compact outline of the page with refs (`e12`) for the other tools, iframes included; scopes to the page's main area when there's exactly one and says what it left out |
  189. | `click`, `fill`, `type`, `press`, `select`, `hover`, `drag`, `scroll` | Act on a ref, selector or point, with human-like input |
  190. | `wait_for`, `dialog`, `upload`, `eval` | Wait for text, a URL or an element; answer dialogs; set files; run JavaScript in the page |
  191. | `screenshot`, `screenshot_diff` | The viewport, full page, an element or a rectangle; compare with a baseline |
  192. | `network`, `console` | Capture a tab's traffic (credentials redacted) or its console messages and errors |
  193. | `recording` | Record a tab to a video file |
  194. | `emulate`, `webmcp` | Viewport, color scheme, user agent, geolocation and more; tools a page offers through WebMCP |
  195. | `tabs` | List, open or close tabs (`group` closes a whole group; an `id` names a tab for good, and opens it if it's missing) |
  196. | `handoff`, `demonstrate` | Ask you to do something only a person can do; ask you to show a flow while it records your steps |
  197. | `settings`, `status` | Read or change your settings when you ask; the relay, browsers, pairing state and what to do next |
  198. | `execute` | For other clients: JavaScript with a Playwright-style `page`, `snapshot()`, `ref()`, `handoff()`, `state` and `browse.<tool>()`. Each result starts with the tab it ended in, to pass back as `tab` |
  199. Everything is a CLI too: `browse navigate https://example.com` prints the new tab's id, then `browse snapshot --tab
  200. <id>`, `browse click e12 --tab <id>`, `browse execute --file script.js`. `browse tools` lists them and `browse <tool>
  201. --help` shows a tool's options.
  202. ## How it works
  203. <picture>
  204. <source media="(prefers-color-scheme: dark)" srcset="assets/how-dark.png">
  205. <img src="assets/how-light.png" alt="Three machines on one bench, cabled in a line: the agent's terminal calling browse, the relay box in the middle, and the computer whose browser the agent drives.">
  206. </picture>
  207. The agent starts `browse mcp`, a small stdio proxy, which starts the relay on demand and forwards each call to it on
  208. `127.0.0.1:19988` (or the next free port from 19990–19997 when another program holds it). The extension connects to
  209. the relay over a WebSocket and runs its commands in your browser through `chrome.debugger`.
  210. - **The relay** (`browse serve`, in `rust/`) keeps agent tabs, handoffs, recordings and network captures, talks the
  211. Chrome DevTools Protocol to each tab, and runs `execute` scripts in an embedded JavaScript engine (QuickJS). It
  212. runs until it's stopped (`browse restart`, `browse uninstall`, a signal) or restarts onto an update.
  213. - **The extension** (`src/`) runs the relay's commands through `chrome.debugger`, keeps agent tabs in collapsed groups
  214. by default (or their own window), closes idle ones, and shows the toolbar badge and the handoff card.
  215. - **Quiet in the page.** browse doesn't enable the CDP domains pages can detect, runs its own code in isolated worlds
  216. and leaves no globals behind. Input moves like a person: curved mouse paths, paced typing, gliding scroll (turn
  217. *Human-like input* off for full speed). This makes an agent hard to spot, not impossible: the browser shows its
  218. "started debugging" bar while the debugger is attached.
  219. Permissions: `debugger`, `tabs`, `tabGroups`, `storage`, `alarms`, `scripting` (to add the handoff card only to tabs
  220. agents use), `webNavigation` (to keep popups agents open with their other tabs), `notifications` (to tell you an agent
  221. needs you while it records a tab), and access to all sites so agents can work wherever you ask. Nothing leaves your
  222. computer except what your agent sends to its model provider; see the [privacy policy](store/privacy-policy.md).
  223. ## Security
  224. browse drives the browser you're signed in to, so it assumes that what an agent reads (a web page, an email) may try
  225. to steer it, and that other programs on your computer may try to use the relay.
  226. - **Relay token.** Every request to the relay needs the token in `~/.local/share/browse/relay-token` (readable only by
  227. you). The MCP server and CLI read it for you. The relay listens on `127.0.0.1` only (unless you open it with `set
  228. hostname`, and then only the extension link) and refuses cross-site browser requests and foreign `Host` headers.
  229. - **Pairing.** A pairing code works once, within 10 minutes; five wrong codes in a row void every pending one. A
  230. browser exchanges it for a random key of its own over a fresh key agreement (ECDH), so neither the code nor the key
  231. crosses the connection. On every later connection both sides prove they hold the key before the extension obeys
  232. anything, so a program that grabs the port first can't drive your browser. The relay accepts only the published
  233. extension IDs (plus any listed in `OPENCODE_BROWSER_EXTENSION_ORIGINS`).
  234. - **`execute` is sandboxed, not a boundary.** Scripts run in QuickJS inside the relay with CPU, memory and time
  235. limits, no Node, network or file access beyond the file roots (temp folders and `OPENCODE_BROWSER_FILE_ROOTS`).
  236. Treat code an agent runs as code running as you. The relay starts with an allowlisted environment, so your API keys
  237. aren't in it.
  238. - **CDP guardrails.** Clearing cookies, cache or site data, closing the browser and changing site permissions are
  239. refused. Closing a page is handled like closing a target: a tab you lent is released, not closed. Cookie and storage
  240. access is limited to the hosts of the tab's own pages. Agents can't open browser-internal pages, other extensions or
  241. local files, or raise windows over your work.
  242. - **Guardrails, not a data boundary.** `allowedOrigins` limits navigations, top-level documents and the tabs and popups
  243. an agent opens; requests a page makes itself (fetch, XHR, images, scripts, iframes) are not filtered. `readOnly`
  244. refuses clicks, hover, drag, typing, key presses, filling, selecting, uploads and navigation commands after the tab
  245. opens. Scrolling to an element or to the page's edges still works. `eval` and `webmcp` still run JavaScript in the
  246. page: they can read everything the page can, make requests as the page, and change it (click, submit, navigate).
  247. Snapshots, screenshots and the cookies the page itself can see stay readable. These keep an agent from wandering: for
  248. pages you don't want an agent to read, don't open them in browse.
  249. - **What output is masked.** `fill` hides values only for password and one-time-code fields. Snapshots leave out what's
  250. typed in editable fields, but not other page text. Network capture redacts credentials by name and shape (auth and
  251. API-key headers, cookie values, secret-named fields, token-like path segments), so a value under an ordinary name can
  252. still come through. `eval` results, console messages, page text and screenshots are returned as they are.
  253. - **WebMCP tools come from the page.** Their names, titles, descriptions, schemas, annotations, `origin` and results are
  254. whatever a page supplies; browse doesn't verify them, and an annotation like `readOnly` is only the page's word. Treat
  255. them like any other page text, not as instructions from the user.
  256. - **Bot challenges.** After a navigation browse reports Cloudflare, captcha walls and "access denied" pages and tells
  257. the agent to hand interactive ones to you. It never solves them.
  258. - **Your tabs stay yours.** Agents use only tabs they opened or you lent them. Only a real click on the card or the
  259. toolbar button finishes a handoff, so a page can't fake it.
  260. Escape hatches, set in the environment you start your agent from. The relay inherits `OPENCODE_BROWSER_*` variables
  261. when it starts: it stops after 30 minutes without use, or run `browse restart` from a shell with the same variables:
  262. | Variable | Effect |
  263. | --- | --- |
  264. | `OPENCODE_BROWSER_ALLOW_ALL_COOKIES=1` | Let tabs read and write every cookie in the profile |
  265. | `OPENCODE_BROWSER_ALLOW_ALL_STORAGE=1` | Let tabs use every site's storage, and load resources from any host with your credentials |
  266. | `OPENCODE_BROWSER_ALLOW_FOREGROUND=1` | Allow bringing a tab's window to the front |
  267. | `OPENCODE_BROWSER_ALLOW_FILE_URLS=1` | Allow `file:` URLs |
  268. | `OPENCODE_BROWSER_FILE_ROOTS` | More folders tools may read and write (path-list separated) |
  269. | `OPENCODE_BROWSER_AGENT_WINDOW=separate` | Open agent tabs in a separate window (`current`: in yours), overriding the options page |
  270. | `OPENCODE_BROWSER_HUMAN_INPUT=0` | Send input at full speed; overrides the options page |
  271. | `OPENCODE_BROWSER_AUTO_UPDATE=notify` | Only tell about new versions (`off`: check, but never install or tell; `on`: install them, the default) |
  272. | `OPENCODE_BROWSER_CHALLENGE_WAIT_MS=15000` | How long to wait for a bot check the browser clears by itself |
  273. | `OPENCODE_BROWSER_EXTENSION_TIMEOUT_MS=30000` | How long the relay waits for the extension to answer a command |
  274. | `OPENCODE_BROWSER_PING_TIMEOUT_MS=10000` | How long a ping may go unanswered before the browser counts as asleep |
  275. | `OPENCODE_BROWSER_PORT=20000` | Pin the relay's port, with no fallback. The extension finds only browse's own ports (19988, 19990–19997) by itself, so enter `localhost:<port>` as its relay address when you pair |
  276. | `OPENCODE_BROWSER_TOOLS=plain\|execute\|all` | Which tools every client gets |
  277. ## Troubleshooting
  278. - `browse status` shows the install, the agents browse is set up in, updates, the relay, the extension and agent tabs,
  279. and says what to do when the extension is missing, unpaired, closed or out of date. Agents get the same from the
  280. `status` tool.
  281. - After the relay restarts, the extension reconnects by itself within about half a minute; calls made in the meantime
  282. wait for it.
  283. - An agent says browse's tools are missing: restart the agent (or reload its MCP servers) after `browse install`.
  284. - "The browser isn't answering" while the computer is very busy: raise `OPENCODE_BROWSER_EXTENSION_TIMEOUT_MS` and
  285. `OPENCODE_BROWSER_PING_TIMEOUT_MS`.
  286. - Logs: `~/.local/state/browse/logs/relay.log`.
  287. - Another program's server on port 19988: browse takes the next free port from 19990–19997 and the extension finds it
  288. there. A port held by something that doesn't answer HTTP stops it; stop that program or set `OPENCODE_BROWSER_PORT`.
  289. - The extension says it's not paired, or the relay refused it: run `browse install` again, or `browse pair` and enter
  290. the code in the extension's options.
  291. - An agent says browse was updated and its MCP server must restart: an MCP server started before an update to this
  292. version can't talk to the new relay. Restart the agent.
  293. ## Development
  294. ```sh
  295. bun install && bun run dev # rebuilds the extension into dist/ on change; load it unpacked, reload to pick it up
  296. bun run typecheck && bun test ./test
  297. cd rust && cargo test --workspace && cargo run -p browse -- status
  298. ```
  299. A build from a checkout (`cargo run -p browse -- install`) is used in place and never updates itself. The extension in
  300. `dist/` keeps the manifest key, so it loads with the unpacked ID the relay trusts; run `browse pair` to pair it.
  301. [RELEASING.md](RELEASING.md) has the release flow (dev builds from every push to `dev`; stable releases only from the
  302. Release workflow in GitHub Actions), and [rust/PLAN.md](rust/PLAN.md) the layout of the Rust crates. `cli/` is the
  303. earlier TypeScript implementation, kept as a reference.
  304. ## Contributing
  305. We don't take pull requests. [Open an issue](https://github.com/anomalyco/browse/issues)
  306. describing the bug or idea, and our agents usually turn it around fast.
  307. ## License
  308. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.