First run: init and quickstart

After the install, DefenseClaw is on disk but not configured yet. One first-run command configures it. There are two, and they do the same work with a different experience. For a guided first block, follow the 5-minute quickstart instead.

Path A: interactive (defenseclaw init)

The recommended first run for a person at a terminal. The wizard walks you through every choice, shows the defaults and explains the trade-offs.

defenseclaw init

On a terminal this runs the guided wizard. It runs local agent discovery, pre-selects every installed hook connector and configures them all in observe (log-only) mode by default, so pressing Enter through the connector prompt brings up everything you have. Rather than asking observe or action for each one, it shows one checklist, Select connector(s) for action enforcement, where you tick the agents that should block. Leave every box unchecked and every connector stays in observe.

The action-only policy settings, the hook fail mode (open or closed) and HITL human approval with its minimum severity, are asked once and shared by every connector you promote to action. Observe connectors never see them.

Near the end the wizard asks Start gateway after setup? (default Yes, because the hooks need a running gateway). --start-gateway or --no-start-gateway answers it in advance. When you add the optional LLM judge on AWS Bedrock, the wizard asks for the region and auth mode first, and asks for an API key only for the api_key auth mode. On macOS, an OpenHands installed with uv tool sits outside the trusted prefixes, so the wizard offers to trust its directory instead of skipping it. Proxy connectors are detected but left out of the observe-all set, because they own the single LLM proxy port and can't run beside other connectors. The wizard prints a one-line note that points you to defenseclaw setup <proxy> for them.

Scripted init (no prompts)

To skip the wizard, including in a session that is a terminal (CI on a pty, scripted demos), defenseclaw init has two init-only multi-connector flags. They don't exist on quickstart:

# Observe every detected hook connector, enforce on codex:
defenseclaw init --non-interactive --yes --observe-all --action-connectors codex

With neither multi-connector flag nor --connector, non-interactive init keeps the single-connector default: one connector found by discovery, in observe. An explicit --connector always wins. defenseclaw init --help lists every option, including the LLM and Cisco AI Defense settings.

Path B: zero prompts (defenseclaw quickstart)

The scripted equivalent. It runs the same setup, never prompts and uses safe defaults: the observe profile, the local scanner, no LLM judge and no HITL.

defenseclaw quickstart --connector claudecode

  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  started

  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 found
  ✓ Sidecar  running
  - LLM API  not configured
  - Cisco AI Defense  scanner_mode is local
  ✓ Gateway binary  found on PATH

  Next
  defenseclaw doctor
  defenseclaw keys list
  Adding another agent later: defenseclaw setup <connector>
  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

defenseclaw tui

defenseclaw-gateway audit export --newest --limit 200 | jq .

What both paths do

All quickstart flags

When to use which

Next