Skip to the content

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.

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.

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 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.

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.
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 <user> and <host>; 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.

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 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.

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.

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.

sudo agentgarm doctor --bundle agentgarm-support-upload.json --upload
garm-central support list
garm-central support get BUNDLE_ID --out node-bundle.json