Skip to the content

Govern Claude Code

Install 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.

Bring Claude Code under AgentGarm in one thread: its policy pack in audit mode, AgentGarm's hooks in Claude Code's managed settings failing open or closed as the pack declares, the launcher and proxy around each session, approvals, and a check of what is enforced and at what level.

1. Install the Claude Code pack in audit mode

On a no-root install, agentgarm policy init claude-code writes the Claude Code pack into your policy directory in mode: audit: it decides and records every action and blocks nothing yet. Restart agentgarmd to load it. A root install normally has it: sudo agentgarmd install writes every default pack, in audit mode, into the system's policy directory before agentgarmd starts, unless that directory already holds a policy. Check that claude-code.yaml is there, and if it is not, write it with policy init and --dir. To put back the shipped pack over one you edited, run policy init with --dir and --force, then restart agentgarmd.

Besides the command and credential rules every pack has, it keeps Claude Code's own settings (yours and the repository's), its hooks directory, its installed plugins and the repository's .git/hooks read-only to Claude Code's file tools. Like every pack, it also keeps your shell startup files, ~/.gitconfig and your per-user login services (~/Library/LaunchAgents, ~/.config/systemd/user) read-only, so once you enforce it a file-tool write to ~/.zshrc is refused. Watch a week of its decisions before you enforce it, as the guide below shows.

agentgarm policy init claude-code
ls /etc/agentgarm/agents.d                               # Linux
ls "/Library/Application Support/AgentGarm/agents.d"     # macOS
sudo agentgarm policy init claude-code --dir /etc/agentgarm/agents.d --force
sudo agentgarm policy init claude-code --dir "/Library/Application Support/AgentGarm/agents.d" --force
schema: agentgarm.com/schemas/agents/v1
name: claude-code
version: "1.1.0"
mode: audit

See also

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.

2. Put AgentGarm's hooks in Claude Code's managed settings

On a root install, sudo agentgarmd hooks install claude-code writes the drop-in managed-settings.d/50-agentgarm.json in Claude Code's system directory (/Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux). Claude Code merges it with your organisation's own managed settings, so the hooks join yours. Each blocking event gets one hook with a 10-second timeout.

What a hook does when it gets no decision, because agentgarmd is unreachable or too slow, follows the pack's top-level on_internal_error. The shipped packs say fail_open_alert, so the drop-in has onFailure: "continue" and such a call goes through with a note rather than being denied. To deny it instead, set on_internal_error: fail_closed in the pack and run hooks install again: it then writes onFailure: "block", which needs Claude Code 2.1.295 or later (an older version lets the call through when a hook fails). With neither the pack nor default.yaml readable, the hooks install fail closed. hooks status says installed while the drop-in is what the last install wrote; to see which mode that was, look for onFailure in the drop-in.

An MDM profile or registry policy for Claude Code outranks the drop-in, which is then ignored unless that source sets managedSourcesBehavior: "merge". hooks status says not in force when it finds one, and agentgarmd alerts if one appears later. A no-root install writes no managed hooks, so there Claude Code is governed through the launcher alone.

sudo agentgarmd hooks install claude-code
sudo agentgarmd hooks status claude-code

3. Start Claude Code through agentgarm run

agentgarm run -- claude picks the Claude Code pack from the command name, registers a task, checkpoints the workspace, builds the sandbox from the pack and proves it with the canary, printing agentgarm: sandbox applied; any failure refuses the launch. It points Claude Code at the proxy with ANTHROPIC_BASE_URL, so each model call is counted and priced against the task.

Sign in with an API key: export ANTHROPIC_API_KEY before you launch, and the sandbox passes it on (unless your pack brokers credentials, which strips it). Claude Code asks whether to use the key, with No selected: choose Yes (macOS keeps the answer; on Linux it asks at every launch). If it still reports Not logged in, add --settings '{"apiKeyHelper":"printenv ANTHROPIC_API_KEY"}' after claude. A claude.ai subscription login is never routed through the proxy, and inside the sandbox Claude Code cannot read it, so it reports Not logged in and makes no model call. In an organisation, give each developer a gateway key instead.

Claude Code sends usage metrics to Anthropic and third-party logging, which appear as allowed egress decisions. Set DISABLE_TELEMETRY=1 before you launch to stop them; it also turns off feature flags, so Remote Control may be unavailable.

agentgarm run -- claude

Checked by the walk: this command ran as written on a no-root Linux install, and the output showed agentgarm: sandbox applied.

See also

Give Claude Code a per-developer gateway key

Give each developer their own gateway key from Central Lite and let Claude Code fetch it through apiKeyHelper; a claude.ai login is never routed.

4. Know what a deny and an ask do

A deny blocks the tool call before it runs, with the rule's reason shown to Claude Code. An ask hands the call to Claude Code's own permission prompt, and AgentGarm not objecting is never an approval: Claude Code's own prompts stay in force. For an approval that the agent cannot answer for you, enrol a presence key and approve with Touch ID. Prompt text is never sent to agentgarmd.

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.

5. Check the session and its level

While Claude Code runs, agentgarm status shows its task with an assurance level and the layer that enforces each class the policy uses. Claude Code's managed hooks rate B at best: only while the drop-in is exactly as rendered, no higher managed source hides it, and once a live run is recorded on the coverage page; until then they rate C. The sandbox's file boundaries hold whatever the hooks do. MCP servers that Claude Code or its host app loads by itself (in-process servers, claude.ai connectors) load beside the policy's.

agentgarm status

Checked by the walk: this command ran as written on a no-root Linux install.

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.