Skip to the content

Govern agents on a headless server or container

Check what a server or container offers, set a policy to the headless profile so every ask is denied instead of waiting, and test it before you install it.

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

Check what a server or container offers AgentGarm and which profile fits it, set a policy to the headless profile so every ask is denied instead of waiting for someone who is not there, test that before you install it, and, on a node enrolled in Central Lite, send the asks you choose to a remote approver's passkey.

1. Check what the host offers

agentgarmd self-check reports what the host offers each enforcement layer (the sandbox, cgroup v2, the active security modules, key custody), and each gap with what it costs in assurance, on a line starting ->. It is read-only and creates nothing. Its environment: line names the container runtime and CI provider it detects, whether the session is headless (on Linux, no DISPLAY or WAYLAND_DISPLAY), and the recommended profile: ephemeral in CI, else container in a container, else headless in a headless session, else interactive.

It describes the process that runs it, so run it from the session that will run the agents, with --user on a no-root install. agentgarmd also runs it at start and records it, and agentgarm status shows the count of gaps on its self-check line.

agentgarmd self-check --user
agentgarmd self-check --user --json
agentgarmd self-check

Checked by the walk: these commands ran as written on a no-root Linux install and a root install on Linux.

2. Read the detected topology

preview

The same environment: line also names the session's topology. The recommended profile follows it too: container in a dev container, Codespaces or Coder, and headless in an SSH session.

3. Set the policy to the headless profile

profile is a setting of each policy file: interactive (the default), headless, ephemeral or container. agentgarmd never changes it from the self-check, so set it in the policy for each agent that runs unattended. Under headless every ask rule's verdict becomes deny, with no prompt and no local Touch ID or security key. The policy evaluator does this, so it holds on root and no-root installs alike. The example's terraform-apply rule is marked approval: remote: on a machine that is not enrolled in Central Lite it is denied like any other ask, and the last step covers sending it to a remote approver.

container, like interactive, keeps the ask: it goes to presence or the agent's own prompt, so use headless where nobody will answer one. For CI jobs, agentgarmd has its own ephemeral profile; CI and dev containers covers it.

schema: agentgarm.com/schemas/agents/v1
name: claude-code
mode: enforce
profile: headless
security_boundaries:
  execution:
    rules:
      - id: privilege-escalation
        ask: { exec: [sudo, sudoedit, su, doas, pkexec, run0] }
      - id: terraform-apply
        ask: { exec: [terraform], args_match: "apply*", approval: remote }

4. Test the change before you install it

Make a copy of the policy with profile: headless and mode: enforce: the pack ships in audit mode, which denies nothing, so the profile alone changes no outcome (see Switch to enforce). Then replay what it must decide with agentgarm policy test. A command the pack would ask about now shows -> deny, and with -v its reason ends in (ask denied: headless profile). policy test shows the enforce verdict even for an audit-mode file, so check the mode yourself. agentgarm policy lint reports headless_ask, information that the profile turns every ask rule into a deny.

sed -e 's/^profile: interactive$/profile: headless/' -e 's/^mode: audit$/mode: enforce/' ~/.config/agentgarm/agents.d/claude-code.yaml > claude-code-headless.yaml
echo '{"exec": "rm -rf ~/projects", "cwd": "/work", "expect": "deny"}' > headless-tests.jsonl
echo '{"exec": "git status", "cwd": "/work", "expect": "allow"}' >> headless-tests.jsonl
agentgarm policy test claude-code-headless.yaml --against headless-tests.jsonl -v
agentgarm policy lint claude-code-headless.yaml

Checked by the walk: these commands ran as written on a no-root Linux install, and the output showed (ask denied: headless profile).

See also

Test a policy before you ship it

Write what a policy must allow, ask about and deny as a file of events, replay it before you install the policy, and keep both in your repository.

5. Put the copy in force

agentgarmd picks a policy by its file name, not its name:, so the copy must replace the agent's own file, claude-code.yaml: under another name it governs an agent of that name, not Claude Code. agentgarmd keeps enforcing the file it loaded until it restarts, so restart it (other installs as in the first guide). agentgarm status then lists the file with its new content hash.

cp claude-code-headless.yaml ~/.config/agentgarm/agents.d/claude-code.yaml
systemctl --user restart agentgarmd
agentgarm status

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

6. Send chosen asks to a remote approver

preview

An ask rule marked approval: remote, like terraform-apply above, is not simply denied under headless when the node is a root install enrolled in your Central Lite and its org root metadata lists an approver set. agentgarmd sends the request through Central Lite, an approver approves it with their passkey on the console's approvals page within 10 minutes, and agentgarmd verifies the approver's signature itself. The call stays denied meanwhile; once approved, the agent's next try of exactly that call is allowed, once. The node reads the approver set afresh for every request, answer and retry, so a new approver set, a revoked approver or certificate, or agentgarm node leave applies at once, voiding an approval not yet used.

Anything that fails keeps the call denied: a node that is not enrolled, no approver set, Central Lite unreachable, a refused answer, an expiry. Approvals rate B under an org root of at least two keys whose custody the org declares offline, and C under Central Lite's own single software root key, since whoever controls Central Lite's host could list an approver of their own. Under an interactive policy, approval: remote is an ordinary ask.

An enrolled server also takes fleet kill orders. With nobody at its keyboard, nobody reads its agentgarm status: a suspended task just stops, and under a lockdown a scheduled agentgarm run fails with the order's reason in its log. Follow the server from Central Lite instead, with each node's answer to the order (Stop agents across a fleet), and from its SIEM export.

sudo agentgarm node enrol     # reads the one-time enrolment token from stdin
garm-central root lite --approvers approvers.json
garm-central approver list