Overview

DefenseClaw stores state across several files under ~/.defenseclaw/. This page enumerates every file, what it contains, which process owns it, and what happens when it's missing.

The layout

~/.defenseclaw/
├── config.yaml                   # primary config
├── .env                          # secrets (0600)
├── audit.db                      # SQLite store
├── gateway.jsonl[.gz]            # append-only structured log + rotations
├── policy/                       # operator overlays
│   ├── rego/*.rego
│   ├── data.json
│   └── guardrail/<profile>/
├── snapshots/                    # drift snapshots (skills, mcp, plugins)
├── quarantine/                   # files moved out of agent reach
├── custom-providers.json         # provider domain allow-list overlay
├── extensions/defenseclaw/       # OpenClaw plugin tree
├── scanners/                     # custom scanner registrations
└── sandbox/                      # sandbox-local state (Linux)

File-by-file

File	Purpose	Owner	Hot-reload
`config.yaml`	Primary config (gateway, guardrail, audit sinks, webhooks, watcher, firewall)	CLI writes; sidecar reads	partial; process config may require restart
`.env`	All secret material (master key, judge API key, sink tokens). Mode `0600`.	CLI writes; sidecar reads at start	no (restart required)
`audit.db`	SQLite store of every event	sidecar writes; CLI reads	n/a
`gateway.jsonl`	Append-only structured event log	sidecar writes	n/a
`policy/rego/*.rego`	Operator overlay Rego modules	human edits	yes (`policy reload`)
`policy/data.json`	Operator overlay `data.json`	human edits	yes (`policy reload`)
`policy/guardrail/<profile>/rules/*.yaml`	Operator rule-pack overlay	human edits	yes (`policy reload`)
`policy/guardrail/<profile>/suppressions.yaml`	Operator suppressions overlay	human edits	yes (`policy reload`)
`snapshots/*.json`	Per-artifact drift snapshots	sidecar writes; `approve` command updates	n/a
`quarantine/**`	Quarantined artifacts	watcher moves	n/a
`custom-providers.json`	Custom LLM provider overlay for the guardrail fetch plugin	`setup provider add/remove`	yes
`extensions/defenseclaw/`	OpenClaw plugin tree	`setup guardrail` manages	no (restart OpenClaw)
`scanners/*.yaml`	Custom scanner registrations	human edits	yes (`policy reload`)
`sandbox/policy.yaml`	Linux sandbox policy	human edits; `init --sandbox` installs	yes (next invocation)

Ownership and permissions

Everything under ~/.defenseclaw/ is owned by the installing user.
.env is 0600. Violating permissions on .env causes defenseclaw doctor to fail.
audit.db is 0600 by default; relaxing permissions is discouraged.
policy/ is 0755 on directories, 0644 on files — human-editable.

Backup and restore

Backing up ~/.defenseclaw/ is equivalent to a full state snapshot. For airgapped DR, zip the whole directory (excluding logs/ and snapshots/ if you want a leaner image).

Restore is drop-in: untar into ~/.defenseclaw/ on a fresh host and start the sidecar. doctor confirms integrity.

Overrides via environment variable

DEFENSECLAW_HOME=/opt/defenseclaw

Changes the base directory. Useful for system installs or containerized deployments that want to mount state separately.

Config files — DefenseClaw