Skip to the content

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.

Steps marked preview rely on a package that has not passed its release gate.

Enrol a Touch ID key on your Mac, keep the presence watcher running, and approve each command your policy asks about with your fingerprint: the prompt shows exactly what will run, the approval is good for that one call, and nothing the agent does on its own can give it.

Not walked: the walk runs on Linux, which has no Secure Enclave or Touch ID. What CI checks instead is agentgarmd's root presence suites on Linux: the self-approval red-team suite, signing with FIDO2-format software keys, and enrolment and approval end to end through the real agentgarm CLI with a stand-in FIDO2 tool. Neither uses the Secure Enclave; a run on a Mac with Touch ID is still to be recorded.

1. Enrol a Touch ID key

Presence approvals need a root install. An administrator first opens a 5-minute enrolment window for you with sudo agentgarm enrol --open; it admits one key, and agentgarmd refuses to open one from inside a governed task. Then, as yourself, run agentgarm enrol: it creates a Secure Enclave key that signs only after a Touch ID match, and agentgarmd binds it to your user and records the enrolment in the audit log. On a machine enrolled in Central Lite preview, an administrator can issue you a presence enrolment grant instead of opening the window with root (enrol developer machines). A Mac without Touch ID uses a FIDO2 security key, as in the last step.

A no-root install has no presence boundary, since agentgarmd runs as the same user as the agent. There every presence request is refused, and an ask falls back to the agent's own prompt, or is denied where the agent has none.

sudo agentgarm enrol --open "$USER"     # an administrator opens the window
agentgarm enrol                         # you create and enrol the key, within 5 minutes

2. Keep the presence watcher running

agentgarm presence watch receives your approval requests one at a time and asks for Touch ID. Start it in a terminal of your own, outside any agent: agentgarmd refuses it to a process inside a governed task, so an agent never sees what is waiting. To see your key's state and the requests still waiting for a signature, open the dashboard's Approvals screen; it is read-only, and approving happens only in the watcher. agentgarm doctor also reports whether your key is enrolled, revoked or missing. To have the watcher start by itself preview, an administrator runs sudo agentgarmd install --presence-watch: it starts in each desktop login session (a LaunchAgent on macOS, a systemd user unit on Linux), never in an SSH session, and exits quietly while you have no key.

agentgarm presence watch
agentgarm ui --open
agentgarm doctor
The dashboard's Approvals screen, with the presence key's state and the requests waiting for it

3. Read what the prompt shows

With a key enrolled, when the policy asks about a call, such as sudo in the default Claude Code pack, the hook denies it for now and tells the agent to confirm the prompt in agentgarm presence watch, then retry. The Touch ID prompt reads “approve for AgentGarm:” followed by the command exactly as it will run, in order, with secrets replaced. Newlines, escape sequences and characters that hide or reorder text are shown as \u{..} escapes, and a request longer than 512 characters is refused rather than cut short. Only agentgarmd's own verdict of ASK issues a prompt, so no process can make you see one of its choosing.

An approval prompt showing the exact command, waiting for a fingerprint

4. Approve with your fingerprint, or refuse

Touch the sensor to approve: the watcher prints approved: with the command, and the agent's retry of exactly that call, in that task, is allowed once and recorded with the approval. Cancel the prompt to refuse (declined:), or do nothing: the request expires after 30 seconds and the call stays denied.

A click on a local dialog is not enough, because the agent runs as you and could produce one. Touch ID is the only accepted factor, with no password fallback, and a synthetic event cannot produce a fingerprint match. The signature covers this one request, so it cannot be replayed or moved to another command. For sessions started with agentgarm run, the sandbox keeps the agent away from the key and the watcher, and approvals rate B; hooks-only sessions rate C.

Each approval covers one call. Where a rule allows it, agentgarm presence grant preview turns one ask into a 5-minute grant for exactly that command in that task, approved the same way (trace a task). The same watcher confirms approvals that are not a retried call preview: new hooks, plugins and MCP servers held at launch, which you approve with agentgarm approve (catch poisoned agent configs); a rollback of files under a legal hold with agentgarm rollback --force-held; and, on a Mac, a computer-use agent's click or key press on a protected element, which the airbag drops and your approval turns into a 60-second grant for that element in that task (govern computer-use agents).

See also

Check that protection is on

See whether AgentGarm's services are up, what assurance level each agent session has and why, and what to do about a bypass alert.

5. Re-enrol after a fingerprint change

Adding or removing a fingerprint invalidates the key for good. The next time the watcher cannot sign, it tells agentgarmd, which revokes the key, and the watcher stops with a message saying approvals are blocked until you re-enrol. Until then every ask is denied; it does not fall back to the agent's own prompt, and the revocation survives a restart. Re-enrol as in the first step, then start the watcher again. On macOS the AgentGarm menu bar app preview also shows the revocation and offers “Re-enrol Presence Key…”, which asks for an administrator's password to open the window and then enrols the new key.

sudo agentgarm enrol --open "$USER"
agentgarm enrol
agentgarm presence watch

6. Replace or retire a key when a Mac is lost or a person leaves

The key never leaves the Mac it was made on: its private half stays in that Mac's Secure Enclave, and the handle that reaches it opens only there and only with the enrolled person's fingerprint, so a lost Mac's key cannot approve anything elsewhere. Each user account on a Mac has one key; enrolling a new one for that account in a fresh window replaces the old and drops its pending requests. There is no command yet that removes a key without enrolling another, so when a person leaves, their account's key stays enrolled until that account is removed or re-enrolled: hand the Mac over under a new account and remove the old one. On a fleet, stop trusting a lost Mac by revoking the machine in Central Lite preview (enrol developer machines), so every service refuses its certificate. If the lost Mac held a remote approver's passkey, revoke that approver (approve CI jobs); if it held a Central Lite admin's only passkey, the admin recovers with a one-time code from Central Lite's host (stand up Central Lite). Recovery adds a passkey but does not remove the old one, so it does not shut out whoever holds the lost Mac.

On a fleet whose people come from your identity provider preview, deactivating a person who leaves ends their console sessions, stops Central Lite counting the remote approver keys they hold, and ends the gateway keys AgentGarm issued them on every machine (offboard someone). Their Touch ID key on their own Mac is untouched: remove or re-enrol that account as above. Which console roles may answer a remote approval is in Give people the right access in the console.

sudo agentgarm enrol --open <user>
agentgarm enrol   # as that user

7. Require presence on a rule

preview

Add presence: required to an ask rule when the agent's own prompt must never answer it. When no presence key this host accepts is active for the user (none enrolled, a revoked key, or a no-root install), agentgarmd turns that ask into a deny, enforced by agentgarmd itself, and the reason says how to enrol, or, on a no-root install, that presence cannot be verified there. With a key enrolled nothing changes: the ask goes to the watcher as above. In audit mode the deny is recorded and the call allowed, as for every ask.

security_boundaries:
  execution:
    rules:
      - id: privilege-escalation
        ask: { exec: [sudo, sudoedit, su, doas, pkexec, run0], presence: required }

See also

Allow, ask or deny shell commands

Write command rules on the parsed command and its wrappers, not its text, choose between asking and denying, and replay commands before you rely on them.

8. Approve with a security key on Linux or a Mac without Touch ID

preview

On Linux the same commands use a FIDO2 security key by default: agentgarm enrol creates a credential on the key, and the watcher asks for the key's PIN (or its built-in verification) and a touch, where doing nothing declines. A Mac without Touch ID (a Mac mini, or a laptop closed on a desk) takes the same key with --method fido2, and the watcher then picks the key by itself. Without a key, agentgarm presence watch --method polkit asks polkit for your password instead; that is labelled not presence-backed, rates C, and never answers a rule with presence: required. On a headless machine enrolled in Central Lite, an ask rule marked approval: remote goes to an approver's passkey on another device instead (govern a headless machine). Windows Hello is built, but stays switched off until its device tests are recorded.

sudo agentgarm enrol --open "$USER"
agentgarm enrol --method fido2
agentgarm presence watch --method fido2
agentgarm presence watch --method polkit