Troubleshooting
What you see when something goes wrong with AgentGarm, and the guide step that explains and fixes it, by symptom.
Installing and checking
| What you see | Where to go |
|---|---|
| agentgarm doctor reports a failed check | Check that protection is on: Run doctor |
| agentgarm status shows the proxy NOT answering | Check that protection is on: Check the services |
| agentgarm status says a policy is NOT LOADED | Watch your agent for a week, then enforce: Install the pack in audit mode |
| A session is rated C, or lower than you expected | Check that protection is on: Read each session's assurance level |
| A bypass alert appears | Check that protection is on: Act on a bypass alert |
| An agent's version is out of range or unknown | Keep agent versions in check: Bring the agent back into range |
| A download's signature or checksum does not verify | Check for and verify AgentGarm updates: Verify the download before you run it |
| agentgarm status says agentgarmd's binary was replaced on disk: restart agentgarmd | Check for and verify AgentGarm updates: Check that the new release is running |
Launching an agent
| What you see | Where to go |
|---|---|
| agentgarm run refuses to launch because of the project's agent configuration | Catch poisoned agent configs before launch: Let agentgarm run refuse a poisoned launch |
| The sandbox canary fails and the launch is refused | Limit what an agent can read, write and reach: Let the canary prove the sandbox |
| Claude Code says Not logged in under agentgarm run | Govern Claude Code: Start Claude Code through agentgarm run |
| Codex makes no model call, or cannot save a folder's trust, under agentgarm run | Govern Codex CLI: Start Codex through agentgarm run |
| A model call carrying a claude.ai or ChatGPT-plan login is refused with 403 | Give Claude Code a per-developer gateway key: Know why a subscription login is refused |
| A model call stops at the budget cap | Set spend budgets and stop runaway loops: Recognise the cap |
| A call is refused because the provider bills in another currency than the USD budget | Set spend budgets and stop runaway loops: Recognise the cap |
| An agent's WebSocket gets 426 Upgrade Required from the proxy | Govern Codex CLI: Start Codex through agentgarm run |
Decisions
| What you see | Where to go |
|---|---|
| A file read or write is denied | Limit what an agent can read, write and reach: Recognise a denial |
| A command is treated as opaque and asked about or denied | Allow, ask or deny shell commands: Know when a command is opaque |
| Enforcing would block everyday work | Watch your agent for a week, then enforce: Fix the rules that would get in the way |
| A secret is flagged that is not one | Keep secrets and card numbers out of prompts: Deal with a false positive |
| You need an exception to a rule | Trace what one agent task did: Ask for an exception to a rule |
Approvals
| What you see | Where to go |
|---|---|
| Every ask is denied after a fingerprint change | Approve risky actions with Touch ID: Re-enrol after a fingerprint change |
| No approval prompt appears | Approve risky actions with Touch ID: Keep the presence watcher running |
| A Mac with an enrolled key is lost, or its user leaves | Approve risky actions with Touch ID: Replace or retire a key when a Mac is lost or a person leaves |
Outbound inspection (preview)
| What you see | Where to go |
|---|---|
| A tool refuses AgentGarm's certificate, or a site shows Refused by tool | Check 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 agent | Check 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 unavailable | Check what agents upload to paste sites and webhooks: Turn it on |
Computer use (macOS)
| What you see | Where to go |
|---|---|
| agentgarm run refuses: the computer-use posture needs a live airbag | Govern computer-use agents: Install the airbag and grant it Accessibility |
| agentgarm doctor says the airbag lacks Accessibility | Govern computer-use agents: Install the airbag and grant it Accessibility |
| The airbag's Accessibility grant is lost after a rebuild or an update | Govern computer-use agents: Install the airbag and grant it Accessibility |
| agentgarm status shows a task SUSPENDED with an airbag hold | Govern computer-use agents: See why a task was suspended, and get it going again |
| An allowed tool's clicks or key presses are dropped | Govern computer-use agents: Read what would have been dropped, and open what you need |
| No agent shows a Screen Recording grant, or grants are unknown | Watch what agents can capture: See which agents hold a grant |
Sentinels, Windows, MCP tools and local runtimes (preview)
| What you see | Where to go |
|---|---|
| agentgarm status shows a macOS sentinel line as FAIL | Turn on the macOS sentinels: Check that the sentinels are connected |
| A security key stops approving on Windows | Approve 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 refused | Contain prompt injection in MCP tool output: Approve a new or changed tool |
| An MCP tool is held back for a poisoned description | Contain prompt injection in MCP tool output: See poisoned tool descriptions held back |
| agentgarm status --inventory lists a local runtime as UNMANAGED | See the AI runtimes and desktop AI apps on a machine: Read unmanaged and governed |
Fleet deployment (preview)
| What you see | Where to go |
|---|---|
| A force-installed browser extension never gets the machine's policy | Deploy AgentGarm with MDM: Force-install the browser extension |
Records and recovery
| What you see | Where to go |
|---|---|
| The audit chain does not verify | Export and verify the audit log: Read a broken chain |
| The dashboard refuses its launch code, or stops loading | Trace what one agent task did: Open the dashboard |
| An agent changed files you want back | Undo what an agent changed: Preview the rollback, then apply it |
| Support asks for details | Send a redacted support bundle: Write the bundle |
Central Lite (preview)
| What you see | Where to go |
|---|---|
| An admin lost their passkey | Stand up Central Lite: Recover an admin who lost their passkey |
| Central Lite cannot open its keys: a wrong PIN or another token | Keep Central Lite's keys in a hardware security module: Know what a wrong PIN or another token does |
Kill orders and evidence (preview)
Single sign-on, SCIM and SIEM (preview)
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.