Guide 5 of 61 · Getting started
Govern an agent with no hooks
Run an agent AgentGarm has no hook adapter for inside the same sandbox and proxy, and know which of your policy's rules that leaves unenforced.
Run an agent AgentGarm has no hook adapter for inside the same sandbox and proxy as any other, know exactly which of your policy's rules that leaves unenforced, and know when an adapter would add them.
1. Check whether your agent has an adapter
An agent with a hook adapter is started with agentgarm run, and its hooks decide each command and tool call; the agents with one are on the coverage page, and agentgarm agents lists the ones installed here, with their versions. Some agents have no hook API at all, such as Aider, Continue, Zed and Roo Code. For those, and for any agent without an adapter, agentgarm wrap applies everything that needs no hooks.
agentgarm agentsSee also
Govern Codex CLIInstall the Codex pack, add its hooks to Codex's managed requirements.toml on a root install, start Codex through the launcher, and check what is enforced.
2. Give the wrapped agent a policy
agentgarm wrap uses the policy named custom (--agent names another), reading custom.yaml from your policy directory and, when there is none, default.yaml. agentgarm install --user writes the default pack when there is none, and sudo agentgarmd install writes every default pack, this one among them, when the system's policy directory holds none; otherwise agentgarm policy init default writes it, in mode: audit (on a root install, with --dir and --force, it puts back the shipped pack). Its file rules go into the sandbox: reads of the credential paths below are denied, and writes to the workspace's .git/hooks, your shell startup files, ~/.gitconfig and your per-user login services. On Linux, Landlock cannot express the .env globs or a write deny inside the workspace, so there a workspace .env stays readable and .git/hooks writable.
agentgarm policy init defaultls /etc/agentgarm/agents.d # Linux
ls "/Library/Application Support/AgentGarm/agents.d" # macOSsudo agentgarm policy init default --dir /etc/agentgarm/agents.d --force 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:
- "${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"Checked by the walk: these commands ran as written on a no-root Linux install and a root install on Linux.
See 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.
3. Start the agent with agentgarm wrap
Run it from your project directory: the workspace becomes writable, so the home directory, / and their ancestors are refused, and a launch from inside another governed task is refused too. agentgarm wrap does what agentgarm run does: it registers a task, checkpoints the workspace, builds the sandbox, proves it with the canary, routes the agent through the proxy and then becomes the agent; any failure refuses the launch. Try it first with a command that exits at once.
agentgarm wrap -- lsagentgarm wrap -- aiderChecked by the walk: this command ran as written on a no-root Linux install.
4. Read what it says is not enforced
Before the agent starts, agentgarm wrap prints on stderr that “this agent runs without agent hooks”, then what still applies on this platform. On macOS: the sandbox (file access, executables, network only through the proxy), task registration, budgets on proxied model calls and the checkpoint; macOS applies no resource limits to a task. On Linux: the sandbox (file access and executables; outbound TCP only to the proxy's port from Linux 6.7, by port and not by address, and no UDP), task registration and the checkpoint; resource limits only where agentgarmd has a delegated cgroup v2 subtree (the cgroups line of agentgarmd self-check says), and network egress and budgets on model calls are observed only, since the agent can reach the network around the proxy, so both rate C. Not enforced on any platform: argv command rules, per-tool and MCP decisions, and approvals, which need hooks.
So the default pack's command rules and asks do not stop the commands a wrapped agent runs, and a session whose policy has them rates C (observed): a session is rated by the weakest class its policy uses. A policy built only on file rules lets a wrapped session that passes its sandbox checks rate B (controlled); on a no-root install, B covers that session only.
5. Know what the sandbox and proxy still do
Whatever the policy says, the sandbox denies the credential paths (~/.ssh, ~/.aws, ~/.gnupg, ~/.git-credentials and more) and AgentGarm's own state, and the agent can write only into the workspace and temporary directories. The launcher removes ambient credentials from the environment, and keeps the provider API keys unless the policy strips them. A policy strips them when it sets strip_ambient: true, or when it brokers credentials and does not set strip_ambient: false. The launcher also points the agent at the proxy (ANTHROPIC_BASE_URL, OPENAI_BASE_URL, HTTPS_PROXY), and the proxy counts a model call that names no task against the task of the process that made it. On macOS the sandbox lets TCP reach only the proxy, so a call that ignores these variables fails rather than going unseen; on Linux that rule is best effort, and network and model-call rules rate C.
See also
Give agents short-lived AWS, GCP and SSH credentialsSeal AWS, GCP and SSH credentials in agentgarmd; each task started with agentgarm run gets short-lived ones, and the sealed ones never reach the agent.
6. Ask for an adapter when you need more
Command rules, per-tool and MCP decisions and approvals need the agent's hooks, which only an adapter reads. Adapters are data files describing an agent's hook payloads, so an agent with a hook API can get one without new code; an agent with no hook API cannot, and agentgarm wrap is the most AgentGarm can do for it. To ask for one, write to support@nannertech.com with the agent's name and version.