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:
- 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.
- Scanner mode (
local,remoteorboth, defaultlocal). - Select connector(s) for action enforcement: the agents you tick block; every other selected agent runs in
observe. - 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).
- 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.
- 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 codexdefenseclaw init
| Flag | What it does |
|---|---|
--connector <name> | Pre-select a single agent. Wins over the multi-connector flags. init has no --agent alias; quickstart has one. |
--observe-all | Configure every detected hook connector in observe. |
--action-connectors a,b | Connectors to configure in action. Works with --observe-all. |
--non-interactive | Skip every prompt. |
--yes / -y | Accept 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. |
--profile | Protection profile (observe or action). |
--scanner-mode | local, remote or both. |
--fail-mode open|closed | Hook fail mode. |
--human-approval / --no-human-approval | HITL. |
--hilt-min-severity | Lowest severity that asks. |
--with-judge / --no-judge | The LLM judge. |
--llm-provider, --llm-model, --llm-api-key-env, --llm-base-url | The unified LLM key settings. |
--llm-api-key | LLM 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-connectors | Turn 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-env | Cisco AI Defense. |
--cisco-api-key | Cisco AI Defense key to save into .env. Prefer DEFENSECLAW_INIT_CISCO_API_KEY, for the same reason. |
--enable-guardrail | Configure the LLM guardrail during init. |
--start-gateway / --no-start-gateway | Answer 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-verify | Run readiness checks before exiting. |
--rescan-agents | Refresh 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-summary | Print the report as JSON. |
--verbose | Show full subprocess output. |
--skip-install | Skip 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 claudecodeQuickstart 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
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 setupThe 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 code | Meaning |
|---|---|
0 | Status ready or partial |
1 | needs_attention |
2 | Stopped 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
List view for small screens. Use the expand button to open the drawing.
- defenseclaw initasks you questions
- your answers1. Saves config.yaml
- defenseclaw quickstartuses safe defaults
- defaults1. Saves config.yaml
- 1. Saves config.yamlyour choices or defaults
- 2. Prepares the data dir
- 2. Prepares the data diraudit DB, policies, scanners
- 3. Connects your agent
- 3. Connects your agenthooks, plugin or proxy
- 4. Starts the gateway
- 4. Starts the gatewaydefenseclaw-gateway
- 5. Checks readiness
- 5. Checks readinessprints the report
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
| Situation | Use |
|---|---|
| First setup at a terminal | defenseclaw init |
| Installer hand-off or unattended provisioning | defenseclaw quickstart --connector <x> |
| CI | defenseclaw quickstart --connector <x> --json-summary |
| Repeatable test fixture | defenseclaw quickstart --connector <x> --force |
Quickstart
Block your first risky tool call in 5 minutes. Install DefenseClaw, run init, turn on blocking for one agent and watch a test command get blocked.
First guardrail
After the quickstart. Switch one agent from observe to action mode so the guardrail blocks, check that it worked, and switch back.