Setup

DefenseClaw setup and configuration surfaces in one place — from the central guardrail wizard to keys, webhooks, registries, observability, sandboxing, and per-connector hooks.

defenseclaw setup is the main family of operator commands that takes DefenseClaw from "binary on disk" to "actively defending an agent". Mutating commands update only the configuration or owned integration surface they manage; restart, prompting, and audit behavior is command-specific. The top-level keys, registry, and experimental sandbox groups are included here because they are part of the same operator workflow.

The one-line summary

Run defenseclaw setup guardrail once. Reach for the auxiliary surfaces when you want to wire a chat notifier, registry, observability destination, custom LLM key, or the experimental Linux OpenShell sandbox 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 setup aliases

Each alias selects one connector and exposes a smaller connector-oriented option surface than setup guardrail. Pass --mode observe to run one 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. Use the central command when you need the complete guardrail flag surface.

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 amp

Adds or reconfigures Amp with --connector amp and writes the synchronous TypeScript policy plugin.

setup omnigent

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

Auxiliary configuration commands

These commands each own a focused slice of the configuration surface. Some are top-level command groups rather than setup subcommands; the matrix below shows which ones are interactive and which ones are designed for scripts.

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 local Splunk, Splunk Enterprise HEC, or Splunk Observability Cloud. V8 exports use the selected routes and redaction profile; review the unredacted fresh default.

setup local-observability

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

setup redaction

Guided v8 policy editor with a simple remove-all choice plus advanced global, bucket, profile, destination, and ordered-route settings.

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.

defenseclaw sandbox

Experimental Linux-only OpenClaw/OpenShell isolation. Review the current endpoint-wiring limitation and pass the sandbox-originated acceptance gate before treating it as enforcement.

Deployment and policy references

These pages explain operator policy and deployment architecture in more depth than the command cards above.

Enterprise hardening

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

Redaction profiles

Configure and inspect global, bucket, destination, and route-specific v8 redaction profiles.

Interactive vs non-interactive — global matrix

The operator-facing commands do not all share one interaction model. The table below is the canonical mapping for their interactive and scripted forms.

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 redaction`	yes (bare command)	subcommands + flags	Simple choices lead into Show advanced settings? for all 14 buckets, custom profiles, destinations, and ordered routes. Mutations support `--dry-run`, `--json`, `--yes`, and optional restart.
`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`.
`sandbox init` / `sandbox setup`	yes	`sandbox setup --non-interactive`	Experimental top-level Linux/OpenClaw group. `init` creates prerequisites and then runs setup; the current generated endpoint wiring must pass the documented acceptance gate.

Redaction is a v8 policy editor, not an on/off toggle

Run defenseclaw setup redaction for the guided workflow, or use subcommands such as status, remove-all, bucket, profile, destination, and route for automation. The command edits observability.destinations[].routes[].selector.buckets and observability.redaction_profiles and compiles the staged effective plan. A changed non-dry-run write creates a private timestamped backup and verifies the installed plan. remove-all selects profile none for configurable projections; it cannot weaken the release-owned managed enterprise destination.

For an independent operator cross-check, run defenseclaw config validate, defenseclaw config show --effective --section observability, and defenseclaw observability plan; use defenseclaw-gateway restart when your deployment requires an explicit activation restart.

The same workflow is available in TUI → Setup → Redaction Policy on macOS, Linux, and native Windows. The macOS app's Logs → Redaction policy… sheet exposes effective status, broad profile actions, and Show advanced settings for the full bucket/profile/destination/route command surface.

See it for yourself

The interactive flow for the central command is replayed end-to-end on the Setup guardrail page. Interactive auxiliary commands follow the same prompt-or-flag rhythm; use the matrix above for script-only commands.

What gets written where

Setup and auxiliary configuration commands can write these paths under ~/.defenseclaw/, depending on the feature being configured:

~/.defenseclaw/
  config.yaml          # canonical configuration (edited by commands that own config)
  .env                 # secret values — never committed, never logged
  audit.db             # SQLite audit store (configuration changes land here too)
  gateway.jsonl        # optional only when an explicit kind: jsonl destination uses this path
  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.