Guides

Browser automation

Anymo's browser automation is local-first and kernel-governed. Browser actions are normal registry tools, so every call flows through policy, hooks, and the event log before a real browser moves.

The path of every browser action

agent request -> ToolRegistry -> policy/hooks -> BrowserTool -> BrowserBridge -> workers/browser-local

The browser worker never grants itself permission. It only receives JSON-RPC requests after the Hive Kernel has evaluated the tool call, run hooks, and recorded sanitized tool material.

You may not need a browser

Static web.fetch and web.extract remain available for plain HTTP pages. Use browser tools only when JavaScript rendering, tab state, or page interaction is required.

Tools

Tool	Mutates browser state	Default auto behavior
`browser.open`	yes	approval required
`browser.observe`	no	allowed unless target URL is sensitive
`browser.click`	yes	approval required
`browser.type`	yes	approval required; credential fields are denied
`browser.scroll`	yes	approval required
`browser.wait`	no	allowed unless target URL is sensitive
`browser.extract`	no	allowed unless target URL is sensitive

Each input accepts a mode field:

plan: read-only planning posture. Mutating actions are denied before worker dispatch.
manual: every browser action requires approval.
auto: safe read and observe actions can run; mutating, sensitive-domain, and destructive actions require approval.

Connecting a browser

Standing up the browser path today is a three-step, manual process. There is no single turnkey anymo browser command yet; you start the browser and the worker yourself, then point Anymo at the worker with two environment variables.

Two distinct sets of environment variables are involved. Do not confuse them:

Where	Variables	Purpose
Worker process	`ANYMO_BROWSER_CDP_URL`, `ANYMO_BROWSER_PORT`, `ANYMO_BROWSER_TOKEN`	Which DevTools endpoint to drive, which loopback port to listen on, and the bearer token it requires
Anymo CLI / desktop	`ANYMO_BROWSER_BRIDGE_URL`, `ANYMO_BROWSER_BRIDGE_TOKEN`	Where the running worker is and its token, so the `browser.*` tools join the registry

Start a Chromium-compatible browser with remote debugging
You start the browser yourself; no automation framework is bundled or installed. Use a dedicated profile, since modern Chrome rejects remote debugging against the default profile:
sh
```
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$PWD/.anymo/cdp-profile"
```
Start the local browser worker
sh
```
ANYMO_BROWSER_TOKEN="$(openssl rand -hex 32)" \
ANYMO_BROWSER_CDP_URL="http://127.0.0.1:9222" \
ANYMO_BROWSER_PORT=47832 \
bun run --cwd workers/browser-local start
```
On start the worker prints a JSON line with its endpoint and token, for example {"url":"http://127.0.0.1:47832","token":"…"}. Those two values are exactly what Anymo needs next.
Point Anymo at the worker
Export the worker's URL and token as the bridge variables in the shell that runs anymo:
sh
```
export ANYMO_BROWSER_BRIDGE_URL=http://127.0.0.1:47832   # = the worker's printed url
export ANYMO_BROWSER_BRIDGE_TOKEN=<the worker's printed token>
```
The CLI wires the bridge from those two variables automatically and registers the browser.* tools; there is no Rust code to write. In the desktop app, configure the same worker endpoint in Settings.

Remote debugging is powerful

A CDP endpoint can inspect and control tabs, cookies, storage, extensions, authenticated sessions, and page contents. Keep it on loopback, do not expose it to a LAN or tunnel, and prefer a dedicated profile.

Worker protocol

workers/browser-local is a Bun/TypeScript JSON-RPC 2.0 worker. It binds to loopback only and requires Authorization: Bearer <token> on every request. Supported methods: browser.health, browser.listTabs, browser.openUrl, browser.observe, browser.screenshotMetadata, browser.click, browser.type, browser.scroll, browser.wait, browser.extract, browser.close.

Safety controls

Transport is localhost-only, with a per-session bearer token on every request.
Kernel browser tools sanitize hook and event input and output; URLs, titles, text, and error data are capped before returning to the kernel.
Secret-like keys and browser typed text are redacted from hook and event material.
Sensitive domains require approval in auto mode.
Typing into credential, payment, token, or secret fields is denied.
Upload and download selectors are denied; file transfer needs a separate explicit approval path.
Worker timeouts cap browser operations.
No hosted browser, cloud browser, signup, API-key, or telemetry flow is used.

Tests

Mocked tests do not require a browser:

cargo test -p hive-kernel --test browser
bun run --cwd workers/browser-local test

Manual tests are skipped by default because they require a locally running Chrome or Edge with remote debugging enabled:

bun test workers/browser-local/tests/manual.chrome.test.ts