Guide 29 of 61 · Protecting secrets and data
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.
Built, not yet claimed preview: this guide describes a package that has not passed its release gate.
Keep launched agents away from the desktop by default, and where an agent or an MCP server must drive it, run it in the computer-use posture: AgentGarm's airbag watches every synthetic click and key press, drops those aimed at password sheets, password managers, System Settings and the targets you add, or asks you with Touch ID, and the task stops whenever the airbag can't watch. macOS only.
1. Know which part covers what
There are three postures. Contained, the default for every agent and MCP server agentgarm run launches, gives no desktop input, screen capture, accessibility, pasteboard or Apple Events at all; the sandbox enforces it, which rates B. Computer use, which you turn on per agent or per MCP server, lets the task post input and capture the screen while the airbag drops its input on protected targets: B with a Developer ID build and accessibility and Apple Events left denied, C otherwise. Unlaunched covers desktop apps, hooks-only agents and your own tools, under the host rule unlaunched in default.yaml (off by default), and rates C.
None of them stops an accessibility action by an unsandboxed process that holds the Accessibility grant, an Apple Event sent through an app you have allowed to control another, or anything an agent does inside a virtual machine of its own. This is built for macOS only, and not yet claimed; no CI walk runs these steps, since they need a Mac's login session, Touch ID and its privacy grants.
See also
Govern browser agentsPut 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.
2. Keep launched agents contained, and check it
Launch the agent through agentgarm run and leave its policy without a security_boundaries.desktop section: it runs contained, so a script it writes cannot click, type, read the screen or the pasteboard, or script another app. agentgarm doctor checks the sandbox backend (Seatbelt) the posture rests on. Most agents need nothing more; go on only for one whose job is to drive the desktop.
agentgarm run -- claudeagentgarm doctorSee also
Check that protection is onSee whether AgentGarm's services are up, what assurance level each agent session has and why, and what to do about a bypass alert.
3. Install the airbag and grant it Accessibility
The airbag, AgentGarm Airbag, is a small background app (no Dock icon) that runs in your login session under its own LaunchAgent, com.agentgarm.airbag, and holds the Accessibility grant and nothing else. sudo agentgarmd install --airbag installs it for every user and starts it in each logged-in session; agentgarmd install --airbag --user installs it for you alone, beside a no-root install. Re-running the install restarts it, which is how an upgrade takes effect.
On its first run macOS asks once for Accessibility. Allow it in System Settings, Privacy & Security, Accessibility. Until it is granted, agentgarm doctor fails its airbag check and names the grant, and every computer-use task is refused or stopped. macOS keeps the grant only for a binary signed by the same identity: after a rebuild signed another way, such as a development build, remove every AgentGarm Airbag row from that list (and any older agentgarm-airbag row, from a build before the app) and add it again with + (an old row stays switched on but no longer matches). A Mac managed by an MDM can grant it with the profile template share/agentgarm/mdm/macos/agentgarm-pppc-airbag.mobileconfig; whether macOS then skips the prompt is not yet shown.
sudo agentgarmd install --airbagagentgarmd install --airbag --useragentgarm doctor4. Turn on computer use in audit mode, and launch
previewIn the agent's policy, set security_boundaries.desktop.posture: computer_use and keep mode: audit. Leave accessibility, apple_events and clipboard at deny unless the agent truly needs them: with accessibility or Apple Events open, its input no longer has to pass the airbag, and the task rates C. Restart agentgarmd, which reads policies only when it starts (until then agentgarm status shows the file as NOT LOADED and the agent launches contained), then launch it with agentgarm run. In audit mode the task starts even without a live airbag, demoted to C.
To give the desktop to one MCP server rather than the agent, keep the agent contained and set desktop on that server under mcp.servers; the gateway launches it in its own computer-use sandbox. Only a stdio server can have one.
security_boundaries:
desktop:
# Let the agent post input and capture the screen, under the airbag.
posture: computer_use
input:
# On a protected target: drop (the default), ask (drop, then a Touch ID
# grant for 60 seconds) or alert (pass and record).
on_protected: ask
# Tools that post input for you, by code requirement: their input passes.
allowed_posters:
- 'identifier "com.agilebits.onepassword7" and anchor apple generic'
# Your own targets, on top of the catalog's.
extra_protected:
- { bundle_id: com.example.payroll, reason: "pay runs" }
# A catalog target this agent needs; built-in ones cannot be opened.
allow_targets:
- { bundle_id: com.apple.Terminal, reason: "the agent runs its own tests here" }
# Keep the agent off AX, Apple Events and the pasteboard: input then
# reaches the desktop only through the airbag's tap.
accessibility: deny
apple_events: deny
clipboard: denysecurity_boundaries:
desktop:
posture: contained
input: { on_protected: drop }
capture: { on_sensitive_frontmost: alert }
mcp:
packages:
- { ecosystem: npm, name: "@example/computer-use-mcp", version: "0.3.1", integrity: "sha512-AAAA" }
servers:
- id: computer-use
package: "@example/computer-use-mcp@0.3.1"
desktop: { posture: computer_use, accessibility: deny, apple_events: deny, clipboard: deny }agentgarm policy lint claude-code.yamlsudo launchctl kickstart -k system/com.agentgarm.agentgarmd # root install
launchctl kickstart -k gui/$(id -u)/com.agentgarm.agentgarmd # no-root installagentgarm run -- claude5. Read what would have been dropped, and open what you need
In audit mode the airbag passes what it would drop and records it. Open the task in the dashboard: each record is a desktop input event naming the app, the element's role and title (as the app supplies it, at most 80 characters), the poster, and the action enforce would have taken. Only events on protected targets are recorded, never what was typed, and never a key's value.
The catalog protects password and authorization sheets, AgentGarm's own app and dashboard, Keychain Access, Passwords, System Settings, Bitwarden, Disk Utility, Finder's Empty Trash, destructive buttons in any app, and synthetic keys into Terminal. Add your own with extra_protected; open a catalog target this agent needs with allow_targets (the built-in ones cannot be opened); and list tools that post input for you, such as a password manager's autofill, in allowed_posters by code requirement, but only tools no agent can script.
agentgarm ui --openSee also
Trace what one agent task didFind an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last.
6. Move to enforce, with drop or ask
Set mode: enforce and restart agentgarmd again. on_protected then says what happens to synthetic input on a protected target: drop (the default) discards it; ask discards it and asks you to allow that element for 60 seconds; alert lets it through and records it. The agent is not told: it sees a screen that did not change. In enforce mode agentgarm run refuses a computer-use task while your airbag is not live, saying that the posture needs one, and a running task stops whenever the airbag stops answering or loses its grant. This is the posture's fail-closed path, enforced by agentgarmd.
agentgarm policy lint claude-code.yamlsudo launchctl kickstart -k system/com.agentgarm.agentgarmd # root install
launchctl kickstart -k gui/$(id -u)/com.agentgarm.agentgarmd # no-root installSee also
Watch your agent for a week, then enforceStart a policy in audit mode, see what enforcing it would have blocked in your own history, fix the rules that get in the way, then switch it to enforce.
7. Approve a desktop ask with Touch ID
With on_protected: ask, a dropped click or key press raises a Touch ID prompt in agentgarm presence watch, such as: allow task … to click AXButton "Empty Trash" (title supplied by the app) in com.apple.finder for 60 seconds? Posted by python3. Approve it and the agent's next attempt on that element passes, for that task only, for 60 seconds. A click loop raises one prompt, a task gets at most three prompts a minute and eight grants at once, and input from a process in no task is only dropped. Asking needs a root install with a presence key enrolled; on a no-root install the drop stands.
agentgarm presence watchSee also
Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only.
8. See why a task was suspended, and get it going again
A suspended task is stopped, its processes and everything they started, and every decision it asks for is denied with "this task is suspended". agentgarm status marks it SUSPENDED with each hold that keeps it stopped; the dashboard's runs show it as suspended. A task runs again only when its last hold is lifted, and a process you stopped yourself (Ctrl-Z) stays stopped.
airbag means your airbag stopped answering, lost Accessibility, or its tap was turned off: fix what agentgarm doctor names, and the hold lifts once the airbag is back. sensitive_frontmost lifts when the sensitive app leaves the front. breach is a budget or loop breach, and order a kill order across the fleet (Stop agents across a fleet), which only its lift removes. Holds survive a restart of agentgarmd.
Root can also remove an airbag, sensitive_frontmost or breach hold by hand, from outside every governed task: sudo agentgarm task resume with the task's id and --hold and its name. It answers with the holds still left, and refuses an order's. Resume is not built on Windows yet. For every kind of hold and who lifts it, see Find out why your agent stopped.
agentgarm statusagentgarm doctorsudo agentgarm task resume <task> --hold airbagSee also
Watch what agents can captureSee which agents can capture your Mac's screen, and alert, pause or end a task when a password manager or other sensitive app comes to the front.
9. Remove the airbag
First take posture: computer_use out of every policy, or those tasks are refused. sudo agentgarmd uninstall --airbag (or agentgarmd uninstall --airbag --user for your own) stops it in each session and removes its LaunchAgent; uninstalling AgentGarm removes it too. Then remove AgentGarm Airbag from System Settings, Privacy & Security, Accessibility. A running agent cannot do this for you: stopping or removing an AgentGarm LaunchAgent and resetting privacy grants are denied to every governed task.
sudo agentgarmd uninstall --airbagagentgarmd uninstall --airbag --user