Skip to content
Docs menu

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.

View .md

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

  • 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

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

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

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

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 Code

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