Configuration: one source of truth

DefenseClaw keeps every decision an administrator makes in one place: ~/.defenseclaw/config.yaml, plus the few policy assets that file names by digest (a custom rule pack, a scanner policy file, extra YARA rules, an AI-discovery signature pack). Nothing else stores a decision. The gateway, the hooks, the TUI, the CLI and the enterprise lifecycle all read that one file, and every change goes through one writer.

This page explains the model. For the key-by-key schema, see the configuration reference.

Four kinds of state

Every file DefenseClaw keeps is one of four kinds. The kind tells you whether you may edit it, what happens if you do, and how to fix it.

The split removes a class of bugs where two files disagreed. A block list in a database, a thresholds file next to the rules, or a hook script with a baked-in setting could each override what config.yaml said. In config_version: 9 they cannot: if a value changes what DefenseClaw decides, it is in config.yaml.

How a change becomes enforcement

Three parts of that path matter day to day.

1. One writer. defenseclaw config set, every defenseclaw setup command, the TUI, defenseclaw skill block and the other block commands, and the gateway's own API all change config.yaml through the same writer. It takes the lock config.yaml.lock (the Go gateway and the Python CLI share it), validates the new file against the schema before it writes anything, replaces the file atomically, and records the write in config.generation.json. A change that fails validation leaves config.yaml untouched.
2. One generation. The gateway watches config.yaml and the assets it names. On a change it builds a complete new policy generation off the hot path: it composes the rule packs, compiles admission:, resolves the thresholds for every connector and profile, and prepares the policy engine. Then it swaps the generation in atomically. Every hook decision, proxy decision and install-watcher decision reads one generation, so a request never sees half of a change.
3. A bad change is not applied. If the new generation does not build (a custom rule pack whose digest changed, for example), the gateway keeps enforcing the previous generation and reports the error as last_reload_error. Doctor shows it as a failed Policy check.

Most keys apply with no restart. The keys that name a file or listener the gateway opened at start, or that it reads once at start, still need defenseclaw-gateway restart. A change to one is saved, and the gateway keeps the old value until you restart it:

• data_dir, observability.local.path and observability.local.judge_bodies_path
• gateway.* (the listener, authentication and upstream keys), except gateway.watcher.* and the gateway.config_reload keys other than mode
• guardrail.host, guardrail.port, guardrail.enabled, guardrail.connector, guardrail.scanner_mode and guardrail.retain_judge_bodies
• the hook self-heal settings (guardrail.hook_self_heal and guardrail.hook_self_heal_debounce_ms)
• claw, agent, routing and plugin_dir
• deployment_mode, enterprise.profile and enterprise.network
• the resource-identity keys (environment, tenant_id, workspace_id, discovery_source)

The storage paths and deployment_mode can not be kept that way: after a change to one, the gateway refuses that reload, and every later one, until you restart it, and /health shows the error as last_reload_error.

Adding, removing, enabling or disabling a connector (guardrail.connectors.<c>.enabled) applies in place: the gateway sets up or removes that connector's hooks and restarts its install watcher, without a process restart. On Secure Client, connector changes still need a restart.

Restart-required keys is the reference list. When your change touches one, config set says so:

Set gateway.port (config generation 9, sha256 b0683fad4394).
Effective policy digest: sha256:c770dec74b1d9a5631df0a0f97d907259a661f6baded49b362722e043e12b76e
Restart the gateway to apply gateway.port: defenseclaw-gateway restart

What lives in config.yaml

config.yaml is administrator intent. These sections decide behaviour:

Read a value, and where it comes from, with config get --effective:

defenseclaw config set guardrail.block_at HIGH
defenseclaw config get guardrail.block_at --effective

HIGH
(source: config:guardrail.block_at)

When you do not set a threshold, the same command prints the rule pack's default and names the pack as the source. The same is true for the admission actions, which derive from the scanner gate until you set them.

Some settings point at a file of their own: a custom rule pack, a scanner policy, extra YARA rules. Those assets are pinned. The config entry carries the file's sha256 digest, so a changed file never takes effect silently:

guardrail:
  rule_pack: acme-hardened
  custom_packs:
    acme-hardened:
      path: /etc/acme/defenseclaw/packs/acme-hardened
      digest: sha256:<64 hex digits from the files digest line of validate-pack>

defenseclaw guardrail validate-pack PATH prints the files digest: line to paste after sha256:. If the digest does not match, the change does not build into a generation, and the previous policy keeps running. See Rules.

On a per-user install you may also edit config.yaml by hand. The running gateway validates the file, applies it, and records the edit in config.generation.json with the actor hand-edit:<os-user>. A hand edit that fails validation is not applied. On a managed host, a hand edit is reverted (see Managed hosts).

What is derived

Derived files are rendered from config.yaml and are not read back as configuration input. Connectors execute generated hook scripts, however: an edit can affect the next hook event before repair. Doctor detects the drift; regenerate the affected file as shown below.

A legacy 0.8.x provider overlay is imported during v9 migration when its fields fit llm_providers. If it contains request_overrides, migration leaves the unmarked file as a live input; see Custom providers. It is not a derived file.

Older releases wrote composed protection packs to ~/.defenseclaw/policies/guardrail/protected-<scope>/, and policy YAML to policies/rego/data.json. Neither exists in config_version: 9. The migration converts them into guardrail.rules and admission:; a leftover data.json is ignored, and doctor reports it as Retired policy data. Migrate config.yaml from v8 to v9 lists everything that moved.

What is evidence

Evidence records what was applied. Tools compare the live state with it. Evidence is not policy; changing it does not change what DefenseClaw decides, but it does make a verification step fail.

What is runtime state

Runtime state is what the product saw or did. status and doctor report it, and it is never policy: removing a quarantine record does not change a block list, and a block list does not rewrite a quarantine record.

• Approvals granted at a prompt (HITL).
• The AI-discovery inventory (AI discovery).
• Quarantine records and the quarantined files.
• The enforcement journal in audit.db: the quarantine and runtime-disable rows the install watcher writes, and its automatic blocks. Only asset_policy blocks and allows an asset by name; the journal records what happened to it.
• The hook guardian's target list, targets.yaml, on managed hosts.

The effective policy digest

Every policy generation has an effective policy digest: sha256: plus the hash of the canonical form of the migrated config, with secret values removed, paths under data_dir rewritten to a token, defaults filled in, and the digests of every pinned asset and composed rule pack. Managed hosts of one OS that run the same release and received the same admin config report the same digest, which is what makes a fleet comparable. Do not compare across operating systems: the config names different paths on each.

The digest and the generation appear in these places:

The Policy row fails when the gateway applies a different digest than config.yaml and its assets compute to (a stale gateway), or when the last reload was rejected. It warns when config.yaml was edited outside the writer. The fix for a stale gateway is defenseclaw-gateway restart.

The config generation counts writes of the file. The generation counts applied policy builds, so it also advances when a pinned asset changes. Two hosts can differ in either counter and still have the same digest.

Managed hosts

A managed host is a device on the standalone enterprise profile (deployment_mode: managed_enterprise) that an administrator controls through an MDM or a package. The Secure Client profile is out of scope for all of this: nothing described here changes its behaviour.

On a managed host, the administrator config is the only intent, and ensure is the only writer.

Local writers refuse

Every local command that would change policy refuses on a managed standalone host and changes nothing. The command exits with code 3:

error: This device is managed: change config.yaml in the admin config (MDM or management plane), not on the device

That covers defenseclaw config set and unset, defenseclaw policy activate, the setup commands that save configuration, the TUI Setup panel (read-only on a managed host), and the gateway's /enforce/block and /enforce/allow routes, which answer 403 with managed_device. skill block, mcp block, plugin block and tool block refuse the same way and point you at asset_policy:

This device is managed: add it to asset_policy in the admin config (MDM or management plane)

Reading is unaffected: config get, config show, status, doctor and enterprise policy show all work. Runtime actions are not config writes, so this gate does not apply to them: quarantine, restore, disable and enable act on runtime state. What a standard user may do beyond that is set by the enterprise profile; see Enterprise concepts.

A hand edit of config.yaml does not survive. On Linux and macOS the lifecycle compares the file with the last config it applied, puts the applied config back, and keeps the edit as rejected-config.yaml; status warns and verify fails with config_rejected until a corrected config is pushed. The block and allow entries a user may have left in audit.db before the device was enrolled are ignored, and ensure reports how many.

Environment variables and .env

The environment is a second place where settings could hide, so a managed host narrows it. Every variable DefenseClaw reads has a managed-host policy in the environment variable reference:

A forged DEFENSECLAW_DEPLOYMENT_MODE or DEFENSECLAW_ENTERPRISE_PROFILE cannot turn a managed host into an unmanaged one. Doctor lists every ignored value it finds, by name only, under its active security overrides.

Updates

update.source changes only where release files are downloaded from. The signature check always uses the release identity compiled into DefenseClaw, so a mirror must serve the same signed checksums.txt bundle. Managed hosts do not self-update: defenseclaw upgrade and defenseclaw rollback refuse there, and the lifecycle applies updates. See Lifecycle and the upgrade guide.

Where do I change it?