Browser tools and the browser extension
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.
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
| 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
--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
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/- In Chrome, open
chrome://extensions, turn on Developer mode, choose Load unpacked and pickdist/chrome-extension/venom-browser/. - Click the extension's icon, paste the pairing code and the relay URL, and press Connect.
- Run
venom --chrome-extension, or putbrowser: extensionin venom.yaml. - 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
- 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 atmax_usd(default $1) for the whole call.
Another desktop
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:
VENOM_BROWSER_RELAY=0.0.0.0:18765 venom --chrome-extensionEvery 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:
venom browser pair --rotate # a new code; every paired extension must pair againAn SSH tunnel (ssh -N -L 18765:127.0.0.1:18765 <venom-host>, then the default URL) works too.
Edge and Firefox
The same extension runs in Microsoft Edge and in Firefox 128 or later; venom --chrome-extension doesn't care which browser answers.
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 .xpiEdge 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
| 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). |
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
/browser in the TUI records a browser task once so it can be replayed without the model, in any browser mode:
/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
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.
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 CodeOnly the venom-browser entry is written or removed, after a backup <file>.venom-bak-<time>. Other clients take the usual shape:
{ "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
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
| 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: the browser flags with the rest.
- venom.yaml: the
browserkey. - Permissions: browser rules.