First run: init and quickstart

The two first-run commands. defenseclaw init is the guided wizard and defenseclaw quickstart is the zero-prompt equivalent. Both run the same setup and print the same first-run report.

After the install, DefenseClaw is on disk but not configured. defenseclaw init is the guided wizard. defenseclaw quickstart is the zero-prompt equivalent with safe defaults. Both run the same setup and print the same report. You do not need init before quickstart. If init chose no agent and started the gateway, quickstart --connector <name> restarts the gateway so it loads the agent and writes its hooks. For a guided first block, follow the Quickstart.

Path A: interactive (defenseclaw init)

On a terminal, init runs local agent discovery, prints the Agent discovery table and asks, in this order:

  1. Select active connector(s): every installed hook connector is pre-selected (on an install that is already set up, the active ones). Clear a box to leave that agent out, or clear every box to protect no host agent for now.
  2. Scanner mode (local, remote or both, default local).
  3. Select connector(s) for action enforcement: the agents you tick block; every other selected agent runs in observe.
  4. Only when you ticked an agent in step 3: Require human approval for risky actions? (default no; yes also asks the minimum severity), asked once and shared by every action agent, then Select action connector(s) for LLM judge (leave it clear for rules-only scanning; a ticked agent asks for the judge LLM settings).
  5. Do you want to use a decision model? (default no). Asked when a connector is in action mode. A decision model is an optional fast model for tool calls, in front of the LLM judge or on its own; yes asks for its endpoint and model name and covers the action-mode connectors.
  6. Start gateway after setup? (default yes), then Run targeted readiness checks? (default yes).

init does not ask for an outage mode and saves none: while the gateway is not running, the default and permissive policies let a call run with a warning and strict blocks it. Pass --fail-mode to save a choice; a saved choice wins over the policy, also over use-pack strict (except OpenClaw under the strict policy and ZeptoClaw model requests, which stay closed despite a saved open). When a saved open decides, the Next lines say While the gateway is not running, hooks let calls run with a warning (your saved fail mode; to block them: ...) and name the command that saves closed instead. A later init run keeps the fail modes already saved for your connectors.

Proxy connectors are detected but left out of the observe-all set, because they own the single LLM proxy port. Use defenseclaw setup <proxy> for them.

An agent version newer than DefenseClaw's tested versions keeps action mode and is reported as untested. A connector whose installed version has no hook contract is left out in observe and action mode, because setup refuses it in both. With other connectors selected, init configures them and reports the one it left out. Alone, it writes no connector config and reports needs_attention. quickstart refuses it the same way. The refusal names the version to install and the command to run after the upgrade: defenseclaw init, or defenseclaw quickstart --connector <name> for quickstart. An action connector whose version could not be read (not probed, or outside a trusted prefix) is configured in observe with a warning. See Hook contracts.

Scripted init (no prompts)

Scripted use skips the wizard:

defenseclaw init --non-interactive --yes --observe-all --action-connectors codex

defenseclaw init

FlagWhat it does
--connector <name>Pre-select a single agent. Wins over the multi-connector flags. init has no --agent alias; quickstart has one.
--observe-allConfigure every detected hook connector in observe.
--action-connectors a,bConnectors to configure in action. Works with --observe-all.
--non-interactiveSkip every prompt.
--yes / -yAccept the default for every prompt. The gateway prompt defaults to yes, so --yes starts the gateway and writes the agent hooks, as the wizard does.
--profileProtection profile (observe or action).
--scanner-modelocal, remote or both.
--fail-mode open|closedHook fail mode.
--human-approval / --no-human-approvalHITL.
--hilt-min-severityLowest severity that asks.
--with-judge / --no-judgeThe LLM judge.
--llm-provider, --llm-model, --llm-api-key-env, --llm-base-urlThe unified LLM key settings.
--llm-api-keyLLM key to save into .env; the config stores only the env name. Other local users can see a command-line value, so prefer DEFENSECLAW_INIT_LLM_API_KEY.
--decision-model-url, --decision-model-name, --decision-model-key-env, --decision-model-connectorsTurn on the decision model at this endpoint, answering alone for the listed connectors where the judge does not run (default: the action-mode connectors). Without them the wizard asks Do you want to use a decision model? (default no) and --yes leaves it off. quickstart takes the same flags.
--decision-model / --no-decision-model--no-decision-model turns the decision model off; --decision-model needs the URL and name flags.
--cisco-endpoint, --cisco-api-key-envCisco AI Defense.
--cisco-api-keyCisco AI Defense key to save into .env. Prefer DEFENSECLAW_INIT_CISCO_API_KEY, for the same reason.
--enable-guardrailConfigure the LLM guardrail during init.
--start-gateway / --no-start-gatewayAnswer the gateway prompt in advance. Without either flag, --non-interactive alone leaves a stopped gateway stopped, and defenseclaw doctor fails its gateway and hook rows until you run defenseclaw-gateway start.
--verify / --no-verifyRun readiness checks before exiting.
--rescan-agentsRefresh cached agent discovery.
--api-port <port>, --proxy-port <port>The gateway API port and the guardrail proxy port of a new configuration. Without them init uses 18970 and 4000, or the next free port when another account on the machine holds one, and says so. An existing configuration keeps its ports; init then names defenseclaw setup gateway --api-port <port> or defenseclaw setup guardrail --port <port>, which move them. The gateway also listens on the two ports after the API port (sandboxes), so init, setup gateway and setup guardrail refuse a proxy port that is one of those three, or OpenClaw's gateway port 18789, and the automatic pick skips a port you gave; defenseclaw config validate warns about such a layout.
--json-summaryPrint the report as JSON.
--verboseShow full subprocess output.
--skip-installSkip the scanner and built-in guardrail availability checks.

With no multi-connector flag and no --connector, non-interactive init keeps one connector found by discovery, in observe. defenseclaw init --help lists every option.

Path B: zero prompts (defenseclaw quickstart)

defenseclaw quickstart --connector claudecode

Quickstart configures one connector, with the observe profile, the local scanner, no judge and no HITL. Without --connector it uses the single configured or detected connector. If more than one is configured or detected, it exits and asks for --connector <name>. On an install that already guards other connectors, quickstart --connector <name> exits without changes; use defenseclaw setup <name> --yes to add an agent, or defenseclaw init to change the set.

The first-run report

First-run report
  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  not started (--skip-gateway)

  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 not found yet - written when the gateway starts
  ✓ Agent installation  claudecode is installed
  - LLM API  not configured
  - Cisco AI Defense  scanner_mode is local
  ✓ Gateway binary  found on PATH

  Next
  defenseclaw-gateway start
  defenseclaw doctor
  defenseclaw keys list
  Adding another agent later: defenseclaw setup <connector>
  While the gateway is not running, hooks let calls run with a warning (strict policy blocks them: defenseclaw guardrail use-pack strict).
  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

The first line holds the status (ready, partial or needs_attention), the connector (or connectors=N) and the profile. Setup lists what the command did, Readiness what it checked, and Next up to five commands to run. A Gateway API port or Guardrail proxy port line appears in Setup when another account on the machine uses the default port, or when you gave --api-port or --proxy-port.

Exit codeMeaning
0Status ready or partial
1needs_attention
2Stopped before changing anything, for example when it cannot tell which connector you mean

In CI, check the status field of --json-summary, because partial also exits 0.

What both paths do

defaults
your answers
defenseclaw quickstartuses safe defaults
defenseclaw initasks you questions
1. Saves config.yamlyour choices or defaults
2. Prepares the data diraudit DB, policies, scanners
3. Connects your agenthooks, plugin or proxy
4. Starts the gatewaydefenseclaw-gateway
5. Checks readinessprints the report

List view for small screens. Use the expand button to open the drawing.

  1. defenseclaw initasks you questions
    • your answers1. Saves config.yaml
  2. defenseclaw quickstartuses safe defaults
    • defaults1. Saves config.yaml
  3. 1. Saves config.yamlyour choices or defaults
    • 2. Prepares the data dir
  4. 2. Prepares the data diraudit DB, policies, scanners
    • 3. Connects your agent
  5. 3. Connects your agenthooks, plugin or proxy
    • 4. Starts the gateway
  6. 4. Starts the gatewaydefenseclaw-gateway
    • 5. Checks readiness
  7. 5. Checks readinessprints the report
init asks its questions first; quickstart takes safe defaults. Both then run the same steps. --skip-gateway (quickstart) or --no-start-gateway (init) skips step 4.

All quickstart flags

Prop

Type

On native Windows, quickstart rejects a connector that is not supported there before it writes anything.

When to use which

SituationUse
First setup at a terminaldefenseclaw init
Installer hand-off or unattended provisioningdefenseclaw quickstart --connector <x>
CIdefenseclaw quickstart --connector <x> --json-summary
Repeatable test fixturedefenseclaw quickstart --connector <x> --force