Overview

defenseclaw init is the one-command bootstrap for every DefenseClaw installation. It creates the on-disk layout under ~/.defenseclaw/, generates the Ed25519 device key the sidecar uses to authenticate with OpenClaw, seeds default policies and guardrail rule packs, initializes the SQLite audit database, and verifies that scanner SDKs are importable. It is idempotent: re-running it preserves existing config, openclaw.json patches, seeded policies, and the audit database.

Flags

Flag	Effect
`--skip-install`	Do not attempt to verify or install scanner SDK dependencies. Useful on airgapped hosts where `pip`/`uv` cannot reach PyPI.
`--enable-guardrail`	After `init` completes, run the full interactive guardrail setup inline (install the OpenClaw plugin, patch `openclaw.json`, restart the sidecar). Equivalent to `init` followed by `setup guardrail`.
`--sandbox`	Linux only. Configure OpenShell sandbox standalone mode: creates the `sandbox` user, installs network policy templates, generates systemd units. See sandbox.

See also the autogenerated init command page for the canonical flag table.

What this creates

Path	Contents	Created by
`~/.defenseclaw/config.yaml`	Main config (gateway, guardrail, scanners, audit sinks, webhooks)	`cfg.save()`
`~/.defenseclaw/audit.db`	SQLite audit store	`Store(cfg.audit_db).init()`
`~/.defenseclaw/device.key`	Ed25519 private key in PEM form, mode `0600`, used to authenticate the sidecar to OpenClaw	`_ensure_device_key`
`~/.defenseclaw/policy/rego/`	Seeded Rego modules + `data.json` from the bundled defaults	`_seed_rego_policies`
`~/.defenseclaw/policy/guardrail/{default,strict,permissive}/`	Seeded guardrail rule-pack profiles (operator can edit in place)	`_seed_guardrail_profiles`
`~/.defenseclaw/splunk-bridge/`	Vendored Splunk local-bridge runtime	`_seed_splunk_bridge`
`~/.defenseclaw/observability-stack/`	Bundled Prom/Loki/Tempo/Grafana stack for `setup local-observability`	`_seed_local_observability_stack`
`~/.defenseclaw/data/`	Watcher snapshots and periodic state	`cfg.data_dir`
`~/.defenseclaw/quarantine/`	Skill/MCP artifacts the watcher pulled out of OpenClaw	`cfg.quarantine_dir`
`~/.defenseclaw/plugins/`	gRPC scanner plugins discovered by `internal/scanner`	`cfg.plugin_dir`
`~/.defenseclaw/.env`	Operator secrets (optional, `0600`); lazily created by `keys set` or `setup guardrail`	`_save_secret_to_dotenv`

On a fresh machine the full tree is created under the user that invoked the command. When --sandbox is passed, ownership is eventually handed to sandbox:sandbox after the network namespace comes up (see setup-sandbox).

Output sections

init prints seven sections in order so failures are easy to locate:

Environment — prints DefenseClaw, Gateway, Platform, Config, Claw mode, Claw home.
Scanners — runs _verify_scanner_sdk for skill-scanner and mcp-scanner. Each prints either available or not installed; not installed is not fatal — re-run after pip install defenseclaw.
Gateway — resolves host:port and the shared auth token from ~/.openclaw/openclaw.json, writes OPENCLAW_GATEWAY_TOKEN to ~/.defenseclaw/.env, generates the device key.
Guardrail — if --enable-guardrail, runs the interactive wizard inline. Otherwise prints a pointer.
Skills — installs the CodeGuard proactive skill into the OpenClaw skills directory (unless openshell.mode=standalone, in which case it's deferred to sandbox setup).
Sandbox — only shown when --sandbox is set.
Sidecar — starts defenseclaw-gateway unless --sandbox is set (the sandbox path starts the sidecar later via systemd or run-sandbox.sh). Polls /health and prints subsystem status.

Verify it worked

ls -la ~/.defenseclaw/
test -f ~/.defenseclaw/device.key && echo "device key OK"
sqlite3 ~/.defenseclaw/audit.db "select count(*) from activity;"
defenseclaw status

The audit DB will be empty on first run — that's fine. The final summary from init itself is the authoritative checklist.

Undo / reset

init has no --uninstall flag; the uninstall path lives at defenseclaw uninstall. To reset to a clean state without removing binaries:

defenseclaw-gateway stop
rm -rf ~/.defenseclaw/
defenseclaw init

This loses the audit database and all local suppressions. Back up ~/.defenseclaw/config.yaml and ~/.defenseclaw/audit.db first if you want to preserve history.

Troubleshooting

Symptom	Cause	Fix
`ERROR: Sandbox mode requires Linux.`	`--sandbox` on macOS/Windows	Remove `--sandbox` or switch to a Linux host
`skill-scanner: not installed`	The Python package lacks extras	`pip install defenseclaw` (the wheel bundles the SDK)
`mcp-scanner: requires Python >=3.11 (skipped)`	Python 3.10 interpreter	Install under Python 3.11+ (`uv tool install --python 3.13 defenseclaw`)
`Sidecar: not found (binary not installed)`	`defenseclaw-gateway` not on `PATH`	`make gateway-install` or re-run the curl installer
`Health: not responding`	Sidecar started but REST API not up yet	Wait a few seconds, then `defenseclaw-gateway status`

defenseclaw init — DefenseClaw