Setup

Every defenseclaw setup verb in one place — from the central guardrail wizard to the auxiliary commands that wire keys, webhooks, registries, observability, and per-connector hooks.

defenseclaw setup is the family of operator commands that take DefenseClaw from "binary on disk" to "actively defending an agent". Every verb writes the same ~/.defenseclaw/config.yaml, restarts the right side-cars, and emits an audit-log entry — interactively when you are at a TTY, scripted when you pass --non-interactive.

The one-line summary

Run defenseclaw setup guardrail once. Reach for the auxiliary verbs only when you want to wire a chat notifier, a registry, an observability sink, or a custom LLM key into a guardrail that is already running.

The central command

defenseclaw setup guardrail

The wizard. Picks the connector, observe vs action mode, scanner backend, hook fail-mode, optional LLM judge, HITL severity, and rule pack — then restarts the gateway.

Connector aliases (thin wrappers around `setup guardrail`)

Each alias pre-fills setup guardrail --connector <name> and inherits every guardrail option. Pass --mode observe to run any of them in audit-only mode. On a host with another hook connector already active, the setup flow can add the new connector to the roster instead of replacing the old one.

setup openclaw

Selects OpenClaw with --connector openclaw and installs the fetch interceptor + before_tool_call plugin.

setup zeptoclaw

Selects ZeptoClaw with --connector zeptoclaw, redirects api_base, runs scan + response-scan.

setup claude-code

Adds or reconfigures Claude Code with --connector claudecode and installs its hooks.

setup codex

Adds or reconfigures Codex with --connector codex and installs hooks, OTel, and notify wiring.

setup cursor

Adds or reconfigures Cursor with --connector cursor and writes hooks.json plus MCP/skills/rules surfaces.

setup windsurf

Adds or reconfigures Windsurf with --connector windsurf for Cascade hooks plus local config discovery.

setup gemini-cli

Adds or reconfigures Gemini CLI with --connector geminicli and configures hooks plus native OTLP export.

setup copilot

Adds or reconfigures GitHub Copilot CLI with --connector copilot and writes hook config.

setup openhands

Adds or reconfigures OpenHands with --connector openhands and writes lifecycle hooks.

setup antigravity

Adds or reconfigures Antigravity with --connector antigravity and writes agy lifecycle hooks.

setup hermes

Adds or reconfigures Hermes with --connector hermes and wires config.yaml hooks.

setup opencode

Adds or reconfigures OpenCode with --connector opencode and writes the bridge plugin.

setup omnigent

Adds or reconfigures OmniGent with --connector omnigent and installs its custom Python policy bridge.

Auxiliary setup verbs

The non-guardrail verbs each own a focused slice of the configuration surface. Every one of them runs interactively at a TTY and supports --non-interactive for CI.

defenseclaw keys

Stash DEFENSECLAW_LLM_KEY (and any per-component overrides) in ~/.defenseclaw/.env. Top-level group: list, set, fill-missing, check. Not a setup subcommand.

setup webhook

Add Slack, PagerDuty, Webex, or generic HMAC notifiers for high-severity alerts. Test deliveries, list, enable/disable, remove.

defenseclaw registry

Subscribe to public or internal skill / MCP catalogs (clawhub, smithery, http_yaml, http_json, git, file). Sync, scan, promote into asset_policy.

setup splunk

Configure the audit-sink HEC forwarder. Replays past events on enable, redacts PII before send.

setup local-observability

Bring up the bundled OTLP collector + Grafana stack so you can see decisions live without leaving your laptop.

setup skill-scanner

Wire the cisco-ai-skill-scanner SDK into admission. Optional VirusTotal + LLM second-opinion.

setup mcp-scanner

Wire the cisco-ai-mcp-scanner SDK into admission. Behavioral introspection of MCP servers before they're added.

Enterprise hardening

Provision the managed OS service, guardian, trust boundaries, scoped credentials, and tamper-repair controls.

setup redaction

Toggle privacy.disable_redaction on/off and inspect status. The right way to manage the redaction kill-switch.

Interactive vs non-interactive — global matrix

Every verb in the setup family exposes both a fully-interactive walkthrough and a --non-interactive flag for CI. The table below is the canonical mapping.

Verb	Interactive	Non-interactive	Notes
`setup guardrail`	yes (default)	`--non-interactive` + flags	Wizard explains each prompt; non-interactive mode requires every required flag.
`setup <connector>`	yes	flags + `--yes`	Adds or reconfigures a connector; pass `--mode observe\|action` to choose enforcement mode.
`keys list` / `set` / `fill-missing` / `check`	yes (default)	`--value` + `--yes`	`keys set` prompts for the value (hidden) when `--value` is omitted.
`setup webhook add <type>`	yes (default)	`--non-interactive` + flags	URL and secret-env are prompt-or-flag; type is always positional.
`setup webhook test <name>`	n/a	n/a	Always non-interactive; safe to re-run.
`registry add <id>`	yes (default)	`--non-interactive` + flags	`wizard` is the friendly first-run alias.
`registry sync` / `entries` / `approve` / `reject`	n/a	flags only	Designed for cron / scripts.
`setup splunk`	yes	`--non-interactive` + flags	HEC token comes from `--hec-token <value>` or, if omitted, the `DEFENSECLAW_SPLUNK_HEC_TOKEN` env var.
`setup local-observability`	yes	flags + `--non-interactive`	One-shot bring-up; `--down` tears the stack back down.
`setup skill-scanner` / `setup mcp-scanner`	yes	`--non-interactive` + flags	Per-feature toggles; the underlying `cisco-ai-skill-scanner` / `cisco-ai-mcp-scanner` SDKs ship as hard dependencies of `defenseclaw`.
`setup redaction on` / `off` / `status`	n/a	flags only	Idempotent; status exits 0/1 for CI.

See it for yourself

The interactive flow for the central command is replayed end-to-end on the Setup guardrail page. Every other verb follows the same prompt-or-flag rhythm.

What gets written where

Every setup verb writes to ~/.defenseclaw/:

~/.defenseclaw/
  config.yaml          # the canonical configuration (every verb edits this)
  .env                 # secret values — never committed, never logged
  audit.db             # SQLite audit store (configuration changes land here too)
  gateway.jsonl        # rolling decision/event JSONL
  registries/<id>/     # cached manifest + scanner verdicts for each registry source

Next steps: defenseclaw setup guardrail is the right starting point if you have not run it yet. Already running? defenseclaw keys set DEFENSECLAW_LLM_KEY is the most common follow-up — it unlocks the LLM judge and the LLM-backed scanners. The full guided workflow lives at Unified LLM key.