Reference
Lookup tables for the DefenseClaw CLI, the sidecar API, configuration files, credentials, fail modes, and environment variables.
Lookup pages for after you know what you are doing. defenseclaw <command> --help is the authority for any flag.
CLI commands
The defenseclaw and defenseclaw-gateway commands, grouped by what you're trying to do.
Setup commands
Every setup surface in one place, with its interactive and scripted forms.
Sandbox CLI
Every defenseclaw sandbox command and flag for NVIDIA OpenShell sandboxes, with an example each.
Gateway API
The HTTP surface defenseclaw-gateway exposes. Used by connectors, hooks, and the CLI.
Configuration: one source of truth
What lives in config.yaml, what is derived, what is evidence and what is runtime state; the single writer; the rules on managed hosts.
Configuration
config.yaml schema, the on-disk layout, and per-connector source-of-truth files.
Keys
The credentials registry, where keys live, and the order DefenseClaw resolves them in.
Fail modes
What a connector does when the gateway is unreachable or answers badly, and how to set it.
Migrate config.yaml to version 9
What the config_version 8 to 9 migration moves, the commands that run it and how to go back to 0.8.x.
Environment variables
Every environment variable DefenseClaw reads, with defaults and accepted values.
To build a non-interactive defenseclaw setup guardrail command, use the
command generator.
For coding agents
These pages are runbooks written to an AI agent. Pick the task, copy its prompt into your agent, and the agent reads the runbook page and does the work. Every runbook tells the agent to look first, change nothing without your yes, and report back in a fixed format.
Pick a task
| Task | Prompt to paste | Runbook |
|---|---|---|
| Install and set up in observe mode | Read https://cisco-ai-defense.github.io/defenseclaw/docs/get-started/quickstart/llms.md and follow it. | Set up DefenseClaw |
| Find out why something is broken | Read https://cisco-ai-defense.github.io/defenseclaw/docs/reference/llms.md, open the "Troubleshoot DefenseClaw" runbook and follow it. | Troubleshoot |
| Run an agent in a sandbox | Read https://cisco-ai-defense.github.io/defenseclaw/docs/sandboxes/guide/llms.md and follow it. | Sandbox an agent |
| Turn a sentence into a rule | Read https://cisco-ai-defense.github.io/defenseclaw/docs/policies/recipes/llms.md and follow it. | Write a rule |
| Deploy to a fleet as an administrator | Read https://cisco-ai-defense.github.io/defenseclaw/docs/enterprise/operations/llms.md and follow it. | Enterprise admin |
Machine-readable docs
https://cisco-ai-defense.github.io/defenseclaw/llms.txtlists every page with its Markdown URL.https://cisco-ai-defense.github.io/defenseclaw/llms-full.txtis the whole documentation in one file.- Add
llms.mdto any page URL for that page as Markdown, for example.../docs/get-started/install/llms.md.
Rules every runbook enforces
- Observe first. The agent does not switch to action mode, change a fail mode, disable a connector, unblock a site or edit
config.yamlby hand without your yes to that exact change. - The agent never prints a key or token.
- On a managed computer the agent stops. A command that prints
This computer is managedorThis device is managed(exit2or3), or"deployment_mode": "managed_enterprise"indefenseclaw status --json, means your administrator owns DefenseClaw there (Managed command availability). - The agent reports in a fixed format: what it ran, what it saw, what it changed, what is left for you.
Hand this page to your agent
Paste this into your agent:
Read https://cisco-ai-defense.github.io/defenseclaw/docs/reference/llms.md, then ask me which task I want and open that runbook.Troubleshoot DefenseClaw
Hand this page to your agent
Paste this into your agent:
Read https://cisco-ai-defense.github.io/defenseclaw/docs/reference/llms.md, open the "Troubleshoot DefenseClaw" runbook and follow it. Collect first, ask me before any fix that changes something.You are an AI agent. Find out why DefenseClaw is not working, map each failure to a known fix, apply only the safe ones the user approves, and report.
Hard rules
- Observe first. Do not switch to action mode, change a fail mode, disable a connector, unblock a site or edit
config.yamlby hand without the user's yes to that exact change. - Never print a key, token,
.env,hooks/ordevice.key. Redact them from anything you quote. - Stop on a managed computer: a command that prints
This computer is managedorThis device is managed(exit2or3), or"deployment_mode": "managed_enterprise"indefenseclaw status --json, means the administrator owns DefenseClaw (Managed command availability). Tell the user to contact them. - Do not open
audit.dbor attach it to a report.
Steps
-
Collect health. Read-only.
defenseclaw doctor --jsonExpected: JSON with
"outcome","exit_code","passed","failed","warned","skipped"and acheckslist. Each check hascheck_id,status(pass,warn,fail,skip),label,detailandremediation. If the command is not found, DefenseClaw is not installed or~/.local/binis not onPATH; see Set up DefenseClaw. -
Collect state. Read-only.
defenseclaw status --json defenseclaw-gateway statusExpected:
sidecar.runningistrue; each connector shows itsmodeandfail_mode.effective. Ifconfig_errorsis present, rundefenseclaw config validateand quote the field it names. -
Read the last gateway log lines, locally, and quote only the error lines.
tail -n 40 ~/.defenseclaw/gateway.logExpected: start lines and no repeated errors. If it differs: redact secrets before quoting. Never paste the whole file.
-
Map each
failandwarncheck by its label or message. The table below has the common ones; for any other row, run theNext step:line doctor prints under it (Read the rows). Installer and upgrade errors are on Troubleshooting. Common ones:Check says Safe fix (ask first) Needs the user's decision gateway not running defenseclaw-gateway startNone stale generated script, hooks not found defenseclaw setup <connector> --yesand restart the agentNone no gateway token configured defenseclaw doctor --fix --dry-run, then--fix --yesRotating tokens config.yamlinvalidnone: show the field it names The edit itself nothing is blocked defenseclaw guardrail statusSwitching to action mode tools blocked while gateway down start the gateway Changing the fail mode "DefenseClaw is not checking this session" start the gateway ( defenseclaw-gateway start), thendefenseclaw doctorif it does not startSwitching the policy doctor.coworkwarns, orstatus --jsonhascowork.protected: falseRun the command in cowork.stepwhen it is adefenseclawcommand (for exampledefenseclaw setup cowork). See Claude Cowork for eachreason_codeUploading the plugin zip in Claude Desktop, or removing the plugin there: only the user can -
Preview repairs. Never skip this.
defenseclaw doctor --fix --dry-runExpected: a list of the repairs that would run, with their risk. Nothing changes. If a repair is
disruptive(it restarts the gateway), say so before asking. -
Apply only what the user approved, one repair at a time, then re-check.
defenseclaw doctor --fix --yes --fix-id <REPAIR_ID> defenseclaw doctor --jsonExpected: the repair is
appliedand the check now has"status": "pass". If it differs: stop, do not try another repair, and report both outputs.
Report
Reply with:
- Symptom the user gave, and the OS.
- Failing checks: label, detail and the Troubleshooting entry you matched.
- Fixes applied (command, result) and fixes you proposed but did not apply.
- Decisions that belong to the user.
- Whether
doctor --jsonnow exits0.
Troubleshooting
Fix a standalone DefenseClaw enterprise deployment by lifecycle error code, MDM wrapper code, hook refusal code, or symptom, on Windows, Linux, and macOS.
CLI commands
The defenseclaw and defenseclaw-gateway commands, grouped by what you are trying to do — first run, doctor, setup, guardrail, policy, configuration (config set, get, migrate), asset block and allow lists, scanning, audit, gateway control, upgrade, uninstall.