Guide 14 of 61 · Writing policy
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.
Steps marked preview rely on a package that has not passed its release gate.
Decide which files an agent may read and write and which hosts its tools may reach, know which layer holds each rule on macOS and on Linux, check that the sandbox was proved at launch, and recognise a denial when the agent meets one.
1. Launch the agent in the sandbox
agentgarm run builds a sandbox from the agent's policy (Seatbelt on macOS, Landlock and seccomp on Linux) and applies it in audit and enforce mode alike, printing agentgarm: sandbox applied and the backend it used before the agent starts. With no rule of yours, the agent can write only the workspace (the directory you launch from, which may not be your home directory or /), temporary directories and its own state (~/.claude and ~/.claude.json for Claude Code). It can neither read nor write credential paths such as ~/.ssh, ~/.aws, ~/.gnupg, ~/.kube and ~/.netrc, nor AgentGarm's own files, and on macOS it cannot change configuration that runs commands outside the sandbox, such as ~/.claude/settings.json and .git/hooks. A policy adds to these lists; it cannot remove from them.
agentgarm run -- claudeChecked by the walk: this command ran as written on a no-root Linux install, and the output showed agentgarm: sandbox applied.
2. Deny reads and protect files
In security_boundaries.filesystem, a deny path is neither read nor written, and a read_only path is read but never written; ~ is your home directory, ${WORKSPACE} the task's workspace, and a glob such as **/.env covers every match. Both lists hold at two layers: the hook, for the agent's file tools (Claude Code's Read, Write and Edit, and Grep, Glob and LS, which are denied when a deny entry lies beneath the directory they search), and the sandbox, for everything the agent runs. On Linux, Landlock can express neither a glob nor a write-only deny inside a writable directory, so there a workspace .env and a read_only path such as ~/.claude/settings.json are held by the hooks alone.
filesystem:
# Reads of credentials are denied; .env.example and other templates stay readable.
deny:
- "~/.ssh"
- "~/.aws"
- "~/.gnupg"
- "~/.config/gcloud"
- "~/.azure"
- "~/.kube/config"
- "~/.netrc"
- "~/.git-credentials"
- "~/.docker/config.json"
- "~/.config/gh/hosts.yml"
- "**/.env"
- "**/.env.local"
- "**/.env.*.local"
# Configuration that runs commands outside any sandbox: file tools may not change it.
read_only:
- "~/.claude/settings.json"
- "~/.claude/settings.local.json"
- "~/.claude/hooks"
- "~/.claude/plugins" # installed plugins carry hooks and MCP servers
- "${WORKSPACE}/.claude/settings.json"
- "${WORKSPACE}/.claude/settings.local.json"
- "${WORKSPACE}/.git/hooks"
# User persistence: shell startup files, git's global configuration and per-user login
# services. File tools are refused here; for agents launched through `agentgarm run` each is
# also a sandbox write deny, and where an OS file sentinel runs it refuses any process's write.
- "~/.bashrc"
- "~/.zshrc"
- "~/.profile"
- "~/.bash_profile"
- "~/.zprofile"
- "~/.gitconfig"
- "~/Library/LaunchAgents"
- "~/.config/systemd/user"
on_internal_error: fail_closed
checkpoint: per_task3. Name the only paths it may write
read_write lists the paths that may be written. File tools are then denied a write anywhere else, temporary files included, and under agentgarm run the list replaces the workspace among the sandbox's write roots, so list ${WORKSPACE} if the agent should still write there. The launcher refuses an entry that is /, your home directory or a directory above it, or one that holds or lies inside AgentGarm's own files. A read_only entry inside a read_write entry still wins, at the hook and in the macOS sandbox, so the agent can write the workspace but not its .github/workflows. The packs leave read_write out on purpose: the sandbox already confines writes, and the list turns every other write into a deny at the hook.
filesystem:
# File tools may write only here, and under `agentgarm run` these replace the workspace
# among the sandbox's write roots (temporary directories and the agent's own state stay).
read_write:
- "${WORKSPACE}"
- "~/agent-scratch"
# Read but never written, even inside a read_write entry.
read_only:
- "${WORKSPACE}/.github/workflows"
# Neither read nor written.
deny:
- "~/.ssh"
- "${WORKSPACE}/secrets"
- "**/*.pem"
on_internal_error: fail_closed4. Keep the network behind the proxy
Inside the sandbox the agent's one TCP destination is agentgarm-session's proxy on loopback, and on macOS it cannot even resolve a name, so a direct connection fails. The proxy forwards model calls on its inspected routes and carries other HTTPS (package registries, git, web fetches) as CONNECT tunnels. It refuses a tunnel to a loopback, link-local (cloud metadata), private or CGNAT address, to a model provider's API host, which must take its inspected route (raising DIRECT_PROVIDER_EGRESS), and to a subscription back end such as claude.ai. On Linux, Landlock limits connections by port only, and only from Linux 6.7, so an agent there can reach another host on the proxy's port directly, and Linux egress is rated C.
5. List the hosts its tools may reach
network.allowed_endpoints lists the host names, or host:port pairs, the agent may connect to: a host alone matches on any port, host:port on that port only, and a subdomain needs its own entry (github.com does not cover api.github.com). agentgarmd checks against it each connection an agent's tool reports to its hook, such as the URL of Claude Code's WebFetch, and every tunnel through the proxy: agentgarm-session has it decide each CONNECT against the policy of the task whose process opened it, so a command such as curl or git is refused a host the list leaves out, after the refusals of the step above. Model calls take the proxy's inspected routes, not tunnels, so the list need not name your provider. If agentgarmd cannot answer, the tunnel goes ahead and the session logs it. On Linux, the list holds only for what goes through the proxy. The packs ship without a list, which would cost false denies before it bought anything.
network:
allowed_endpoints:
- "api.anthropic.com"
- "github.com"
- "docs.rs:443"
- "webhook.site"6. Read what it sends to the sites you list
previewallowed_endpoints decides which hosts a tool may reach; network.inspect, beside it, lists the reachable ones whose requests agentgarm-session should also read for secrets, such as paste sites and webhooks. A tunnel is decided against the list first, and only then, for a listed site, opened and read: a site allowed_endpoints leaves out is never reached, so it is never inspected, and agentgarmd warns about such an entry when it loads the policy. Inspection reads the request's path, query and body in memory, never the response, and in Block mode stops a request that carries a secret. It applies only to agents started with agentgarm run, and on Linux it is rated C, as egress is.
# Of the hosts above, read what is sent to this one for secrets (the outbound-inspection
# guide). A listed host the list above leaves out is never reached, so never inspected.
inspect:
hosts: [webhook.site]
mode: auditSee also
Check what agents upload to paste sites and webhooksHave AgentGarm read what launched agents send to paste sites, file sharing and webhooks, record or stop secrets, and fix tools that refuse its certificate.
7. Let the canary prove the sandbox
Every agentgarm run first starts a canary inside the very sandbox it built, which must be refused a read of a denied file, a write into a denied directory and, where the kernel limits TCP, a connection to a loopback port the launcher listens on. Only the operating system's refusal counts, and a probe that gets through refuses the launch. The canary then checks containment: that the agent cannot signal the launcher, reach SSH on loopback or use agentgarm-session's console, and on Linux that no ssh-agent, gpg-agent, D-Bus or display socket is reachable. A failed containment check does not stop the launch: the launcher prints it and the task is demoted to C (so a Linux desktop session with those sockets is C), which agentgarm status shows beside the task. agentgarm doctor checks the sandbox backend (Seatbelt, or Landlock among the active security modules), but the canary decides at every launch.
agentgarm statusagentgarm doctorChecked by the walk: these commands ran as written on a no-root Linux install.
See 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.
8. Recognise a denial
In enforce mode, a file tool or fetch the hook refuses gets a short reason, never the rule: Claude Code sees “AgentGarm: file access denied by policy”, “AgentGarm: file is read-only by policy”, “AgentGarm: write outside the allowed paths” or “AgentGarm: endpoint not allowed by policy”. The sandbox refuses in either mode, as the operating system: a read or write fails with “Operation not permitted” on macOS, and with “Permission denied” or “Operation not permitted” on Linux, and a refused tunnel gets HTTP 403 from the proxy (a tunnel to a host outside allowed_endpoints only in enforce mode). The dashboard's “Denied or asked” shows the rule id and the full reason of each hook denial.
agentgarm ui --open