Skip to the content

Govern browser agents

Put AgentGarm's browser shim in front of the browsers your agent launches, so each launch gets a fresh profile and its downloads wait in quarantine.

Built, not yet claimed preview: this guide describes a package that has not passed its release gate.

Put AgentGarm's browser shim in front of the browsers your agent launches through Playwright, Puppeteer or a browser command on PATH, so each launch gets a fresh profile instead of yours, automation reaches the browser through a mediated pipe, and downloads wait in quarantine; and know what the separate browser extension does for people pasting into AI chat sites.

1. Know which part covers what

Two parts are built. The browser shim governs the browsers an agent launches through Playwright, Playwright MCP, Puppeteer or a browser command such as google-chrome; it is built but not yet claimed. The browser extension governs people pasting into AI chat sites in Chrome and Edge, not agents. Neither governs a computer-use agent that drives the desktop rather than a browser: that is the computer-use posture and its airbag, on macOS.

See also

Govern computer-use agents

Let an agent drive your Mac's mouse and keyboard while AgentGarm's airbag drops its input on password managers, settings and other protected targets.

2. Turn on the browser boundary and launch through AgentGarm

agentgarm run puts the shim in front of the agent's browsers only when the agent's policy has a security_boundaries.browser section, or AgentGarm's config.toml sets shim = true under [browser]. It then points PUPPETEER_EXECUTABLE_PATH, PLAYWRIGHT_MCP_EXECUTABLE_PATH and CHROME_PATH at the shim, gives the task its own Playwright browsers directory whose browsers are the shim, and puts shim commands named google-chrome, chromium, msedge, firefox and others first on PATH.

If the shim is not installed beside agentgarm, or those directories cannot be made, the launch goes on without it: you are told, and the task is demoted to C.

security_boundaries:
  # With this section set, `agentgarm run` puts the browser shim in front of
  # the browsers the agent launches through Playwright, Puppeteer or a browser
  # command on PATH.
  browser:
    # Runtime.evaluate on the pipe: allow, alert (the default: forwarded and
    # recorded), ask or deny (both refused).
    runtime_evaluate: alert
    # Downloads go to quarantine (the default).
    download_quarantine: true
    # --disable-quic on every governed launch (the default).
    quic: disabled
    # Refuse --remote-debugging-port, so automation uses the pipe (the default).
    allow_remote_debugging_port: false
agentgarm run -- claude

3. Give each launch a fresh profile

Every browser the shim starts gets the task's own empty profile (--user-data-dir on Chromium-family browsers, -profile on Firefox), which agentgarmd removes when the task ends. A launch that names one of your real profiles (Chrome, Chromium, Edge, Brave, Arc or Firefox), by path, through a symlink into one, through a variable such as PUPPETEER_USER_DATA_DIR, or with --profile-directory and no directory of its own, is refused and recorded, and no browser starts.

A real profile carries your live session cookies, saved passwords and WebAuthn state, so an agent using it would act as you on every site you are signed in to. Under agentgarm run the sandbox also denies those directories whatever binary the agent runs, which rates B; in a hooks-only session it rates C.

See also

Limit what an agent can read, write and reach

Decide which files an agent may read and write and which hosts it may reach, know which layer holds each rule, and recognise a denial.

4. Keep automation on the mediated pipe

The shim inspects the DevTools protocol only on --remote-debugging-pipe, for Chromium-family browsers. Unless the policy sets allow_remote_debugging_port: true, it refuses --remote-debugging-port (Puppeteer's default, so launch Puppeteer with pipe: true), Firefox's Juggler pipe, Marionette and debugger server; an allowed port passes through unmediated. On the pipe, deny_methods and allow_methods list methods, and runtime_evaluate, runtime_call_function_on and add_script_on_new_document each take allow (forwarded), alert (the default: forwarded and recorded), or ask or deny, both refused, since the pipe cannot wait for an answer. Synthetic keyboard and mouse input is recorded as synthetic.

This rates C: an agent that runs the real browser binary directly bypasses the shim. On Windows there is no pipe relay, so the browser runs with its fresh profile only.

5. Release downloads from quarantine

With download_quarantine on (the default), every download goes to a staging directory of the task's. When one completes, agentgarmd copies it into its own quarantine, outside every agent sandbox, hashes and scans the copy for secrets, and removes the staged file; until then the download in progress is readable by the agent. To release one, run agentgarm-browser-shim --agentgarm-release-download from your own terminal outside the task, with the download's id, a destination directory and its quarantine directory: agentgarmd's own, browser-quarantine/<task>/<session> under its state directory, not the staging directory, which is refused. Release needs a presence approval, so it works only on a root install with a presence key enrolled, and it takes two runs: the first is refused with a challenge id; approve it, then run the same command again with --approval-id and that id. agentgarmd then checks the hash and scan again and writes the file without replacing one. A download that matched a secret rule is never released. With quic: disabled (the default), every governed browser starts with QUIC off.

See also

Approve risky actions with Touch ID

Enrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only.

6. Catch secrets people paste into AI chat sites

The extension checks a paste or drop into ChatGPT, Claude, Gemini or DeepSeek before the page sees it, and the whole prompt again at submit, with the same secret rules as the hooks and the proxy. In default.yaml, browser.on_secret says what a finding does: alert, block, or redact, which replaces a pasted secret with a placeholder and blocks at submit; in audit mode it is always alert. agentgarmd signs this into a policy the extension checks against this machine's key, pinned through the browser's managed policy. Until that key is pinned, the extension never asks the host and uses the on_secret of the browser's managed policy instead.

Its rule packs (chat sites and literal patterns, data only) are signed and accepted only under a key pinned the same way; with none pinned, only the rules bundled in the extension apply, and no AgentGarm key for public packs exists yet. The extension is not yet in the Chrome and Edge stores; the managed-policy templates are in share/agentgarm/mdm/. It rates C, since a person can turn it off or use another browser.

browser:
  on_secret: redact
The browser extension's popup over an AI chat site: the policy and rules in force, then the recent findings

See also

Keep secrets and card numbers out of prompts

See which credentials your agent sends its model provider, have the proxy replace them with cache-safe placeholders, and deny tool calls that carry one.

7. Force-install the extension in managed browsers

The extension reaches people through their browser's managed policy, which an MDM, Group Policy or the Linux policy directories set. share/agentgarm/mdm/fill.sh fills the templates from extension.env beside it (the store ids, update URLs and ON_SECRET; an environment variable of the same name overrides a line) and installs nothing: it writes, for Chrome and Edge, the Linux policy JSON, the macOS configuration profiles and the Windows .reg and ADMX files, each force-installing the extension, allowing the native-messaging host com.agentgarm.nm_host, turning QUIC off and setting on_secret. Until the store listings exist the ids in extension.env are empty, so set them yourself.

Two parts are per host. --node-pub with that host's node.pub, from agentgarmd's state directory, writes a second file pinning its node key, which lets the extension take its policy from agentgarmd; --host-path fills the native-messaging host's manifest, which you copy into the browser's native-messaging directory (for Chrome on Linux, /etc/opt/chrome/native-messaging-hosts/), and its allowed-origins file, which goes over the one agentgarm-nm-host reads in share/agentgarm/native-messaging/ beside its bin/; until it names the extension, the host serves nothing. On macOS only a profile an MDM installs is mandatory, and on Windows a browser outside a domain, Entra ID or Chrome Enterprise Core does not force-install an extension from outside the store.

CHROME_EXTENSION_ID=<chrome id> EDGE_EXTENSION_ID=<edge id> ON_SECRET=block   <prefix>/share/agentgarm/mdm/fill.sh --out mdm --node-pub /var/lib/agentgarm/node.pub --host-path <prefix>/bin/agentgarm-nm-host
sudo cp mdm/linux/chrome/*.json /etc/opt/chrome/policies/managed/
sudo cp mdm/native-messaging/com.agentgarm.nm_host.json /etc/opt/chrome/native-messaging-hosts/
sudo cp mdm/native-messaging/allowed-origins <prefix>/share/agentgarm/native-messaging/