Quickstart
Block your first risky tool call in 5 minutes. Install DefenseClaw, run init, turn on blocking for one agent and watch a test command get blocked.
Install DefenseClaw, guard one agent and watch a test command get blocked, in about five minutes. This uses Claude Code. For another agent, replace claudecode with its connector name (codex, copilot, cursor, devin, antigravity, kiro, opencode, amp or hermes). The support matrix shows which agents can block on your OS.
The block comes from a one-rule test pack that matches only echo defenseclaw-demo-marker. Agents refuse the destructive commands the default rules target, so a harmless marker is the reliable way to see a block.
Block a tool call in six steps
Install
curl -LsSf https://github.com/cisco-ai-defense/defenseclaw/releases/latest/download/install.sh | bashirm https://github.com/cisco-ai-defense/defenseclaw/releases/latest/download/install.ps1 | iexOpen a new terminal afterwards if the installer asks you to.
The installer asks which agent to guard: type claudecode. Requirements and options are on Install.
Run defenseclaw init
defenseclaw init --connector claudecodeOn an install that already guards other agents, init --connector claudecode keeps only Claude Code. To add an agent there, use defenseclaw setup <agent> instead.
Press Enter through the prompts. Claude Code starts in observe mode: DefenseClaw records policy findings without enforcing them. In the default policy its hook lets a call run with one warning while the gateway is not running; a running hook blocks every other failure it detects. At Select connector(s) for action enforcement, leave the box unchecked. init starts the gateway and prints a first-run report. This sample comes from defenseclaw quickstart --skip-gateway, which prints the same report, so its Sidecar row says not started where yours says started:
DefenseClaw First-Run
status=ready connector=claudecode profile=observe
--------------------------------------------------------
Setup
✓ Config created defaults
✓ Bootstrap ~/.defenseclaw
✓ Skill scanner ~/.local/bin/skill-scanner
✓ MCP scanner ~/.local/bin/mcp-scanner
✓ Guardrail claudecode, mode=observe, fail mode=open
- Sidecar not started (--skip-gateway)
Readiness
✓ Config file ~/.defenseclaw/config.yaml
✓ Audit database ~/.defenseclaw/audit.db
✓ Device key ~/.defenseclaw/device.key
✓ Skill scanner ~/.local/bin/skill-scanner
✓ MCP scanner ~/.local/bin/mcp-scanner
- Connector Claude Code settings not found yet - written when the gateway starts
✓ Agent installation claudecode is installed
- LLM API not configured
- Cisco AI Defense scanner_mode is local
✓ Gateway binary found on PATH
Next
defenseclaw-gateway start
defenseclaw doctor
defenseclaw keys list
Adding another agent later: defenseclaw setup <connector>
While the gateway is not running, hooks let calls run with a warning (strict policy blocks them: defenseclaw guardrail use-pack strict).
After a reboot, agent hooks start the gateway on their next call; after defenseclaw-gateway stop, run: defenseclaw-gateway start
Running coding agents in OpenShell sandboxes: defenseclaw sandbox setup✓ is done and - is optional or skipped. You need no LLM key for this guide. If the report says partial, it names what needs attention; defenseclaw doctor explains the rest. Options are in the init reference.
Quit and reopen Claude Code so it loads the hooks, ask it to list the files in the directory, then run defenseclaw status. The agent, its mode and the new events appear within a second or two.
Turn on blocking for Claude Code
defenseclaw guardrail mode action --connector claudecodeThis switches only Claude Code to action mode, which enforces the rules. The running gateway applies it without a restart. The mode does not change what an outage does: in the default policy a tool call runs with a warning while the gateway is not running, and defenseclaw guardrail use-pack strict blocks it. A mode you saved with defenseclaw guardrail fail-mode wins over the policy: with a saved open the call still runs under strict, and defenseclaw guardrail fail-mode closed (add --connector <name> when the mode was saved for one agent) blocks it. Two cases stay closed even with a saved open: OpenClaw under the strict policy, and ZeptoClaw model requests (fail modes).
Add the demo rule
Copy the default rule pack, add one CRITICAL rule that matches only defenseclaw-demo-marker, and point Claude Code at the copy:
PACK=~/.defenseclaw/policies/guardrail/first-guardrail
cp -R ~/.defenseclaw/policies/guardrail/default "$PACK"
cat > "$PACK/rules/first-guardrail.yaml" <<'EOF'
version: 1
category: first-guardrail
rules:
- id: DEMO-MARKER-BLOCK
tool_call_only: true
expression: >-
f.commands.exists(c, 'defenseclaw-demo-marker' in c.argv)
pattern: '\bdefenseclaw-demo-marker\b'
title: "First-guardrail demo marker"
severity: CRITICAL
confidence: 0.99
tags: [demo]
EOF
defenseclaw guardrail validate-pack "$PACK"
defenseclaw guardrail use-pack first-guardrail --connector claudecode$Pack = "$HOME\.defenseclaw\policies\guardrail\first-guardrail"
Copy-Item -Recurse "$HOME\.defenseclaw\policies\guardrail\default" $Pack
Set-Content -Path "$Pack\rules\first-guardrail.yaml" -Encoding ascii -Value @'
version: 1
category: first-guardrail
rules:
- id: DEMO-MARKER-BLOCK
tool_call_only: true
expression: >-
f.commands.exists(c, 'defenseclaw-demo-marker' in c.argv)
pattern: '\bdefenseclaw-demo-marker\b'
title: "First-guardrail demo marker"
severity: CRITICAL
confidence: 0.99
tags: [demo]
'@
defenseclaw guardrail validate-pack $Pack
defenseclaw guardrail use-pack first-guardrail --connector claudecodeThe copy keeps every default rule. use-pack pins the pack's digest in guardrail.custom_packs.first-guardrail and switches Claude Code to it. Nothing restarts.
Ask the agent to run the marker
In Claude Code, ask:
Please run
echo defenseclaw-demo-marker.
The command does not run. Claude Code tells you DefenseClaw blocked it:
DefenseClaw policy blocked this action (rule DEMO-MARKER-BLOCK: First-guardrail demo marker). Do not retry it in another form.
In another terminal, list the latest alerts:
defenseclaw alerts --limit 5The block is the newest row. defenseclaw alerts --show 1 prints the whole record:
Alert #1
Severity: CRITICAL
Action: scan-finding
Target: claudecode:PreToolUse
Decision: blocked
Connector: claudecode
Rule: DEMO-MARKER-BLOCK: First-guardrail demo marker
Scanner: hook-rulesThe same alert is in the Alerts panel of defenseclaw tui (press 2).

Undo the demo
defenseclaw guardrail use-pack --clear --connector claudecode # back to the default pack
defenseclaw guardrail mode --clear --connector claudecode # back to observeDelete the first-guardrail folder under ~/.defenseclaw/policies/guardrail/. Skip the second command to keep enforcing the default rules.
Set up with an AI agent
Hand this section to your agent
Paste this into your agent:
Read https://cisco-ai-defense.github.io/defenseclaw/docs/get-started/quickstart/llms.md and follow the section "Set up with an AI agent". Ask me before any change it marks as needing my yes.You are an AI agent. Install DefenseClaw for the current user and set up the coding agents on this computer in observe mode. Run each step, compare with the expected output, and follow the "if it differs" branch.
Hard rules
- Observe first. Never switch an agent to action mode, change a fail mode, disable a connector or edit
config.yamlby hand without the user's yes to that exact change. - Never print a key, token or the contents of
.env. - Stop on a managed computer: if a command prints
This computer is managedorThis device is managed(exit2or3; see Managed command availability), ordefenseclaw status --jsonshows"deployment_mode": "managed_enterprise", tell the user to contact their administrator.
Steps
-
Check the OS and CPU.
uname -smExpected:
Darwin arm64,Linux x86_64orLinux aarch64. On Windows, use PowerShell and expect an x64 system. If it differs:Darwin x86_64is an Intel Mac. Stop and tell the user it is unsupported. Windows on ARM64 and x86 are also unsupported. -
Check whether DefenseClaw is already installed and whether the computer is managed.
defenseclaw status --jsonExpected on a clean computer:
command not found. Go to step 3. If it printsThis computer is managed: stop (rule 3). If it prints JSON: readdeployment_mode.managed_enterprisemeans stop (rule 3). Otherwise DefenseClaw is already installed; skip to step 4. -
Install. This is the official one-line installer; tell the user what you run.
curl -LsSf https://github.com/cisco-ai-defense/defenseclaw/releases/latest/download/install.sh | bash -s -- --connector noneOn Windows PowerShell:
& ([scriptblock]::Create((irm https://github.com/cisco-ai-defense/defenseclaw/releases/latest/download/install.ps1))) -Connector none--connector noneinstalls without picking an agent; step 4 sets up every agent it finds. Expected: the installer ends withNext: defenseclaw init. Open a new shell if it says~/.local/binis not onPATH, then rundefenseclaw --version(expectdefenseclaw, version X.Y.Z). If it fails, exit1means not installed (an upgrade puts the previous install back) and2an unknown option. Report the last lines of the output; do not retry in a loop. -
Set up the agents in observe mode.
defenseclaw init --non-interactive --yes --observe-allExpected: a first-run report like this one (a terminal shows
✓where a script seesOK):OK Configured connectors: claudecode, codex DefenseClaw First-Run status=ready connectors=2 profile=observe … OK Guardrail 2 connectors: claudecode=observe, codex=observe OK Sidecar …If
status=partialorneeds_attention: the report names the cause (for example an agent that is not installed). Continue to step 5 and include it in your report. For one agent only, usedefenseclaw quickstart --connector <name>. -
Check health.
defenseclaw doctor --jsonExpected:
"outcome": "healthy"(or"warning") and"exit_code": 0."outcome": "failed"comes with"exit_code": 1. If it differs: list each check with"status": "fail"and its"remediation". Do not apply--fixwithout the user's yes; you may showdefenseclaw doctor --fix --dry-run. -
Check the gateway and the agents.
defenseclaw status --jsonExpected:
sidecar.runningistrue, and each entry inconnectorshas"mode": "observe". If the sidecar is not running, ask the user before runningdefenseclaw-gateway start. -
Tell the user to restart each agent so it loads the hooks.
Report
Reply with:
- Installed: version, OS and CPU.
- Agents set up and their mode.
doctoroutcome and each failing check with its remediation.- What you did not do, and what needs the user's yes (for example action mode:
defenseclaw guardrail mode action --connector <name>).
Troubleshooting
If it did not block:
- The agent was open before
init: quit and reopen it. defenseclaw doctorshows a failing hook or gateway row: run theNext step:line it prints under that row (Read the rows).- Still in observe mode: run
defenseclaw guardrail status.
Next
Install
Install DefenseClaw on macOS, Linux, or Windows with one command, or build the current checkout from source.
First run: init and quickstart
The two first-run commands. defenseclaw init is the guided wizard and defenseclaw quickstart is the zero-prompt equivalent. Both run the same setup and print the same first-run report.