---
title: Browser tools and the browser extension
description: Give the agent a browser with --chrome, --chrome-headless or --chrome-attach, or drive your own logged-in Chrome, Edge or Firefox through the venom browser extension with venom browser pair, and serve the same tools to other agents with venom browser mcp.
section: integrations
order: 40
audience: [user, operator, builder]
sources: [docs/browser-extension.md, clients/chrome/manifest.json, clients/chrome/AGENTS.md, cli/src/browser-cli.ts, cli/src/branding.ts, cli/src/doctor.ts, packages/harness/src/browser/index.ts, packages/harness/src/browser/relay.ts, packages/harness/src/extensions/browser-tasks.ts, docs/adr/0032-browser-extension-transport.md, docs/adr/0034-encrypted-browser-relay.md, docs/adr/0035-browser-tools-over-mcp.md, docs/adr/0036-firefox-and-edge-extension.md, docs/architecture.md, docs/venom-config.schema.json]
features: [integrations.chrome, integrations.browser]
---

venom's browser tools (`browser_navigate`, `browser_read`, `browser_click`, `browser_type`, `browser_screenshot` and the rest) can reach a browser four ways: a Chrome venom launches in a window, the same headless, a Chrome you started with a debugging port, or your own everyday browser through the venom browser extension. The tools, the permission gate (first action on a site, form submissions, password and card fields ask), screenshot masking and the audit log are the same in every mode; only how the commands reach the browser differs.

## Choose a mode {#modes}

| Flag | `browser` in venom.yaml | What the agent gets |
|---|---|---|
| (none) | `on` (default) | With Chrome, Chromium, Edge or Brave installed, one tool, `browser_navigate`; the rest and a headless browser start on its first call. |
| `--chrome` | `window` | Every browser tool from the start, in a Chrome window you can watch (a temp profile behind venom's guard proxy). |
| `--chrome-headless` | `headless` | The same, headless. |
| `--chrome-attach <port>` | | The tools on a Chrome you started with `--remote-debugging-port=<port>`; its logins are in reach. |
| `--chrome-extension` | `extension` | The tools on your own Chrome, Edge or Firefox through the venom extension, one window per agent. |
| `--no-chrome` | `off` | No browser tools. |

A flag wins over the `browser` key. `VENOM_CHROME` names the browser binary the launched modes start (default: the installed Chrome, Chromium, Edge or Brave). `venom doctor` has a Browser section that reports the browser found, the relay, the extension and the MCP clients registered.

## The browser extension {#extension}

`--chrome-extension` drives your own browser, logged in as you, through a small extension that uses `chrome.debugger`. No `--remote-debugging-port`, no second profile: clicks, keys and scrolls are trusted input events, and screenshots are what the tab shows. The browser can be on this machine or another desktop.

### Pair it {#pair}

```bash
venom browser pair                    # prints the pairing code and the relay URL (once per machine)
make chrome-extension                 # from a venom source checkout: dist/chrome-extension/venom-browser/
```

1. In Chrome, open `chrome://extensions`, turn on Developer mode, choose **Load unpacked** and pick `dist/chrome-extension/venom-browser/`.
2. Click the extension's icon, paste the pairing code and the relay URL, and press **Connect**.
3. Run `venom --chrome-extension`, or put `browser: extension` in venom.yaml.
4. Check it: `venom browser status`.

The extension's name comes from its locale file (the manifest's name is `__MSG_extName__`), so a renamed build changes it in one place: `make chrome-extension NAME="Acme Browser Agent"` writes a renamed copy and its Web Store zip into `dist/chrome-extension/acme-browser-agent/` without touching the sources.

### How it behaves {#extension-behaviour}

- **One window per agent.** Each venom process gets its own browser window, its tabs in a tab group named after the agent (`venom · repo`). Subagents get their own windows too, so parallel agents never touch each other's tabs or yours. Chrome shows "started debugging this browser" while a tab is attached; Cancel detaches it until the agent's next action.
- **The popup** shows the state (**Connected · encrypted**, **Connecting…**, **venom isn't running**, **Can't connect** with the reason), which venom holds the relay, the open agent windows, and each agent's last few actions (never typed text or a URL's query). **Stop** next to an agent detaches it until you press **Resume**. The toolbar badge shows the number of agent windows.
- **Input looks like a person's**: curved, eased mouse paths, a hover before each click, scrolling in small wheel ticks, typing key by key. A whole gesture is played locally by the extension, so timing holds even across a network. The agent's cursor, a frame and the current action are drawn in the page while it works, and hidden from its screenshots.
- **Anti-bot checks are yours.** venom never solves a CAPTCHA or similar check. It stops acting on that page, brings the window to the front, tells you, and waits up to two minutes for you.
- **Several sites at once**: in this mode the main agent can fan a task out across up to 12 sites with `browser_parallel` (3 at a time by default, at most 6), each in its own window, capped at `max_usd` (default $1) for the whole call.

### Another desktop {#remote}

The relay listens on `127.0.0.1:18765`. For a browser on another machine, start venom with the relay on another interface and point the extension at `ws://<venom-host>:18765`:

```bash
VENOM_BROWSER_RELAY=0.0.0.0:18765 venom --chrome-extension
```

Every frame after the handshake is encrypted and authenticated with keys only the paired ends can derive (an ephemeral P-256 exchange authenticated by the pairing code, then AES-256-GCM), so someone on the network can't read pages, screenshots or keystrokes, change a command, or pose as either end. A fresh key exchange per connection means a code leaked later can't decrypt traffic recorded earlier. What isn't hidden: that a connection exists, its timing and frame sizes. Keep the pairing code secret, and rotate it if it leaks:

```bash
venom browser pair --rotate           # a new code; every paired extension must pair again
```

An SSH tunnel (`ssh -N -L 18765:127.0.0.1:18765 <venom-host>`, then the default URL) works too.

### Edge and Firefox {#edge-firefox}

The same extension runs in Microsoft Edge and in Firefox 128 or later; `venom --chrome-extension` doesn't care which browser answers.

```bash
make chrome-extension TARGET=edge       # dist/chrome-extension/venom-browser-edge/ + its Add-ons zip
make chrome-extension TARGET=firefox    # dist/chrome-extension/venom-browser-firefox/ + an unsigned .xpi
```

Edge is Chromium, so everything above holds; load it from `edge://extensions`. Firefox has no `chrome.debugger`, so the extension drives it with what Firefox has:

| | Chrome, Edge | Firefox |
|---|---|---|
| Clicks, keys, scrolling | Trusted input events | Synthesized page events (`isTrusted` false); most sites accept them, some ignore them |
| Screenshots | The tab's viewport | The same viewport, through `tabs.captureTab` |
| `alert`, `confirm`, `prompt` | Answered by venom, noted for the agent | Wait for you |
| A button inside a form | venom checks whether it submits | Counts as a submission (asks you) |
| What shows the agent is acting | The debugging bar and the overlay | The overlay only |

`venom browser status` prints the limits of the connected browser, and the agent is told once per session. Load Firefox's build from `about:debugging#/runtime/this-firefox` → **Load Temporary Add-on** (pick its `manifest.json`); a permanent install needs a signed `.xpi`. The add-on id is `venom-browser@usevenom.dev`; a renamed build takes `GECKO_ID=you@example.com`.

## venom browser {#venom-browser}

| Command | What it does |
|---|---|
| `venom browser pair [--rotate]` | Print the pairing code and relay URL (`--rotate`: a new code). The code is 32 random bytes in `~/.venom/browser/token`, mode 0600. |
| `venom browser status [--json]` | Whether the relay hub runs, which extension is connected (name, version, browser and its limits), and the agents' windows. `--json` for scripts. |
| `venom browser mcp [flags]` | Serve the browser tools over MCP on stdio to another agent (below). |
| `venom browser mcp install`, `uninstall` | Register or remove venom's MCP server in Claude Code, Cursor and Codex. |
| `venom browser replay <name>`, `venom browser scripts` | Replay a recorded browser task with no model calls; list, show or delete recorded scripts. |
| `venom browser task schedule <script> --cron <expr>` | Replay a recorded task on a schedule in `venom serve` (see [Scheduled agents](/docs/automation/schedules.md#browser-tasks)). |
| `venom browser watch <url>` | Watch a page or element for changes with no model; `venom serve` checks it. |
| `venom browser snapshot`, `diff`, `baselines` | Visual regression baselines at several widths and color schemes; `diff` exits 1 on a change. |
| `venom browser a11y <url>` | An accessibility audit: contrast, names, headings, landmarks, ARIA, focus, tab order, target sizes. |
| `venom browser profile …` | Form-filling profiles, the sites allowed to use them, and the fill log (field names, never values). |

The relay address for every command is `VENOM_BROWSER_RELAY` (`host:port`, default `127.0.0.1:18765`). The first venom in extension mode binds it and becomes the hub; the others connect to it. When the hub exits, the next one to bind takes over. There is no separate daemon.

## Recorded tasks: /browser {#record}

`/browser` in the TUI records a browser task once so it can be replayed without the model, in any browser mode:

```text
/browser record invoice          start recording; ask the agent to do the task
/browser record stop             save .venom/browser-scripts/invoice.yaml
/browser scripts                 list the recorded scripts
```

`/browser record cancel` drops a recording, `/browser record secret <param>` marks a parameter secret, and `/browser show`, `edit` and `delete` manage scripts. Text typed into fields becomes `{{param}}` placeholders; passwords, one-time codes and card numbers become secret parameters that are never saved and are asked for at replay. The agent replays with `browser_replay`; from the shell, `venom browser replay invoice --param month=2026-10`. A step that no longer matches the page stops the replay rather than clicking the closest thing.

## Other agents: venom browser mcp {#mcp}

The same tools work for any agent that speaks MCP: Claude Code, Codex, Cursor, Zed or your own app. Each client process gets its own window, with a tab group named after the client, and venom's permission gate, private-address guard, credential and payment checks and audit log (`~/.venom/audit.jsonl`) all still apply.

```bash
venom browser mcp install                      # Claude Code, Cursor and Codex, those found here
venom browser mcp install --client codex       # one client
venom browser mcp install --dry-run            # show what would change
venom browser mcp uninstall
claude mcp add venom-browser -- venom browser mcp     # by hand, for Claude Code
```

Only the `venom-browser` entry is written or removed, after a backup `<file>.venom-bak-<time>`. Other clients take the usual shape:

```json
{ "mcpServers": { "venom-browser": { "command": "venom", "args": ["browser", "mcp"] } } }
```

| Flag | What it does | Default |
|---|---|---|
| `--launch [--headless]` | A Chrome venom launches (temp profile, guard proxy) instead of yours. | your browser through the extension |
| `--attach <port>` | A Chrome started with `--remote-debugging-port=<port>`. | |
| `--relay <host:port>` | The relay to reach the extension through. | `VENOM_BROWSER_RELAY`, else `127.0.0.1:18765` |
| `--mode <mode>` | `default` (asks per site, submit, credential), `accept-edits`, `yolo` or `plan`. Sudo isn't offered. | `default` |
| `--allow`, `--ask`, `--deny <rule>` | Permission rules, such as `browser(domain:example.com)`; repeatable. | none |

Approvals go to the client's user through MCP elicitation. A client without elicitation can't ask anyone, so those calls are refused with the rule that would allow them; pass rules up front or put them in `~/.venom/permissions.json`. Tools served: `browser_navigate`, `browser_read`, `browser_screenshot`, `browser_click`, `browser_hover`, `browser_type`, `browser_press`, `browser_scroll`, `browser_wait`, `browser_tabs`, `browser_batch` and `browser_replay`. An app can embed the same server with `browserMcpServer()` from `@venom/harness`.

## A seat on a daemon {#seat}

A Venom Cloud daemon can give an agent a persistent browser on its own machine. It starts the session with `VENOM_BROWSER_CDP` (a `ws://` or `wss://` CDP address) and `VENOM_BROWSER_CDP_TOKEN` (a bearer token) in the environment, and the browser tools drive that browser; `VENOM_BROWSER_CLIENT_ID` names the client when several agents share one browser (default: a per-session id). The address is read only from the environment, never from a tool argument or the model, and it takes precedence over the other browser modes. The session acts only on tabs it opened itself.

`browser_type` accepts `{{secret:NAME}}` in its text: the value is typed without the model seeing it, only on a page whose origin the secret is bound to, and read-backs show `(secret: NAME)`.

## Troubleshooting {#troubleshooting}

| Symptom | Fix |
|---|---|
| Popup says **venom isn't running** | Start `venom --chrome-extension` (or `venom browser mcp`); the extension connects within seconds. |
| Close code 4401, wrong pairing code | The relay doesn't hold this code. Run `venom browser pair` on the venom machine and paste the code again. |
| Close code 4426 | The extension and venom speak different relay protocol versions. Update the older side. |
| The extension can't reach a remote venom | Start it with `VENOM_BROWSER_RELAY=0.0.0.0:18765`, open the port, or use an SSH tunnel. |
| Firefox can't act on pages | The add-on lacks website access; press **Allow on all sites** in its popup. |
| An MCP client's browser calls are refused | It has no elicitation. Pass `--allow` rules. |

## Related

- [CLI flags](/docs/cli/flags.md): the browser flags with the rest.
- [venom.yaml](/docs/configuration/venom-yaml.md#search): the `browser` key.
- [Permissions](/docs/harness/permissions.md): browser rules.
