Setup commands

DefenseClaw setup and configuration surfaces in one place — from the central guardrail wizard to keys, webhooks, registries, observability, legacy sandbox cleanup, 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 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, or custom LLM key into a guardrail that is already running.

The central command

defenseclaw setup guardrail

The wizard. Picks the connector, observe or action mode, hook fail mode, scanner backend, optional LLM judge and HITL severity, 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 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 devin

Adds or reconfigures native Devin CLI lifecycle hooks and documented local customization surfaces.

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.

setup kiro

Adds or reconfigures Kiro with --connector kiro and writes the lifecycle hooks shared by the Kiro IDE and CLI.

setup acp

Finds ACP agents that are not guarded yet and routes them through the DefenseClaw ACP guard.

Proxy connectors

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.

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, remove, fill-missing, check. Not a setup subcommand.

setup routing

Route OpenAI Chat Completions traffic between configured model backends with the managed vLLM Semantic Router sidecar. Proxy connectors only.

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, skills_sh, 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

Choose the cisco-ai-skill-scanner analyzers, scan policy and optional LLM, VirusTotal and Cisco AI Defense checks.

setup mcp-scanner

Choose the cisco-ai-mcp-scanner analyzers and whether scans also cover MCP prompts, resources and instructions.

defenseclaw sandbox legacy-cleanup

Linux-only removal of the retired standalone OpenShell sandbox (openshell-sandbox 0.0.x). Restores host OpenClaw networking, ownership, and config.

OpenShell sandbox

defenseclaw sandbox setup prepares a Linux machine or an Apple-silicon Mac to run Claude Code and Codex inside NVIDIA OpenShell 0.1 sandboxes, and defenseclaw sandbox run claude starts one on the current project folder. On a Mac, sandboxes are OpenShell MicroVMs and every run works on a copy (see macOS). The same setup is the Sandboxes (OpenShell) wizard in the TUI's Setup and the Sandbox wizard in the macOS app; the TUI Sandboxes panel (key 7) shows live activity. Run defenseclaw sandbox --help for every command. defenseclaw sandbox legacy-cleanup removes the retired openshell-sandbox 0.0.x install from Linux hosts. The sandbox guide covers setup, runs and legacy cleanup.

Deployment and policy references

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

Secure Client managed deployment

DefenseClaw as a Cisco Secure Client module on Windows and macOS. For any other managed deployment, see Enterprise deployment.

Sandbox policy packs

The open, balanced, and strict OpenShell sandbox packs, custom packs, openshell.admin limits, and sandbox policy explain.

Redaction profiles

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

Interactive vs non-interactive

The operator commands do not all share one interaction model. This table lists the interactive and scripted form of each.

Command	Interactive	Non-interactive	Notes
`init`	yes, on a TTY	`--non-interactive --yes` + per-option flags	Guided first run. `--fail-mode`, `--observe-all` and `--action-connectors` cover the choices it asks about.
`quickstart`	no	always	Zero-prompt first run by design; use `init` for the wizard.
`setup guardrail`	yes (default)	`--non-interactive` + flags	Missing flags fall back to the wizard defaults. Hook fail mode and judge fallback models have no flag here; see Prompt-flag mapping.
`setup <connector>`	yes	flags + `--yes`	Adds or reconfigures a connector. With other connectors configured the default, also under `--yes`, is to add; `--replace` switches. With `--mode`, a TTY run does not ask for the mode again.
`setup routing`	no	`--enable`, `--disable` or `--status`	Requires Docker. Applies only to proxy-mode OpenAI Chat Completions traffic.
`keys set`	hidden prompt when no value is given	`--value-stdin` (or `--value`, which is visible in `ps`)	See Unified LLM key.
`keys fill-missing`	yes	`--yes` skips the opening confirmation	Prompts for every required key that is not set.
`keys list` / `keys check`	no	always	`keys check` exits non-zero when a required key is missing.
`keys remove`	asks to confirm	`--yes`	See Keys.
`setup webhook add <type>`	yes (default)	`--non-interactive` + flags	URL and secret env are prompt-or-flag; the type is always positional.
`setup webhook test <name>`	no	always	Safe to re-run; `--dry-run` formats without delivering.
`registry add <id>`	yes (default)	`--non-interactive` + flags	`registry wizard` is the first-run add-and-sync flow.
`registry sync` / `entries` / `approve` / `reject`	no	flags only	Designed for cron and scripts.
`setup splunk`	yes, when no mode flag is given	`--non-interactive` + `--logs`, `--enterprise` or `--o11y`	The HEC token comes from `--hec-token` or the `DEFENSECLAW_SETUP_SPLUNK_HEC_TOKEN` env var; the env var keeps it out of `ps`.
`setup local-observability`	no	subcommands	`up` is the default; `down` stops the stack and keeps its data; `reset` also deletes the data. `status`, `logs`, `url` and `env` read state.
`setup redaction`	yes (bare command)	subcommands + flags	The simple flow leads into Show advanced settings? for buckets, profiles, destinations and routes.
`setup skill-scanner` / `setup mcp-scanner`	yes	`--non-interactive` + flags	The skill scanner SDK is a hard dependency; the MCP scanner SDK is installed on Python 3.11 and newer.
`sandbox setup`	yes (default)	`--non-interactive`, or `--yes` to take every default	One-time setup for OpenShell sandboxes on Linux, or on a Mac with Apple silicon. See the sandbox guide.
`sandbox legacy-cleanup`	yes (prints the plan, then asks once)	`--yes`; `--dry-run` prints the plan only	Linux-only removal of the retired standalone sandbox.
`doctor`	only with `--fix`	`--fix --yes`	A plain run is read-only and never prompts.
`alerts`	no	`--limit`, `--connector`, `--show <n>`, `--json`; `acknowledge` / `dismiss` subcommands	A snapshot of recent alerts, not a live tail.
`tui`	full-screen dashboard	none	Interactive only.
`defenseclaw-gateway`	no	`--host`, `--port`	Run bare for the foreground daemon; `start`, `stop` and `restart` manage the background daemon. `setup guardrail --restart` restarts it for you.

Redaction is its own workflow

defenseclaw setup redaction edits the v8 bucket, profile, destination and route policy for telemetry. See Redaction for the interactive and scripted workflow, which is also in TUI → 0 Setup → Guardrail & scanning → Redaction and in the macOS app under Logs → Redaction policy….

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 write files under ~/.defenseclaw/, depending on the feature being configured, including:

~/.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)
  picked_connector        # last connector picked by install.sh or connector setup
  custom-providers.json   # custom LLM providers (setup provider add)
  hooks/                  # connector hook scripts, written when the gateway starts
  policies/               # rule packs and admission policies
  registries/<id>/        # cached manifest + scanner verdicts for each registry source
  semantic-router/        # generated router config (setup routing)
  gateway.jsonl           # optional: only when an explicit kind: jsonl destination uses this path

The list covers the common files, not every one. See Configuration for the full layout.

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.

Setup commands

On this page