---
title: Setup
description: 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.
keywords:
  - defenseclaw setup
  - DefenseClaw configuration
  - setup guardrail
  - setup webhook
  - setup registry
  - unified LLM key
  - DefenseClaw observability
  - per-connector setup
---

`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`.

<Callout title="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.
</Callout>

## The central command

<Cards>
  <Card
    title="defenseclaw setup guardrail"
    href="/docs/setup/guardrail"
    description="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."
  />
</Cards>

## Connector aliases (thin wrappers around `setup guardrail`)

Each alias pre-fills the connector flag and inherits every guardrail option. Pass `--mode observe` to run any of them in audit-only mode.

<Cards>
  <Card title="setup openclaw" href="/docs/setup/guardrail/aliases" description="Pins claw.mode=openclaw, installs the fetch interceptor + before_tool_call plugin." />
  <Card title="setup zeptoclaw" href="/docs/setup/guardrail/aliases" description="Pins claw.mode=zeptoclaw, redirects api_base, runs scan + response-scan." />
  <Card title="setup claude-code" href="/docs/setup/guardrail/aliases" description="Pins claw.mode=claudecode and installs the PreToolUse / Stop hooks into Claude Code's settings.json." />
  <Card title="setup codex" href="/docs/setup/guardrail/aliases" description="Pins claw.mode=codex and installs the inspect-request / inspect-response hooks." />
  <Card title="setup cursor" href="/docs/setup/guardrail/aliases" description="Pins claw.mode=cursor and writes hooks.json plus MCP/skills/rules surfaces." />
  <Card title="setup windsurf" href="/docs/setup/guardrail/aliases" description="Pins claw.mode=windsurf — Cascade hooks plus local config discovery." />
  <Card title="setup gemini-cli" href="/docs/setup/guardrail/aliases" description="Pins claw.mode=geminicli and configures settings.json hooks plus native OTLP export." />
  <Card title="setup copilot" href="/docs/setup/guardrail/aliases" description="Pins claw.mode=copilot and writes the .github/hooks command hooks." />
  <Card title="setup hermes" href="/docs/setup/guardrail/aliases" description="Pins claw.mode=hermes and wires config.yaml hooks for MCP, skills, and plugins." />
  <Card title="setup mode <connector>" href="/docs/setup/guardrail/switching-connectors" description="Switch the active claw connector with smart guardrail inheritance — does not re-prompt for guardrail options unless you change the integration scope." />
</Cards>

## 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.

<Cards>
  <Card
    title="defenseclaw keys"
    href="/docs/setup/unified-llm-key"
    description="Stash DEFENSECLAW_LLM_KEY (and any per-component overrides) in ~/.defenseclaw/.env. Top-level group: list, set, fill-missing, check. Not a setup subcommand."
  />
  <Card
    title="setup webhook"
    href="/docs/setup/webhooks"
    description="Add Slack, PagerDuty, Webex, or generic HMAC notifiers for high-severity alerts. Test deliveries, list, enable/disable, remove."
  />
  <Card
    title="defenseclaw registry"
    href="/docs/setup/registries"
    description="Subscribe to public or internal skill / MCP catalogs (clawhub, smithery, http_yaml, http_json, git, file). Sync, scan, promote into asset_policy."
  />
  <Card
    title="setup splunk"
    href="/docs/observability/splunk"
    description="Configure the audit-sink HEC forwarder. Replays past events on enable, redacts PII before send."
  />
  <Card
    title="setup local-observability"
    href="/docs/observability/local-observability"
    description="Bring up the bundled OTLP collector + Grafana stack so you can see decisions live without leaving your laptop."
  />
  <Card
    title="setup skill-scanner"
    href="/docs/setup/skill-scanner"
    description="Wire the cisco-ai-skill-scanner SDK into admission. Optional VirusTotal + LLM second-opinion."
  />
  <Card
    title="setup mcp-scanner"
    href="/docs/setup/mcp-scanner"
    description="Wire the cisco-ai-mcp-scanner SDK into admission. Behavioral introspection of MCP servers before they're added."
  />
  <Card
    title="setup redaction"
    href="/docs/reference/redaction"
    description="Toggle privacy.disable_redaction on/off and inspect status. The right way to manage the redaction kill-switch."
  />
</Cards>

## 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 mode <connector>` | yes | flags only | Reuses the existing guardrail config; only re-prompts when the integration scope changes. |
| `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. |

<Callout title="See it for yourself">
The interactive flow for the central command is replayed end-to-end on the [Setup guardrail](/docs/setup/guardrail) page. Every other verb follows the same prompt-or-flag rhythm.
</Callout>

## 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`](/docs/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](/docs/setup/unified-llm-key).
