Quickstart
First run in two minutes. Pick init for the guided wizard or quickstart for the zero-prompt scripted equivalent — both call the same first-run backend and end with a working guardrail.
After the install, DefenseClaw is on disk but not yet configured. You then run one first-run command. There are two of them — they do the same work, with different UX.
defenseclaw init
Interactive wizard. Asks about connector, profile, scanner mode, judge, HITL. Recommended the first time.
defenseclaw quickstart
Zero-prompt equivalent with safe defaults. Recommended for CI, scripts, and demos.
You do not need to run init before quickstart. Both invoke
the same run_first_run backend (cli/defenseclaw/bootstrap.py)
that writes config, seeds the audit DB, configures guardrail, and
starts the gateway. Pick one.
Path A — Interactive (defenseclaw init)
The recommended first run for a human at a terminal. The wizard walks you through every choice, shows defaults, and explains the trade-offs.
defenseclaw initOn a TTY this runs the guided path (_prompt_first_run). It runs local agent discovery, pre-selects every installed hook connector, and configures them all in observe (log-only) mode by default — pressing Enter through the connector prompt brings up everything you have. Rather than asking observe-vs-action for each one, it asks a single question, "Action-mode connector(s)", naming the subset that should enforce. Leave it blank and every connector stays in observe.
The action-only policy knobs — hook fail-mode (open/closed) and HITL human-approval plus its minimum severity — are asked once and shared across every connector you promote to action; observe connectors never see them. Proxy connectors (openclaw, zeptoclaw) are detected but excluded from the observe-all set — they own the single LLM proxy port and can't be multi-connector peers — so the wizard prints a one-line note pointing you to defenseclaw setup <proxy> for them.
An action connector whose installed version doesn't map to a known hook contract is downgraded to observe with a warning — the same gate the gateway applies at boot. Override only for exploratory testing with DEFENSECLAW_ALLOW_HOOK_CONTRACT_DRIFT=1.
Scripted init (no prompts)
To skip the wizard — including inside a session that is a TTY (CI on a pty, scripted demos) — defenseclaw init exposes two init-only multi-connector flags. These do not exist on quickstart:
# Observe every detected hook connector, enforce on codex:
defenseclaw init --non-interactive --yes --observe-all --action-connectors codexFlag (init only) | Effect |
|---|---|
--observe-all | Configure every detected hook connector in observe mode. |
--action-connectors codex,claudecode | Comma-separated connectors to configure in action mode. Composable with --observe-all (everything else stays observe); the named connectors are configured even on their own. |
--non-interactive | Skip every prompt. |
--yes / -y | Auto-accept every confirmation. |
--connector <x> | Pre-select a single agent. Single-connector path — wins over the multi flags. |
With neither multi flag nor --connector, non-interactive init keeps the single-connector default: one discovery-backed connector in observe. An explicit --connector always wins.
Path B — Zero prompts (defenseclaw quickstart)
The scripted equivalent. Same backend, no prompts ever, safe defaults baked in: observe profile, local scanner, no LLM judge, no HITL.
Run it
defenseclaw quickstart --connector claudecodeReplace claudecode with codex, cursor, windsurf, geminicli, copilot, hermes, openhands, antigravity, opencode, omnigent, openclaw, or zeptoclaw to target the agent you actually use. quickstart configures one connector. If you skip --connector, it uses the single configured or detected connector; if more than one connector is configured/detected, or the installer hint disagrees with the detected connector, it exits and asks you to rerun with --connector <name>.
Watch the report
The command emits a one-screen first-run summary:
DefenseClaw — first run report
──────────────────────────────────────────────
status ok
connector claudecode (Claude Code)
profile observe
scanner_mode local
judge disabled
hilt disabled
gateway running on 127.0.0.1:18970
audit DB ~/.defenseclaw/audit.dbIf status is needs_attention the command exits non-zero and lists the gaps (missing API key, gateway port in use, …) with the exact next command to run.
Drive the agent
Open Claude Code (or whichever connector you picked). Every prompt and tool call now flows through DefenseClaw. Watch decisions land in the live dashboard:
defenseclaw tuiOr tail the JSONL fan-out from a script:
tail -f ~/.defenseclaw/gateway.jsonl | jq .What both paths do
All quickstart flags
Prop
Type
When to use which
| Situation | Use |
|---|---|
| First-time setup at a terminal | defenseclaw init |
| You want to be asked questions and shown defaults | defenseclaw init |
| Installer hand-off / unattended provisioning | defenseclaw quickstart --connector <x> |
| CI pipeline (no TTY, deterministic config) | defenseclaw quickstart --connector <x> --non-interactive --yes --json-summary |
| Scripted demo / repeatable test fixture | defenseclaw quickstart --connector <x> --force |
Next
Upgrade DefenseClaw
Safely upgrade DefenseClaw with verified artifacts, automatic schema migrations, backups, health checks, and durable OTel destination conversion.
First guardrail in 5 minutes
An end-to-end walkthrough — install, pick Claude Code, switch to action mode, and safely verify a destructive-command rule against a disposable path.