Guide 1 of 61 · Getting started
Watch your agent for a week, then enforce
Start 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.
Start a policy in audit mode, where its rules decide and record every action but let through what they would deny or ask; work as usual; see what enforcing it would have blocked in your own history; fix the rules that would get in the way; then switch it to enforce.
1. Install the pack in audit mode
On a no-root install, agentgarm policy init writes the default pack for your agent into your policy directory. Every pack ships with mode: audit. A root install already holds them all: sudo agentgarmd install writes every default pack, in audit mode, into the system's policy directory before agentgarmd starts, unless a policy is already there, so check that your agent's is. policy init never replaces a file that is already there unless you add --force; with --dir naming the system's directory, that puts back the shipped pack. agentgarmd reads the policy directory when it starts, so restart it after policy init: until then the pack is not in force, and your agent's actions are decided by default.yaml, or allowed when there is none.
agentgarm policy init claude-codels /etc/agentgarm/agents.d # Linux
ls "/Library/Application Support/AgentGarm/agents.d" # macOSsudo agentgarm policy init claude-code --dir /etc/agentgarm/agents.d --forceschema: agentgarm.com/schemas/agents/v1
name: claude-code
version: "1.1.0"
mode: auditsystemctl --user restart agentgarmdsudo systemctl restart agentgarmd # root install, Linux
sudo launchctl kickstart -k system/com.agentgarm.agentgarmd # root install, macOS
launchctl kickstart -k gui/$(id -u)/com.agentgarm.agentgarmd # no-root install, macOSChecked by the walk: these commands ran as written on a no-root Linux install and a root install on Linux.
2. Work as usual, through AgentGarm
Start the agent with agentgarm run. In audit mode every command, file access and connection is still decided by the policy's rules and recorded with the verdict enforcing them would give, and what they would deny or ask is let through. The sandbox agentgarm run builds from the policy applies in either mode: its denied paths stay closed, and the network is reachable only through the proxy. Commands and the agent's file tools reach the policy only through the agent's hooks, which a root install puts in place (Govern Claude Code); on a no-root install Claude Code has none, so the history holds its model calls and network connections, and what the sandbox refuses is not recorded as a decision. Use the agent for real work for about a week, so the history covers what you actually do.
agentgarm run -- claudeChecked by the walk: this command ran as written on a no-root Linux install.
3. Check that the policy is the one in force
agentgarm status lists each policy file with its path, content hash and modification time, and flags one that changed on disk since agentgarmd loaded it. The dashboard's Policy screen shows the same, with each file in force or skipped and why. While the pack is in audit mode the dashboard's “Denied or asked” lists only what a built-in rule refused, not what the pack's rules would block; that is the next step.
agentgarm statusagentgarm ui --openChecked by the walk: this command ran as written on a no-root Linux install.
4. See what enforcing it would block
agentgarm policy lint --blast-radius replays the policy's agent's decisions among your last 500 under the enforce verdict. It counts what would now be blocked (an allow that becomes an ask or a deny, an ask that becomes a deny) and loosened, and lists up to 20 of each with the rule that decides it, in lines such as blast radius: 6 decisions replayed; 3 would be blocked, 0 loosened, and exits 1 when anything would be blocked. A root install's packs are readable by everyone, so lint the file in place as yourself.
A week of work is usually more than 500 decisions. To replay all of it, export the week's decisions with agentgarmd replay export (times in RFC 3339, UTC; on macOS, date -v-7d instead of date -d '7 days ago') and replay that file with --events.
Two things to check by hand: the replayed requests were redacted before they were stored, so a secret appears as its placeholder; and a recorded decision carries no workspace, so a recursive delete run from a subdirectory into another part of the same workspace can show as blocked by the outside-the-workspace rule.
agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml --blast-radiusagentgarm policy lint ~/Library/Application\ Support/AgentGarm/agents.d/claude-code.yaml --blast-radiusagentgarm policy lint /etc/agentgarm/agents.d/claude-code.yaml --blast-radius # Linux
agentgarm policy lint "/Library/Application Support/AgentGarm/agents.d/claude-code.yaml" --blast-radius # macOSagentgarmd replay export --policy claude-code --user --since "$(date -u -d '7 days ago' +%FT%TZ)" --until "$(date -u +%FT%TZ)" --out week.jsonl
agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml --blast-radius --events week.jsonlChecked by the walk: these commands ran as written on a no-root Linux install, and the output showed would be blocked and would be blocked.
5. Fix the rules that would get in the way
For each blocked line, decide whether it should be. Change the rule that blocks what you need, and run the lint again: it also reports a rule that another rule shadowed, a duplicate, a conflict between two rules with the same predicates, and a policy that would deny everything. Repeat until the report shows nothing blocked, or only what you mean to block.
6. Switch to enforce
Change mode: audit to mode: enforce. The lint exits 1 on any lint error or anything newly blocked, so run it once more first. agentgarmd keeps enforcing the file it loaded until it restarts, so restart it as in the first step.
agentgarmd lints the policy again as it loads it. An enforce-mode policy with a lint error is rejected and fails closed: every decision for its agent is denied, and agentgarm status marks it “REJECTED (fails closed)”. The one exception is a policy that denies everything on purpose, which loads as written.
The pack's hooks do not follow on their own. The shipped packs set the top-level on_internal_error: fail_open_alert, so a hook that gets no decision from agentgarmd lets the call through. If a missed decision should deny, set on_internal_error: fail_closed as well. Hooks take their fail mode from the pack when they are installed, so on a root install run sudo agentgarmd hooks install for the agent again. hooks status says whether the hook file is still what that install wrote; for Claude Code, the drop-in then reads onFailure: "block".
The same order serves outbound inspection preview, which reads what launched agents upload to paste sites and webhooks: its sites start in their own Audit mode, a week of findings shows what its Block mode would have stopped, and you block site by site. Switching the policy to enforce blocks nothing there by itself, since each site keeps the mode its entry names; while the policy is in audit mode, every site stays in Audit (switch a site to Block).
sudo agentgarmd hooks install claude-code
sudo agentgarmd hooks status claude-codeSee also
Govern Claude CodeInstall the Claude Code pack, put AgentGarm's hooks in Claude Code's managed settings, run it through the launcher and proxy, and check what is enforced.