Configuration
~/.defenseclaw/config.yaml schema for config_version 9, on-disk layout, which files are policy, derived or evidence, reload and restart rules, and per-connector files. The place to look up "where does this setting live?"
~/.defenseclaw/config.yaml is the source of truth for every decision an administrator makes. Setup commands, defenseclaw config set and the policy commands change it through one writer that validates before it writes; on a per-user install you can also edit it by hand. The running gateway validates the whole file on change and swaps in a new policy generation, so most changes need no restart; a change that does not validate leaves the previous generation running. The model behind this is on Source of truth; the keys that need a restart are under Reload without restart.
The current schema is config_version: 9. defenseclaw config reference --format json-schema prints the schema of every section with allowed values, and defenseclaw config validate checks a file. A version 8 file (written by 0.8.5 to 0.8.10) is migrated in memory when the gateway loads it; see Migrate to config version 9.
A refusal of an enumerated key lists only the values you can type: guardrail.hook_fail_mode lists open and closed, not an empty entry. guardrail.connector and claw.mode take the spellings claude-code and claude_code, in any letter case, and are read as claudecode. Words in the OpenShell settings (for example enterprise.openshell.install) mean the same in any letter case. On a managed standalone Linux or macOS host, defenseclaw-gateway config validate refuses a required sandbox pack that ensure refuses.
Windows layouts depend on the installer
The Windows Enterprise Setup package uses an embedded runtime and defenseclaw-hook.exe, without a .venv. The supported per-user install.ps1 route manages a private .venv and generates hook scripts under the data home. See Windows paths before locating or editing Windows state.
Managed computers
On a Linux or macOS computer with the standalone enterprise package, defenseclaw offers users only the commands in Managed command availability (every other command exits 2), and defenseclaw-gateway is not on their PATH. On Windows, defenseclaw.exe is the administrator's command. The defenseclaw and defenseclaw-gateway examples on this page are for a per-user install. The administrator edits the managed config and runs the packaged binary as root: /opt/defenseclaw/bin/defenseclaw-gateway on Linux, /opt/cisco/defenseclaw/bin/defenseclaw-gateway on macOS, and & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise ... from an elevated PowerShell prompt on Windows. Apply a change with enterprise <os> ensure, check it with enterprise <os> verify, and use policy digest and policy reload on the gateway binary. See Change the config and Enterprise settings.
On-disk layout
Where each file lives on macOS and Linux is under What the install creates and Data. Windows paths are on Windows paths. Only config.yaml and the assets it names by digest are policy. Everything else is one of three other kinds, and none of it is read back as input:
| Kind | Files | What to do |
|---|---|---|
Derived (rendered from config.yaml) | custom-providers.json, hooks/<connector>-hook.sh, the composed rule packs and compiled admission (the last two live in memory) | Never edit. Doctor reports drift. Regenerate with defenseclaw doctor --fix (providers) or defenseclaw-gateway restart (hook scripts). |
| Evidence (what was applied) | config.generation.json, hook_contract_lock.json, migration-v9.json, config.yaml.v8.bak, data.json.migrated-v9 | Keep; they explain how the file got here. |
| Runtime state (what was seen or done) | audit.db, doctor_cache.json, judge_bodies.db, quarantine records, the AI-discovery inventory | Reported, never policy. |
config.generation.json records the generation counter, the SHA-256 of the file the writer last wrote, the actor and the reason. config.yaml.lock is the lock the Go and Python writers share. hooks/, hook_contract_lock.json and connector_backups/ appear once a connector is set up; backups/ holds the timestamped copies that commands such as setup redaction write before changing config.yaml. A policies/rego/data.json left over from an upgrade is ignored. gateway.jsonl exists only when an optional kind: jsonl destination explicitly uses that path.
What the install creates
The trees below describe the per-user shell installers, including native Windows install.ps1, which manages a private .venv and generated hook scripts. The Windows Enterprise Setup package uses an embedded runtime and defenseclaw-hook.exe instead; it creates no .venv. See Windows installation for the package layout.
config.yaml, config.generation.json, audit.db and device.key are created by defenseclaw init or quickstart, and the hook scripts by setting up an agent. Only config.yaml is policy; the hook scripts are derived from it. installer/ is the installer that performed the current install (defenseclaw rollback uses it); on macOS and Linux its binaries.sha256 lists the SHA-256 of each installed binary as it runs (cd ~/.local/bin && shasum -a 256 -c ~/.defenseclaw/installer/binaries.sha256); on Windows installer\ holds only install.ps1. On macOS these differ from the binaries in the release archive, which the installer checks against checksums.txt and then signs ad hoc for this Mac. previous/ is the install the last upgrade replaced. On Linux, ~/.local/bin also holds defenseclaw-sensor-helper for the opt-in sandbox kernel feed. When the installer installs uv for you, uv and uvx are in ~/.local/bin too.
On macOS and Linux the installer does not change PATH. If ~/.local/bin is not on it, the installer prints the line to add to your shell profile.
Data
In ~/.defenseclaw, %USERPROFILE%\.defenseclaw on Windows, or DEFENSECLAW_HOME when set.
| Path | What it is | Edit it? |
|---|---|---|
config.yaml | Your configuration. | Use defenseclaw config set or the setup commands. The gateway applies a valid edit and keeps the previous policy if an edit is invalid; run defenseclaw config validate first when you edit by hand. |
config.generation.json | Generation, SHA-256, actor and time of each write to config.yaml. | No. |
custom-providers.json | Custom LLM providers, derived from llm_providers. | No. defenseclaw doctor --fix regenerates it. |
config.yaml.v8.bak, migration-v9.json | Kept by the config_version 9 migration. | Read them. defenseclaw config migrate --ack marks the record read. |
.env | Protected tokens and API keys. | No. Never print it. Use defenseclaw keys. |
audit.db | The local audit database (SQLite). | No. Do not open it with a second writer or attach it to a ticket. |
gateway.log | The gateway's output. | Read it locally; check excerpts before sharing. |
logs/install-*.log | One log per install, upgrade or rollback. | Read it. |
logs/hook-failures.jsonl | Hook delivery failures. | Read it locally; it can hold sensitive details. |
.venv/ | The Python environment the installer manages. | No. |
previous/ | The install the last upgrade replaced. | No. defenseclaw rollback swaps it back. |
hooks/ | Generated hook files and per-connector credentials. | No. Never print or copy them. |
backups/, connector_backups/ | Copies needed to restore agent files and earlier settings, including config.yaml.before-redaction-*. | No. They can contain credentials. |
quarantine/ | Quarantined skills and plugins. | No. Use defenseclaw skill restore or plugin restore. |
gateway.pid, watchdog.pid | Records of the running gateway and watchdog. | No. |
gateway.jsonl | Exists only when an optional kind: jsonl destination explicitly uses that path. | Manage it through observability. |
Doctor cache
~/.defenseclaw/doctor_cache.json is the latest non-dry-run Doctor snapshot. The TUI reads it for the Overview panel instead of repeating network probes on every redraw.
{
"schema_version": 2,
"captured_at": "2026-04-17T18:21:09Z",
"mode": "repair",
"outcome": "failed",
"exit_code": 1,
"passed": 12,
"failed": 0,
"warned": 1,
"skipped": 2,
"summary": {"passed": 12, "failed": 0, "warned": 1, "skipped": 2},
"checks": [
{"status": "warn", "label": "Splunk HEC", "detail": "queue depth 4200/5000"}
],
"repair_summary": {
"planned": 0,
"applied": 1,
"failed": 0,
"blocked": 1,
"manual": 0,
"noop": 0,
"declined": 0,
"requires_confirmation": 0
},
"repairs": [
{"repair_id": "doctor.gateway.service.reconcile", "state": "blocked"}
]
}The top-level and summary counts keep their health-only meaning; repair_summary and repairs form a separate ledger, so a failed or blocked repair can fail the aggregate outcome without raising the health failure count. The CLI publishes the cache atomically after each non-dry-run Doctor run, including nonzero outcomes; doctor --fix --dry-run never writes it. The TUI marks snapshots older than 15 minutes stale. A missing cache is normal before the first Doctor run.
config.yaml schema
Every block is optional, and setup commands preserve comments and unrelated hand edits. Do not copy every default into the file.
Before validating this example, make GALILEO_API_KEY and SPLUNK_ACCESS_TOKEN
available to the validation process from your credential store. The Galileo and
Splunk destinations below require them. Omit those destinations if you do not use
them. Validation is read-only and refuses an unresolved credential reference.
config_version: 9 # current schema; `defenseclaw migrate` rewrites a v8 file (the old file stays as config.yaml.v8.bak)
claw:
mode: claudecode # the primary connector; setup aliases select this with --connector.
# With several connectors active it names the primary one
# (see guardrail.connectors below). It is mirrored to the
# OTel resource attr `defenseclaw.claw.mode` only while a
# single connector is active.
gateway:
host: 127.0.0.1 # upstream agent gateway host (OpenClaw/ZeptoClaw fleet link)
port: 18789 # upstream agent gateway port
fleet_mode: auto # auto | enabled | disabled: when to dial host:port (see below)
api_port: 18970 # gateway REST API port (hooks + TUI dial this)
api_bind: "" # REST API bind override; normally 127.0.0.1 when empty
config_reload:
mode: hot # hot | restart; omitted means hot
watcher: # install watcher for new skills, plugins and MCP servers
enabled: true
skill:
enabled: true
take_action: true # apply the admission actions (quarantine/block) to a rejected new skill; false = alert only
dirs: [] # non-empty replaces the connector's own skill folders
plugin:
enabled: true
take_action: true # same for new plugins (admission.plugin)
dirs: []
mcp:
take_action: true # block a rejected new MCP server in the connector's MCP config
# One observability graph owns collection, local history, routing, redaction,
# sampling, metrics policy and every destination (see Reference > Observability).
observability:
resource:
attributes:
service.name: defenseclaw-gateway
deployment.environment.name: production
trace_policy:
sampler: parentbased_always_on
semantic_profile: defenseclaw-genai-rich-v1
metric_policy:
export_interval_seconds: 60
temporality: delta
local:
path: ~/.defenseclaw/audit.db
judge_bodies_path: ~/.defenseclaw/judge_bodies.db
retention_days: 7 # default rolling window; larger values are deliberate overrides
# Omit defaults/buckets for full-fidelity collection. List only deliberate
# overrides; a route cannot resurrect a signal disabled at collection.
buckets:
diagnostic:
collect: {logs: false, traces: false, metrics: false}
model.io:
redaction_profile: content
redaction_profiles:
soc:
extends: sensitive
detectors: [pii, credentials, secrets]
field_classes:
content: detect
evidence: detect
path: hash
credential: remove
destinations:
- name: local-observability
kind: otlp
protocol: grpc
endpoint: 127.0.0.1:4317
network_safety: {allow_private_networks: true}
# Omitted send/routes means every bucket and all OTLP capabilities:
# logs, traces, and metrics. Profile resolves per bucket; model.io uses
# content above and every other omitted bucket inherits none.
- name: galileo
kind: otlp
preset: galileo
protocol: http/protobuf
endpoint: https://api.galileo.ai/otel/traces
batch: { scheduled_delay_ms: 1000 }
headers:
Galileo-API-Key: {env: GALILEO_API_KEY}
project: defenseclaw
logstream: production
# Keep send/routes omitted for the compiler-owned traces-only route whose
# event_names equal the generated available Galileo family membership.
# Explicit send/routes replace that filter and express operator intent.
# More optional destinations join the same graph. Splunk HEC is logs-only.
- name: org-splunk
kind: splunk_hec
endpoint: https://splunk.example.com/services/collector/event
token_env: SPLUNK_ACCESS_TOKEN
index: defenseclaw
send:
signals: [logs]
buckets: [compliance.activity, security.finding, enforcement.action]
redaction_profile: soc
# Top-level LLM block, written by `defenseclaw setup llm`. Every component
# without its own llm block reads it. `setup llm --role judge` writes
# guardrail.judge.llm instead; the role is a command option, not a key.
llm:
provider: anthropic # anthropic | openai | bedrock | vertex_ai | azure | custom
model: claude-sonnet-4-6
api_key_env: DEFENSECLAW_LLM_KEY
base_url: "" # optional override; LiteLLM picks a default per provider. For an OpenAI-style provider (openai, openai-compatible, vllm, lm_studio) a bare host such as https://host gets /v1 added, so the judge, doctor and the scanners all call https://host/v1/chat/completions; a URL with a path is used as written
instance_name: "" # binds to an llm_providers.custom entry; required with provider: custom
region: "" # generic regional hint (Bedrock / Vertex); provider-specific sub-blocks below take precedence
# forward_custom_headers: copy inbound agent HTTP headers to the upstream LLM
# provider (default on). A blocklist (proxy-hop, auth, host, X-DC-*,
# X-DefenseClaw-*, W3C trace context), RFC 7230 validation and 64-header /
# 32 KiB caps apply regardless.
forward_custom_headers: true
# Provider sub-blocks: only the one matching `provider` is consulted.
bedrock:
region: us-east-1
auth_mode: iam_credentials # api_key | iam_credentials | profile | instance_role
access_key_env: AWS_ACCESS_KEY_ID
secret_key_env: AWS_SECRET_ACCESS_KEY
session_token_env: AWS_SESSION_TOKEN
profile_name: ""
inference_profile: us. # optional model-id prefix
deployment_aliases: {} # alias -> model-id, populated by --bedrock-deployment
vertex:
project_id: acme-prod-vertex
region: us-central1
auth_mode: service_account # service_account | adc | workload_identity
service_account_json_env: GOOGLE_APPLICATION_CREDENTIALS
azure:
endpoint: https://my-resource.openai.azure.com
api_version: "2024-10-21"
auth_mode: api_key # api_key | managed_identity
deployment_aliases: {} # model -> deployment, populated by --azure-deployment-alias
# Inline TLS posture for self-signed or internal endpoints; doctor warns
# when both are set.
tls:
ca_cert_pem: "" # PEM bundle inlined from --tls-ca-cert-file
insecure_skip_verify: false
# Optional semantic model classifier for proxy-mode OpenAI Chat Completions.
# Routing-only edits are validated by config reload but activate on gateway
# restart. Omit `remote` to run the pinned, loopback-only Docker sidecar.
routing:
enabled: false
version: "0.3.0" # the only tested managed-sidecar contract
port: 8080
algorithm: static
# remote: {endpoint: https://router.example.com} # sends prompt content
models:
- name: fast # classifier alias; unique within this catalog
provider: openai
model: gpt-5.4-mini
base_url: https://api.openai.com
api_key_env: OPENAI_API_KEY
capabilities: [general]
signals:
keywords:
- name: code-request
keywords: [debug, implement, refactor]
operator: OR
decisions:
- name: code
priority: 100
conditions: [{type: keyword, name: code-request}]
model_refs: [fast]
- name: default # an unconditional decision is the fallback
priority: 1
model_refs: [fast]
guardrail:
enabled: true
connector: claudecode # actively enforced connector
mode: action # observe | action (default observe)
scanner_mode: local # local | remote | both (default both)
rule_pack: default # default | strict | permissive, or a guardrail.custom_packs name (guardrail use-pack)
custom_packs: {} # pack directories pinned by digest; `guardrail use-pack` adds an entry, for example:
# acme-hardened: # select it with rule_pack: acme-hardened
# path: /etc/acme/defenseclaw/packs/acme-hardened
# digest: sha256:<64 hex digits of the pack files>
rules: # layered on the selected pack in memory; no files are written
protections: [] # built-in use-case packs, for example database-destruction-protection
enable: [] # rule IDs, as the pack spells them (SEC-AWS-KEY, exec.remote_ip_download_execute_same_artifact)
disable: []
severity_overrides: {} # RULE-ID: CRITICAL | HIGH | MEDIUM | LOW (any case)
suppressions: [] # {id, finding_pattern, entity_pattern, reason}
sensitive_tools: [] # {name, result_inspection, judge_result, min_entities_for_alert}
block_at: "" # CRITICAL | HIGH | MEDIUM | LOW; empty -> the rule pack's level
alert_at: "" # same values; never above block_at
cisco_trust_level: full # full | advisory | none: how far a Cisco AI Defense verdict can escalate
port: 4000 # guardrail proxy port
block_message: "" # custom; empty -> default
detection_strategy: regex_judge # default; regex_only | regex_judge | judge_first
detection_strategy_prompt: "" # per-lane override; empty -> detection_strategy
detection_strategy_completion: regex_only # default for tool results and completions; regex_judge also sends them to the judge
detection_strategy_tool_call: "" # per-lane override; empty -> detection_strategy
# judge.llm omitted: the judge inherits the top-level llm block.
judge:
enabled: false
model: anthropic/claude-sonnet-4-6
api_base: ""
api_key_env: DEFENSECLAW_LLM_KEY
llm: {} # same shape as top-level `llm:` above
trace: false # log judge prompts and responses (debugging); refused on a managed device
hilt:
enabled: false
min_severity: HIGH # CRITICAL, HIGH, MEDIUM or LOW, any case (empty: HIGH)
# Multi-connector overlay: each key is a hook connector carrying a subset of
# the guardrail knobs above; unset fields inherit guardrail.*. Proxy
# connectors (openclaw, zeptoclaw) cannot appear here. Managed by
# `defenseclaw setup <connector>` and `guardrail ... --connector X`.
connectors:
codex:
enabled: true # pointer field: omit = inherit (enabled); false = explicitly off
mode: action # observe | action; inherits guardrail.mode when unset
hook_fail_mode: closed # open | closed; inherits guardrail.hook_fail_mode
block_message: "" # custom; inherits guardrail.block_message
rule_pack: strict # inherits guardrail.rule_pack
block_at: HIGH # inherits guardrail.block_at, then the rule pack's level
hilt:
enabled: true
min_severity: HIGH
claudecode:
mode: observe # only logs; everything else inherits the global default
# Identity-based profiles (see Guardrail profiles below); the strictest applies.
profiles:
contractors:
mode: action
block_at: MEDIUM
hilt: {enabled: true, min_severity: HIGH}
profile_assignments: # the strictest applies; keys AND, values OR
- profile: contractors
match: {groups: ["contractors@corp.example.com"]} # or "CORP\\Contractors" on Windows
default_profile: "" # "" keeps the guardrail.* settings above
ai_discovery:
ide_inventory: all # all | ai_only | off
include_user_principal: false
signature_packs: [] # pack files to load; only listed packs load (see the table below)
trusted_ad_child_domains: [] # child AD domains whose users are verified on Linux
# What happens to a skill, MCP server or plugin by scan severity.
admission:
defaults: {} # scan_on_install, allow_list_bypass_scan, actions, scanner_overrides, first_party_allow_list
skill: {} # per-type overrides of the same keys
mcp: {}
plugin: {}
# The only block and allow list. `defenseclaw skill|mcp|plugin|tool block` writes here.
asset_policy:
skill: {denied: [], allowed: []}
mcp: {denied: [], allowed: []}
plugin: {denied: [], allowed: []}
tool: {denied: [], allowed: []}
# Scanner model (see Scanners below).
scanners:
skill_scanner:
policy: quiet # quiet | strict | balanced | permissive | low-noise | custom
fail_on_severity: HIGH # the blocking gate
review_queue_min: MEDIUM # the warn band starts here
mcp_scanner:
analyzers: [] # [] = automatic
# Custom LLM providers; custom-providers.json is derived from this block.
llm_providers:
custom: []
ollama_ports: []
update:
check: true # the once-a-day "new release available" notice
channel: stable # the only channel
source: "" # "" = the official GitHub releases, else an https mirror
# Notifier webhooks remain separate from telemetry routing.
webhooks:
- name: oncall-slack
type: slack
enabled: true
url: https://hooks.slack.com/services/T000/B000/XXX
# secret_env: WEBHOOK_HMAC_KEY # optional HMAC key variable, for type: generic
min_severity: HIGHOther top-level keys
Defaults from the loader. Omitted keys take these values.
| Key | Default | What it does |
|---|---|---|
data_dir | ~/.defenseclaw | The data directory. DEFENSECLAW_HOME relocates it. Restart required. defenseclaw config set data_dir seeds the rule packs and Rego policies under the new directory (packs already there are kept), and the CLI resolves the omitted paths below under it as the gateway does. |
observability.local.path, observability.local.judge_bodies_path | <data_dir>/audit.db, <data_dir>/judge_bodies.db | The audit store and the retained judge bodies. The 0.8.x top-level audit_db and judge_bodies_db keys are refused; defenseclaw migrate moves them here. |
quarantine_dir, plugin_dir, policy_dir | <data_dir>/quarantine, plugins, policies | Quarantined files, connector plugins, policy assets. |
environment | detected (macos, windows, linux, ...) | Stamped on every record. Restart required. |
tenant_id, workspace_id, discovery_source | empty | Identity stamped on every record. Restart required. |
deployment_mode | empty | managed_enterprise on a managed device. Restart required. |
claw.mode | openclaw | The primary connector. With several active it names the first; the OTel attribute defenseclaw.claw.mode is set only while a single connector is active. |
claw.home_dir, claw.config_file | ~/.openclaw, ~/.openclaw/openclaw.json | Where the OpenClaw install is looked up. |
claw.workspace_dir | empty | Set by setup <connector> --workspace or config set; scopes hooks to one folder, and setup without --workspace keeps it (Per-connector files). |
gateway.host, gateway.port | 127.0.0.1, 18789 | The upstream agent gateway (OpenClaw and ZeptoClaw fleet link). |
gateway.fleet_mode | auto | auto, enabled or disabled: when to dial host:port (OpenClaw fleet link). |
gateway.token_env | DEFENSECLAW_GATEWAY_TOKEN | The variable that holds the sidecar API token (Keys). |
gateway.api_port, gateway.api_bind | 18970, empty | The sidecar REST API. Empty api_bind binds 127.0.0.1 (Gateway API). |
gateway.device_key_file | <data_dir>/device.key | The device key. |
gateway.auto_approve_safe | false | Auto-approve safe requests from the upstream gateway. |
gateway.reconnect_ms, gateway.max_reconnect_ms | 800, 15000 | Reconnect backoff to the upstream gateway. |
gateway.approval_timeout_s | 30 | Seconds to wait for an approval. |
gateway.watchdog.enabled, .interval, .debounce | true, 30, 2 | The health watchdog: poll interval in seconds and consecutive failures before an alert. |
gateway.watcher.* | on | The install watcher for new skills, plugins and MCP servers; take_action: false alerts only. |
watch.debounce_ms, watch.auto_block | 500, true | Debounce for file events, and whether a rejected install is blocked. |
watch.rescan_enabled, watch.rescan_interval_min, watch.rescan_content_gated | true, 60, true | Periodic rescan of installed assets; content gating skips a target whose content did not change. |
llm.timeout, llm.max_retries | 30, 2 | Seconds and retries for the unified LLM block. |
decision_model.enabled | false | The decision model for tool calls: in front of the LLM judge where the judge runs. Needs decision_model.base_url and .model; the token is in DEFENSECLAW_DECISION_MODEL_KEY (.api_key_env), or .credential on a managed device. |
decision_model.hook_connectors | empty | Connectors (or *) whose tool calls the decision model answers on its own where the LLM judge does not run: rules, then the decision model, no judge. Empty keeps it in front of the judge only. Hot reload. |
decision_model.timeout, .allow_threshold, .block_threshold, .on_confident_block | 1, 0.30, 0.75, escalate | Seconds per call; risk at or below which an allow is confident; risk at or above which a block answer is confident; whether the judge still checks a confident block (with the judge only). Hot reload. |
cisco_ai_defense.endpoint | https://us.api.inspect.aidefense.security.cisco.com | The AI Defense inspection endpoint. |
cisco_ai_defense.api_key_env, .timeout_ms | CISCO_AI_DEFENSE_API_KEY, 3000 | The key variable, and the request timeout. |
notifications.enabled | true on macOS and native Windows, else false | Desktop notifications master switch (defenseclaw setup notifications). |
notifications.block_enforced, .hitl_approval | true | Notify on a real block, and on a pending approval. |
notifications.block_would_block | false | Also notify when observe mode would have blocked. |
notifications.sources.hook, .guardrail, .asset_policy | true | Per-source switches. |
notifications.dedup_window, .max_per_minute | 30 seconds, 12 | Duplicate suppression and rate cap. |
guardrail.stream_buffer_bytes | 1024 | Buffer for streamed proxy responses. |
guardrail.judge.timeout, .adjudication_timeout | 30, 5 | Seconds for a judge call, and for adjudication. |
guardrail.judge.max_parallel | Automatic | Most judge calls sent to the judge model at once. Unset uses 1 for loopback/private endpoints and no limit for public endpoints; explicit 0 means no limit. With a limit, tool-call judging goes first. See A judge on a local model. |
guardrail.judge.extra_body | empty | Additional JSON fields for a judge using an OpenAI-compatible endpoint. Judge-owned request fields and authentication keys are refused when the config loads. See Lemonade and Gemma 4. |
guardrail.judge.injection, .pii, .pii_prompt, .pii_completion, .tool_injection, .exfil | true | Which judge categories run when the judge is enabled. |
guardrail.judge_sweep | true | Run the full judge on content the regex triage found no signal in. |
guardrail.retain_judge_bodies, .judge_persist_queue_depth | true, 1024 | Keep raw judge bodies in judge_bodies.db, and the async write queue depth. Restart required. |
guardrail.hook_self_heal, .hook_self_heal_debounce_ms | true, 500 | Re-install a deleted DefenseClaw hook block while the gateway runs. Restart required. |
guardrail.chains.root_scope | false | Managed devices: also evaluate tool-call chains across the sessions of one root_session_id a trusted connector sends. No effect on a per-user install. 1.0.6 and later. |
guardrail.protected_files.on_change, .paths | alert, built-in list | The protected-file watch: alert on an agent's change to SSH authorized keys, shell startup files and autostart entries; restore (opt-in) puts the content back; off turns it off. Restart required. |
When gateway.api_bind is empty the sidecar uses 127.0.0.1 (bind address). The openshell: block is under OpenShell sandbox settings.
Cisco AI Defense API-key rule selection
For an API-key inspection sent to /api/v1/inspect/chat, an unset, null or empty cisco_ai_defense.enabled_rules sends no config or enabled_rules, and the AI Defense connection's own policy applies. A nonempty list sends only the named cloud rules, in the configured order.
Guardrail profiles and identity keys
| Key | Default | Meaning |
|---|---|---|
guardrail.profiles.<name> | none | A named set of guardrail overrides. <name> is lower case, at most 64 characters. Allowed keys: description, mode, block_at, alert_at, hilt, rule_pack, block_message and connectors. Each connectors.<connector> entry allows mode, hilt, block_message, rule_pack, block_at and alert_at. enabled and hook_fail_mode are rejected at both levels. |
guardrail.profile_assignments | [] | Ordered list of {profile, match}. match takes groups, users, connectors and agents; at least one is required. Keys combine with AND, values of one key with OR. When several assignments match, the profile that covers the others, or their strictest combination, applies. agents entries are agt- followed by 16 hex digits. At most 4,096 assignments fit the schema; the whole config also has a 65,536 YAML node limit. |
guardrail.default_profile | "" | The profile for subjects no assignment matches. Empty keeps the guardrail.* settings. |
ai_discovery.ide_inventory | all | IDE extension and plugin inventory scope: all, ai_only or off. See IDE plugin inventory. |
ai_discovery.include_user_principal | false | Send the user's directory principal and Kerberos principal on every record that carries identity (hook decisions, tool activity, agent, model and tool spans, identity.observed). Off, records keep the domain, directory, assurance, session kind and client address but no principal. |
ai_discovery.signature_packs | [] | Signature pack files to load. Since config_version: 9 only listed packs load; the migration lists and pins the packs it finds in <data_dir>/signature-packs/. |
ai_discovery.signature_pack_digests | {} | The sha256 of each pack file, keyed by its path. A pack with a digest loads only when it matches; on a managed standalone device a pack without one does not load, and an apply (ensure) refuses a config whose pack file does not match its digest or has none. |
ai_discovery.trusted_ad_child_domains | [] | Child domains of the joined Active Directory realm whose SSSD accounts are verified on Linux (emea.corp.example.com). An account of a child domain that is not listed gets no domain, realm, directory or principal, so no users assignment matches it. Empty trusts the joined domain only. See Child domains of the joined realm. |
Within a profile, the precedence for one connector is the profile's
connectors.<connector> entry, then the profile field, then
guardrail.connectors.<connector>, then the application protection overlay,
then the global guardrail.* value. For block_at and alert_at the chain ends
with the rule pack's default, and they take CRITICAL, HIGH, MEDIUM
or LOW. A profile mode is observe or action. Profile names are lower
case letters, digits, - and _. Only verified users and groups select a
profile, and the Secure Client profile rejects all three guardrail keys.
defenseclaw config validate reports an unknown profile name, an empty
match, a malformed agent identity and a forbidden key. See
User- and group-based policies for
examples, the match reasons and auditing, and
Identity and authentication
for the two privacy keys.
Rule packs, rules and thresholds
These keys are allowed at the global level, in guardrail.connectors.<connector>,
in guardrail.profiles.<profile> and in a profile's connector entries. The
concept pages explain how they combine: Rules and
Thresholds.
| Key | Default | Meaning |
|---|---|---|
guardrail.rule_pack | default | The rule pack: default, strict, permissive, or a name from guardrail.custom_packs. Lower case letters, digits, _ and -, up to 64 characters. defenseclaw guardrail use-pack NAME writes it. |
guardrail.custom_packs.<name> | none | A rule-pack directory pinned by digest: path and digest (sha256: plus 64 hex digits, printed by defenseclaw guardrail validate-pack). If the directory no longer hashes to the digest, the change does not build into a generation and the previous policy keeps running. At most 64 packs. |
guardrail.rules.protections | [] | Built-in use-case packs layered on the selected pack, such as database-destruction-protection. defenseclaw guardrail protection list shows them. |
guardrail.rules.enable, guardrail.rules.disable | [] | Rule IDs to switch on or off, spelled and cased exactly as the pack has them (SEC-AWS-KEY, exec.remote_ip_download_execute_same_artifact). An unknown ID fails validation. |
guardrail.rules.severity_overrides | {} | Rule ID to CRITICAL, HIGH, MEDIUM or LOW, in any case, the values block_at takes. Rules have no INFO severity. |
guardrail.rules.suppressions | [] | {id, finding_pattern, entity_pattern, reason} entries appended to the pack's suppressions. IDs are unique across the pack and the config. |
guardrail.rules.sensitive_tools | [] | {name, result_inspection, judge_result, min_entities_for_alert} entries merged into the pack's sensitive tools by name. |
guardrail.block_at, guardrail.alert_at | empty | The lowest severity that blocks or alerts: CRITICAL, HIGH, MEDIUM or LOW, in any case. Empty inherits: a connector from the global value, the global value from the rule pack's default. alert_at is never above block_at. defenseclaw guardrail block-at LEVEL [--connector X] writes them. |
guardrail.cisco_trust_level | full | How much a Cisco AI Defense verdict counts. full: as much as a local finding. advisory: a verdict that only Cisco AI Defense reached is downgraded to an alert, never a block. none: Cisco AI Defense results are ignored when choosing the action. |
guardrail.internal_domains | [] | Your organization's own domains, such as corp.example.com. A download from a host that is one of them or under one does not start the download → execute alert. Domain names only: no scheme, port, path, wildcard or IP address. At most 256. |
guardrail.judge.trace | false | Log the judge's prompts and responses for debugging. They can hold agent traffic and secrets. It replaces DEFENSECLAW_JUDGE_TRACE, and a managed device refuses it. |
block_at and alert_at are the only threshold source. They apply to hook
tool calls, hook prompts, and proxy prompts, completions and tool calls alike.
Precedence, most specific first: the profile's connector entry, the profile,
guardrail.connectors.<connector>, the application protection overlay, the
global value, and then the rule pack's default (its manifest posture). Ask
for the value in force and where it comes from:
defenseclaw config get guardrail.block_at --effective(source: config:guardrail.block_at)
HIGHThe source line comes first and goes to standard error, so $(...) or a pipe
gets only the value. When nothing sets the threshold, the same command prints
the pack's level and names the pack, for example
(source: pack-default:default).
Admission
admission decides what happens to a skill, MCP server or plugin by scan
severity. admission.defaults applies to every type; admission.skill,
admission.mcp and admission.plugin override it field by field. There is no
admission.tool: a tool is only blocked or allowed by name, in asset_policy.
The policy page explains the actions and the matching rules:
Admission.
| Key | Default | Meaning |
|---|---|---|
admission.<type>.scan_on_install | true | Scan a new asset when it is installed. |
admission.<type>.allow_list_bypass_scan | true | An asset on the allow list skips the scan. false scans it anyway. |
admission.<type>.actions.<severity> | see below | One entry per severity: critical, high, medium, low, info. A shorthand (block, quarantine, warn, allow) or the exact triple {install, file, runtime}. |
admission.<type>.scanner_overrides.<scanner> | {} | The same severity map for the findings of one scanner, keyed by its name (skill-scanner, mcp-scanner, plugin-scanner, codeguard, and the ClawShield names). VirusTotal and the other analyzers run inside the skill scanner, so they use the skill-scanner key. At most 32 scanners. |
admission.<type>.first_party_allow_list | built in | Assets that count as first party: {name, source_path_contains, reason}, matched when the name is equal and the path contains one of the entries as whole path components. Unset inherits; an empty list clears it. |
The shorthands are block (do not install, runtime disable), quarantine
(do not install, quarantine the files, runtime disable), and warn and allow
(install, runtime enabled; they differ only in the verdict).
Each severity resolves in this order, first match wins: admission.<type>,
for skills the scanner gate (scanners.skill_scanner.fail_on_severity and
review_queue_min), admission.defaults, and the built-in policy. The
built-in policy quarantines critical and high, warns on medium, low and
info, except that balanced MCP servers warn on high, medium and low as
well. Secure Client keeps its separate admission actions. The built-in first-party lists name the codeguard skill and the
defenseclaw plugin. A severity nothing covers fails closed.
Block and allow lists
asset_policy is the only block and allow list. defenseclaw skill block,
mcp block, plugin block, tool block and their allow and unblock
partners write asset_policy.<type>.denied and allowed through the config
writer, and the running gateway applies the change without a restart. On a
managed standalone device those commands are refused: add the entry to
asset_policy in the admin config. Quarantine, restore, disable and enable are
runtime state, not entries here.
| Key | Default | Meaning |
|---|---|---|
asset_policy.skill.denied, allowed | [] | Entries {name, connector, reason, source_path_contains}. An empty connector covers every connector. |
asset_policy.mcp.denied, allowed, asset_policy.plugin.denied, allowed | [] | The same entries, plus the matchers url, command, args_prefix and transport for MCP servers. |
asset_policy.tool.denied, allowed | [] | {name, connector, reason}. A tool is matched by name (and connector) when an agent calls it. |
The other asset_policy keys (enabled, mode, default, registry,
registry_required, registry_empty_action and runtime_detection) govern
deny-by-default and approved-catalog rules, not the explicit lists. They are
described in Admission and
Registries.
Scanners
The skill scanner and MCP scanner settings live under scanners (Scanners).
| Key | Default | Meaning |
|---|---|---|
scanners.skill_scanner.policy | quiet | The scan policy preset: quiet, strict, balanced, permissive, low-noise, or custom. |
scanners.skill_scanner.policy_file | none | {path, digest} of your policy file, pinned by digest. Used only with policy: custom and required there. |
scanners.skill_scanner.use_llm | true | The LLM analyzer. |
scanners.skill_scanner.use_behavioral, enable_meta, use_trigger | false | The behavioral, meta and trigger analyzers. |
scanners.skill_scanner.lenient | true | Tolerate malformed skills instead of failing them. |
scanners.skill_scanner.llm_consensus_runs | 0 | Run the LLM analysis this many times and combine the results (up to 1000). 0 leaves the SDK default of one run in place; use_llm: false disables LLM analysis. |
scanners.skill_scanner.judge_source | inherit | inherit uses the top-level llm: block. override uses the scanner's own llm: block, which then needs llm.model. An unset value with a populated llm: block counts as override. |
scanners.skill_scanner.fail_on_severity | HIGH | The blocking gate DefenseClaw applies to the scanner's findings (CRITICAL, HIGH, MEDIUM, LOW or INFO). It is never passed to the scanner itself. Skill admission actions derive from it. |
scanners.skill_scanner.review_queue_min | MEDIUM | The review (warn) band starts here. It must not be above fail_on_severity. |
scanners.skill_scanner.analyzers.virustotal | off | {enabled, api_key_env, upload_files}. The key is read from the variable api_key_env names (VIRUSTOTAL_API_KEY when empty), never from config.yaml. |
scanners.skill_scanner.analyzers.aidefense.enabled, analyzers.osv.enabled | false | Cisco AI Defense and OSV dependency checks. |
scanners.skill_scanner.timeouts.scan_s | 300 | Seconds one skill scan the gateway starts may run: the install watcher and its rescans, the REST scan endpoint and the scans an agent hook starts. 0 uses the default. defenseclaw skill scan --remote uses the gateway REST endpoint and this timeout; defenseclaw skill scan without --remote has no scan time limit. |
scanners.mcp_scanner.analyzers | [] | A list of api, yara, llm, behavioral and readiness. [] is automatic: YARA, plus the LLM analyzer when its model and key are ready. |
scanners.mcp_scanner.scan_prompts, scan_resources, scan_instructions | false | Also scan prompts, resources or server instructions. |
scanners.mcp_scanner.judge_source, llm | inherit | As for the skill scanner. |
scanners.mcp_scanner.unverified_server | warn | What defenseclaw mcp set and the gateway's install admission do with a server they could not verify: its scan did not finish (a timeout, an unresolved hostname, a launcher that exited, an unreachable URL), or an OpenCode command is outside the trusted install prefixes. warn adds or keeps it with a warning and an audit record, and the gateway scans it again later. block refuses it, and the gateway blocks and disables it (the strict setting). Unset is warn on managed standalone and per-user hosts. Secure Client uses its separate closed admission. Completed HIGH scanner findings follow admission.mcp.actions.high: balanced warns and audits; quarantine refuses under an explicit strict setting. CRITICAL still refuses by default. |
scanners.mcp_scanner.yara | bundled rules | include_bundled (default true) and extra_rules, a list of {path, digest} files pinned by digest. A scan loads a file only when it matches its digest; a config whose pin does not match is refused when it is applied, and the gateway rejects a reload while a file does not match. |
defenseclaw setup skill-scanner and setup mcp-scanner write these keys. A scanner policy file and extra YARA rules are pinned by digest, so a changed file never takes effect silently.
Updates
| Key | Default | Meaning |
|---|---|---|
update.check | true | The once-a-day "new release available" notice in the CLI and TUI. Never shown in scripts, JSON output or CI. DEFENSECLAW_NO_UPDATE_CHECK=1 also turns it off. |
update.channel | stable | The only channel. |
update.source | empty | Where release files are downloaded from: empty for the official GitHub releases, otherwise an https:// base URL that serves the same release layout. It changes only where bytes come from. The signature check always uses the release identity compiled into DefenseClaw, so a mirror must serve the same signed checksums.txt and bundle. DEFENSECLAW_REPO is a deprecated alias. |
A managed device does not self-update. Mirror setup is on Upgrade.
Removed in version 9
A config_version: 9 file that holds a key the schema retired fails validation. The retired keys and their replacements are listed in Migrate to config version 9.
OpenClaw fleet link
The gateway dials the OpenClaw or ZeptoClaw gateway at gateway.host and gateway.port only when there is one to reach. gateway.fleet_mode: enabled always dials and disabled never does. With auto, the default:
- the
openclawandzeptoclawconnectors dial; codexandclaudecodedial only whengateway.hostis not loopback;- every other connector, and an install with no connector, does not dial.
claw.mode defaults to openclaw for older configs, so an install that never picked a connector names OpenClaw without having it. When only that default names OpenClaw (guardrail.connector and guardrail.connectors are empty) and OpenClaw is not installed, the gateway and CLI resolve no agent connector; with a loopback gateway.host and fleet_mode unset or auto, the gateway does not dial. OpenClaw counts as installed when an openclaw.json exists at claw.config_file or in claw.home_dir, or an openclaw binary is on PATH or in /usr/local/bin, /opt/homebrew/bin, ~/.npm-global/bin or ~/.local/bin. Then defenseclaw-gateway status shows the Gateway subsystem DISABLED with OpenClaw gateway off (OpenClaw is not installed), doctor reports OpenClaw gateway: off (OpenClaw is not installed), the TUI and Mac app show the same text, and OPENCLAW_GATEWAY_TOKEN is not required. The gateway checks at start: restart it after installing OpenClaw, or set fleet_mode: enabled.
When guardrail.connectors lists agents, the active connector comes from that roster. An older claw.mode default does not add OpenClaw to it.
Routing and observability behavior
The routing block affects OpenClaw and ZeptoClaw only on the proxy's OpenAI-compatible Chat Completions path. defenseclaw keys list discovers each non-empty api_key_env; the classifier never receives the key value. See Semantic routing.
Omissions compile to an explicit effective policy; inspect it with defenseclaw config show --effective --section observability and defenseclaw observability plan. Destination kinds, buckets, routes and redaction are on Observability.
- With
observability: {}, all 14 buckets collect logs, traces and metrics, local SQLite stores all collected logs unredacted, and no remote destination exists. - An enabled destination without
sendorroutestakes every bucket, every signal it supports, and profilenone. A logs-only kind sends all logs; a general OTLP kind sends logs, traces and metrics. The Galileo preset generates one traces-onlycapability-defaultroute restricted to its available family membership. - An explicit
sendorroutesblock replaces the generated route. A selected nonmember of the Galileo family is rejected asunsupported_shapeand reported through destination failure accounting. - Destinations are independent fan-out legs; one failing does not stop another. For advanced routes the first matching route wins per destination and signal, and an unmatched record is not delivered. Selectors AND across fields and OR within one:
buckets,sources,connectors,actions,event_names,min_severity. Collection happens first, so routing cannot recreate a disabled signal. - Exactly one generated local SQLite destination is mandatory. It is configured only through
observability.local, cannot be disabled or filtered, and keepsretention_days(default 7;0retains forever and warns about capacity). The same window bounds AI discovery history in<data_dir>/inventory.db.max_store_mb(default0, off) is an opt-in size cap foraudit.dbin MiB, 64 or more.
Destination transport and queue limits
| Limit | Value |
|---|---|
| Destinations | at most 64, names unique after canonical normalization |
Advanced routes per destination | at most 256 |
| Queue (queue-backed destinations) | default 2,048 records and 67,108,864 bytes; bounds 1..65536 records and 4198400..268435456 bytes. JSONL and console accept only these queue fields |
| Batch (Splunk HEC, HTTP JSONL, OTLP) | default at most 512 records and 8,388,608 encoded bytes, 5,000 ms delay, 10,000 ms attempt timeout. Count 1..8192 and not above queue count; bytes 4263936..67108864; delay 1..600000 ms. Galileo's omitted delay is 1,000 ms. Prometheus is pull-based and rejects batch |
When a queue overflows, the newest enqueue is dropped; older work, the mandatory SQLite store and sibling destinations stay intact. Transient or ambiguous acknowledgements retry the same immutable projection and record ID, so remote delivery is not exactly once.
Config reload mode
gateway.config_reload.mode controls what happens after a valid change:
| Mode | Behavior |
|---|---|
hot | Default. Reload, validate, diff and reconcile in the running gateway. |
restart | Validate first, then use a fresh gateway process only for edits that cross a restart boundary (listener, topology, storage). Hot-reloadable fields, observability destinations included, still reconcile in process. A daemon launches defenseclaw-gateway restart; a service-supervised foreground run exits cleanly for its supervisor. Changing only this mode does not restart. |
In hot mode a change to a restart-required key is not rejected: the gateway keeps that key's running value, logs [config] restart the gateway to apply <key>; the rest of the change applies now, and applies everything else. The storage paths (data_dir, observability.local.path, observability.local.judge_bodies_path) and deployment_mode cannot be kept that way: the gateway refuses that reload, and every later one, until it restarts. /health shows last_reload_error, and an /enforce write answers applied: false. Changing gateway.config_reload.mode itself needs a restart.
The LLM block, regional Bedrock, Vertex and Azure backends and how doctor validates them are on LLM providers.
OpenShell sandbox settings
The openshell: block configures NVIDIA OpenShell 0.1 sandboxes, the defenseclaw sandbox commands. You rarely edit it by hand: sandbox setup writes enabled, harnesses and upstream_telemetry, sandbox enable and disable keep wrappers in step with your shell rc files, sandbox policy allow and block edit the egress lists, and "always" answers are saved to egress.unblocked or egress.block. Pack contents, layering and admin limits are on Sandbox policy.
Where sandboxes run
Sandboxes run on Linux and on Apple-silicon Macs, with the DefenseClaw and OpenShell gateways running as your own user. On a Mac they are OpenShell MicroVMs that mount no host folders, so openshell.workdir.mode is always copy there. A standalone managed_enterprise install runs them for each signed-in person under the policy in openshell.admin and each guardrail profile (Sandboxes on managed computers). On Windows, an Intel Mac and a Secure Client profile /health reports the sandbox subsystem as disabled.
The selected sandbox policy pack supplies every default, the keys below override it, sandbox run options override those, and openshell.admin clamps the result. Keys the pack governs have no loader default, so an unset key follows the pack: profile, yolo, workdir.mode, workdir.max_upload_mb, egress.ports, egress.large_upload_mb, egress.block_large_uploads, egress.feed and mcp.import. The mask, unmask, block and allow lists add to the pack's lists. Some settings exist only in a pack: the approvals mode, the review list, mcp.blocked_tools, mcp.project_servers, hooks.on_tamper, and hooks.on_silence with hooks.silence_after.
openshell:
enabled: false # true starts the sandbox runtime; sandbox setup sets it
binary: openshell # the upstream openshell CLI
gateway:
name: "" # OpenShell gateway registration; "" = the active one
workspace: "" # OpenShell workspace; "" = default
ingress_port: 0 # sandbox hook ingress; 0 = gateway.api_port + 1
egress_port: 0 # DefenseClaw egress proxy; 0 = gateway.api_port + 2
pack: "" # "" = open; a built-in, a name under pack_dir, or an absolute path
pack_dir: ~/.defenseclaw/policies/sandbox # default <data_dir>/policies/sandbox; managed standalone: <policy_dir>/sandbox
profile: "" # "" follows the pack; open | balanced | strict
yolo: null # null follows the pack; true | false
llm: auto # model credential a run shares; see below
keep_headless: false # true keeps a --prompt run's sandbox
trusted_ca_bundle: "" # PEM file of CAs sandboxes also trust (a TLS-inspecting proxy's root)
workdir:
mode: "" # "" follows the pack; mount | copy
masks: [] # secret-file globs added to the pack's masks
unmask: [] # project globs that stay visible despite a mask
max_upload_mb: 0 # copy-mode size limit; 0 follows the pack
git_depth: 200 # history depth of the copy-mode clone
on_exit: ask # ask | keep | undo
undo_ignored:
enabled: false # true: undo restores these directories (Linux mount mode)
max_mb: 500 # cap on one undo point's copies, in MiB
dirs: [node_modules, .venv, venv]
egress:
block: [] # host patterns added to the pack's block list
allow: [] # host patterns added to the allow list
unblocked: [] # "always" unblocks and approvals the daemon saves
ports: [] # replaces the pack's proxy ports when non-empty
large_upload_mb: 0 # first-seen-host upload alert in MiB; 0 follows the pack
block_large_uploads: false # true also cuts that upload; false follows the pack
feed: "" # "" follows the pack; builtin | none
image:
base: "" # "" = the pinned NVIDIA community base image
harness_versions: {} # harness name -> exact version
approvals:
debounce_ms: 3000 # batch approvals until hooks are quiet this long
agent_proposals: null # null = true
resources:
cpu: "" # "" = unlimited
memory: "" # "" = unlimited
harnesses: [] # harnesses set up for sandboxes
wrappers: [] # harnesses with the shell wrapper
mcp:
import: null # null follows the pack
host_ports: [] # host ports opened for host-side MCP servers
upstream_telemetry: false # OpenShell's own anonymous usage telemetry
token_delivery: provider # provider | env
admin: {} # administrator limits; see belowSandbox keys
| Key | Default | Values and rules |
|---|---|---|
enabled | false | The sandbox switch. true starts the sandbox runtime with the API: the hook ingress and egress proxy listeners and the sandbox manager behind the sandbox API. It also turns on the port checks under Validation and reload, and a change restarts the API listener. sandbox setup sets it to true, and sandbox teardown to false. |
binary | openshell | The upstream openshell CLI, used for terminal attach, command runs, file transfer, and provider profile imports. A command name looked up on PATH, or an absolute path. A relative path with a separator, such as bin/openshell or ./openshell, is refused: it would run from the project folder. |
gateway.name | "" | The local OpenShell gateway registration. Empty selects the active registration. At most 128 characters. |
gateway.workspace | "" | The OpenShell workspace (tenant). Empty selects default. At most 128 characters. |
ingress_port | 0 | The sandbox hook ingress port, 0–65535. 0 means gateway.api_port + 1 (18971 by default). Its OpenShell provider profile is defenseclaw-ingress-<port>. Sandboxes keep the port their image and policy were built for, so re-create them after a change. |
egress_port | 0 | The egress proxy port, 0–65535. 0 means gateway.api_port + 2 (18972 by default). |
pack | "" | The sandbox policy pack: open, balanced, strict, a custom pack name under pack_dir, or an absolute path (or ~/…) to a pack.yaml or its directory. Empty selects open. |
pack_dir | <data_dir>/policies/sandbox; <policy_dir>/sandbox on a managed standalone install | Where custom packs live, as <name>/pack.yaml. An absolute path or ~/...; empty turns custom pack names off. On a managed standalone install the default is the administrator-owned <policy_dir>/sandbox that ensure and verify check (see Packs). |
profile | "" | open, balanced, or strict. Empty follows the pack's network mode. |
yolo | null | Skip-permissions mode for the harness. null follows the pack. |
keep_headless | false | true keeps the sandbox a headless sandbox run creates (--prompt, or the harness's print mode, such as the shell wrapper's claude -p), as --keep does for one run. By default it is deleted when the run ends and nothing is left in it to bring back or undo, by the rules of --rm. |
llm | auto | The model credential a run shares with its sandbox: auto (the first key found for the harness, an Amazon Bedrock key last), none, anthropic, claude-oauth, openai, bedrock, or gemini. It is the default of sandbox run --llm, so the runs the shell wrappers, the TUI and the macOS app start take it too; --llm overrides it for one run. A provider the harness has no profile for falls back to auto; one whose key is not set refuses the run. |
workdir.mode | "" | mount (live bind mount) or copy. Empty follows the pack. |
workdir.masks | [] | Project globs of secret files, added to the pack's masks. |
workdir.unmask | [] | Project globs that stay visible even though a mask covers them, added to the pack's own unmask list. |
workdir.max_upload_mb | 0 | Copy-mode size limit in MiB, 0–1048576. 0 follows the pack. |
workdir.git_depth | 200 | History depth of the copy-mode clone, 0–1000000. 0 uses 200. |
workdir.undo_ignored.enabled | false | Whether a mounted project's undo point keeps a copy of the directories in workdir.undo_ignored.dirs that git ignores (in a folder without git, the dependency directories its snapshot skips), so sandbox undo restores them as the session found them. Copies are file clones where the filesystem supports them (btrfs, XFS) and byte copies otherwise (ext4). It applies from the next session's start, on Linux in mount mode; copy mode, every sandbox on a Mac, has no undo point. |
workdir.undo_ignored.max_mb | 500 | The cap on one undo point's copies in MiB, 0–1048576; 0 means 500. A directory whose copy would pass it keeps none, and undo reports it as before. |
workdir.undo_ignored.dirs | [node_modules, .venv, venv] | Directory names kept, matched at any depth: one path segment, not .git, up to 64 names. Empty means the default. |
workdir.on_exit | ask | What happens to a mounted project's changes when a session ends: ask, keep, or undo. Without a terminal, or with --yes, ask keeps them. |
egress.block | [] | Host patterns added to the pack's block list. An unblock can't lift an entry; remove it to reach the host. A "reject always" answer to an ask adds its hosts here. |
egress.allow | [] | Host patterns added to the allow list. An entry exempts the host from the blocklist feed, and one that names a private host (an exact name, an intranet wildcard such as *.corp, or an address) opens it. Under strict, a direct connection to an entry is approved without asking. Entries that cover every host or a whole top-level domain are ignored, and all entries are ignored when admin.allow_unblock is false. |
egress.unblocked | [] | Hosts the daemon saves when you choose "always" for an unblock or an approval. Validated like egress.allow, and ignored when admin.allow_unblock is false. Unlike egress.allow, an entry here lifts only blocklist-feed and allowlist refusals: it never opens a private address the name resolves to. |
egress.ports | [] | Destination ports for the egress proxy, 1–65535, unique, at most 64. A non-empty list replaces the pack's ports. |
egress.large_upload_mb | 0 | Report an upload of more than this many MiB to a host the sandbox hasn't contacted before, 0–1048576. 0 follows each sandbox's pack, including a run's --pack. A change reaches running sandboxes on the next reload. |
egress.block_large_uploads | false | true cuts that upload before the chunk that crosses the threshold and refuses the sandbox's later requests to the host (and to other new hosts under its domain or at its address), for every sandbox. The feed shows a ✗ with the threshold, and defenseclaw sandbox unblock lifts the block for a host. Hosts on an allow list you or your administrator wrote, and hosts you unblocked, are only reported. false follows each pack; it cannot turn a pack's block off, and a pack with large_upload_mb: 0 keeps the report off. See Large-upload alert threshold. |
egress.feed | "" | builtin turns the built-in blocklist feed on, none turns the feeds off. Empty follows the pack. |
trusted_ca_bundle | "" | A PEM file of CA certificates that sandboxes trust besides the image's public roots, such as the root of a TLS-inspecting proxy. Every sandbox image built while it is set adds them to its system store, and the sandbox points SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, GIT_SSL_CAINFO, NODE_EXTRA_CA_CERTS and DENO_CERT at OpenShell's CA bundle plus them. It does not cover the agents' model calls, which OpenShell's supervisor makes with its own trust store, so model provider hosts must not be TLS-inspected (Sandbox network). An absolute path or ~/...; on a managed computer an absolute path to an administrator-owned file. At most 64 CA certificates and 1 MiB; a private key or non-CA certificate refuses it and no image is built. A change rebuilds the images at the next run. defenseclaw sandbox doctor reports it in the Sandbox TLS trust row. |
image.base | "" | A bring-your-own base image. The image build refuses a base that isn't pinned by digest (<image>@sha256:<64 hex digits>). Empty selects the pinned NVIDIA OpenShell community base image. |
image.harness_versions | {} | Harness name to exact version, at most 64 entries. The image build refuses a version outside DefenseClaw's reviewed hook contract. |
approvals.debounce_ms | 3000 | 0–600000. How long hooks must be quiet before the sandbox manager applies a batch of approvals: every OpenShell policy reload closes open connections. |
approvals.agent_proposals | null | Whether the agent may submit its own connection requests for triage; false rejects them. null means true. |
resources.cpu | "" | CPU request: cores ("2", "1.5") or millicores ("500m"). Empty means unlimited. sandbox run --cpu overrides it. |
resources.memory | "" | Memory request: bytes with an optional Ki, Mi, Gi, Ti or k, K, M, G, T suffix ("512Mi", "4Gi"). Empty means unlimited. sandbox run --memory overrides it. |
harnesses | [] | The harnesses set up for sandboxes, such as claudecode and codex. sandbox setup writes it, and setup, image build, and doctor default to it (then to Claude Code and Codex). At most 64, unique. |
wrappers | [] | The harnesses whose command runs in a sandbox through the shell wrapper. sandbox enable and disable record it; the wrapper itself lives in your shell rc file. At most 64, unique. |
mcp.import | null | Whether the harness's MCP servers come along. null follows the pack. |
mcp.host_ports | [] | Host ports you agreed to open for MCP servers running on your machine, 1–65535, unique, at most 64. Each port is still checked against the pack and openshell.admin, and DefenseClaw's own listeners are never opened. |
upstream_telemetry | false | Whether OpenShell's own anonymous usage telemetry stays on. sandbox setup turns it off in the OpenShell gateway's environment (OPENSHELL_TELEMETRY_ENABLED=false) unless you keep it (--upstream-telemetry), and records your choice here, on Linux and on a Mac whose gateway the Homebrew service runs. sandbox doctor reports a mismatch, and --fix repairs it. |
token_delivery | provider | How a sandbox receives its hook ingress credential. provider: as an OpenShell provider credential, so the agent only sees a placeholder, rotated on every start. env: as a plain DEFENSECLAW_SANDBOX_TOKEN variable the agent can read, kept for the sandbox's life. Both are revoked when the sandbox is deleted. See Hook ingress. |
For upgrades from 1.0.2–1.0.7, an existing openshell.middleware.enabled entry still loads in 1.0.8 but has no effect. Remove it from config.yaml; config set no longer accepts it. This compatibility allowance ends in 1.1.0.
Host patterns in egress.block, egress.allow, egress.unblocked, admin.egress_block, admin.egress_allow_only and a pack's egress lists are a host name, *.<host> (every subdomain, not the host), an IP address, or a CIDR prefix such as 198.51.100.0/24. Addresses compare by value, so 2001:db8::1, its uncompressed spelling and an IPv4-mapped spelling match one entry. A bare *, schemes, ports, paths, wildcards inside a name, and host names whose last label does not start with a letter (127.1, 0x7f000001) are refused. Matching ignores case and a trailing dot. Only admin.egress_block widens a host name (example.net blocks its subdomains too); every other list matches exactly. Lists hold at most 4096 entries.
Project globs (workdir.masks, workdir.unmask, sandbox run --unmask, a pack's masks) are relative to the project folder with forward slashes. Absolute paths, ~, drive letters, backslashes and .. are refused. Lists hold at most 1024 entries.
Names in harnesses, wrappers, image.harness_versions and admin.allowed_harnesses start with a letter or digit, then letters, digits, ., _ and -, up to 128 characters. An image.harness_versions key cannot contain ..
Built-in packs, custom pack format and loading rules are on Sandbox policy.
Admin keys
openshell.admin holds the administrator's limits. Every key is optional; an unset key adds no limit, and the allow_* switches restrict only when false. Each is explained with examples on Sandbox policy.
openshell:
admin: # every key is optional
required_pack: "" # its profile, yolo, workdir mode, MCP import, feeds and ports are floors
required_pack_digest: "" # sha256:<hex> pins the required pack's content
min_profile: "" # strict > balanced > open
allow_yolo: null # null = no constraint; false forbids
allow_mount: null
allow_host_ports: null
allow_unblock: null # also governs approve-always, user allow entries, turning the feed off
allow_learn_mode: null
allowed_harnesses: [claudecode, codex] # nonempty; leave the key out for no limit
egress_block: [] # always blocked, never unblockable
egress_allow_only: [api.example.com] # nonempty; forces an allowlist profile
block_large_uploads: false # true: every sandbox's large uploads to new hosts are cut
require_copy_for: [] # absolute or ~/ path globs that must run in copy mode
max_resources: {cpu: "", memory: ""}
locked: [] # keys run options may not loosen| Key | Values | Effect |
|---|---|---|
required_pack | Pack reference, like pack | Every run uses this pack, and its profile, skip-permissions default, workspace mode, MCP import, blocklist feed, and proxy ports are floors. |
required_pack_digest | sha256: and 64 lowercase hex digits | Pins the required pack's content: the digest defenseclaw sandbox pack show reports. Needs required_pack. |
min_profile | open, balanced, strict | The loosest profile allowed. |
allow_yolo | true, false, null | false keeps every harness's permission prompts. |
allow_mount | true, false, null | false forces copy mode and refuses every host folder mount. |
allow_host_ports | true, false, null | false refuses every host port. |
allow_unblock | true, false, null | false refuses unblocks and approve-always, ignores saved unblocks and the allow entries of users and of custom packs they chose, and keeps the blocklist feed on. A one-time approval then can't reach a feed-listed or private-network destination. |
allow_learn_mode | true, false, null | false refuses learn mode. |
allowed_harnesses | Harness names, at least one | Only these harnesses may run. Leave the key out for no limit: an empty list is refused. |
egress_block | Host patterns | Always blocked, for every sandbox. Nothing unblocks or approves them. A host name also blocks its subdomains (example.net covers www.example.net). |
egress_allow_only | Host patterns, at least one | Leave the key out for no limit: an empty list is refused. The only hosts any sandbox may reach. Raises the profile to at least balanced. Entries match exactly: list *.<host> for subdomains. |
block_large_uploads | true, false | true turns the large-upload block on for every sandbox (see egress.block_large_uploads) and keeps its report on: a pack's large_upload_mb: 0 gets 25 MiB, and a threshold above 25 MiB (a pack's or egress.large_upload_mb) is lowered to 25 MiB, or to the required pack's own when that is higher. An unblock still lifts it for one host unless allow_unblock is false. |
require_copy_for | Path globs, at most 1024 | Projects that must run in copy mode. |
max_resources.cpu, max_resources.memory | Same formats as resources | Ceilings for every sandbox. |
locked | Up to 16 of pack, profile, yolo, workdir.mode, workdir.unmask, mcp.import, mcp.host_ports, resources | Keys whose configured value run options may not loosen. |
Every loosening openshell.admin refuses is reported as "blocked by your organization's DefenseClaw policy: <key>", and the same limits gate runtime actions such as unblocking a destination or opening a host port. In a managed_enterprise install the admin block is authoritative; elsewhere it is enforced but advisory, because you can edit the file. sandbox policy explain and sandbox doctor say which applies.
Validation and reload
The configuration schema rejects unknown keys in every openshell block. DefenseClaw also
refuses to load a config.yaml whose openshell values break these rules:
ingress_portandegress_portmust differ when both are set;- when
enabledistrue, the effective ingress and egress ports must differ from each other, fromgateway.api_port, and fromguardrail.port. A derived port that would pass 65535 (agateway.api_portof 65534 or higher) must be set explicitly; - enum values, port ranges, host patterns, globs, names, and CPU and memory quantities must be valid, and size and depth values must not be negative;
admin.required_pack_digestmust be a well-formed digest and needsadmin.required_pack, and everyadmin.lockedentry must be a lockable key.
The checks don't open pack files, so a missing or broken custom pack named in
pack or admin.required_pack isn't reported when the config loads.
sandbox policy show reports it, and so does the next sandbox run;
sandbox pack validate checks a pack file on its own.
The gateway reloads the openshell block in place, with either
gateway.config_reload.mode. A change that fails these checks is rejected,
and the running config stays in place. A reload re-resolves the egress policy
of every running sandbox, so changes to the egress keys, the large-upload
threshold included, reach them within seconds.
Turning enabled on or off, or moving ingress_port or
egress_port while enabled is true, restarts the API listener inside the
running gateway.
guardrail.connectors (several connectors)
A single gateway can enforce guardrail policy for several hook connectors at once. Each connector that's active gets a guardrail.connectors.<name> block; the gateway resolves policy per connector and falls back to the global guardrail.* values for anything a block leaves unset.
| Per-connector key | Type | Inherits when unset |
|---|---|---|
enabled | bool pointer — omit = inherit (on); false = explicitly off (drops it from the active set, removes its hooks) | on |
mode | observe | action | guardrail.mode |
hook_fail_mode | open | closed | guardrail.hook_fail_mode |
block_message | string | guardrail.block_message |
rule_pack | a preset (default, strict, permissive) or a guardrail.custom_packs name | guardrail.rule_pack |
block_at | CRITICAL | HIGH | MEDIUM | LOW (any case) — lowest severity that blocks | guardrail.block_at, then the rule pack's level |
alert_at | same values — lowest severity that alerts; never above the block level | guardrail.alert_at, then the rule pack's level |
hilt | { enabled, min_severity } | guardrail.hilt |
With more than one connector active, claw.mode and guardrail.connector keep naming the primary connector (the first in alphabetical order unless setup keeps the existing one), and the gateway leaves the OTel attribute defenseclaw.claw.mode off. Manage these blocks with defenseclaw setup <connector> (choose Add) and defenseclaw guardrail ... --connector X (Multi-connector).
Enterprise settings (enterprise.*)
A managed deployment (deployment_mode: managed_enterprise) reads an
administrator-owned config: /etc/defenseclaw/config.yaml on Linux,
/opt/cisco/defenseclaw/etc/config.yaml on macOS, and
C:\ProgramData\Cisco\DefenseClaw\etc\config.yaml on Windows. The
enterprise block tunes it. The config is rejected if the block appears in a
config whose deployment_mode is not managed_enterprise. In the
secure_client profile, profile is the only key allowed. For explanations
and examples, see the enterprise settings reference.
| Key | Values (default) | OS | Notes |
|---|---|---|---|
enterprise.profile | secure_client | standalone (Windows and macOS: secure_client; Linux: standalone) | all | Linux accepts only standalone |
enterprise.inspection.ai_defense.enabled | bool (false) | all | Adds Cisco AI Defense to the local engine |
enterprise.inspection.ai_defense.credential | credential name | all | Lowercase letters, digits, and dashes; must be valid when AI Defense is enabled. Store the value with enterprise secret set. An inline cisco_ai_defense.api_key is rejected |
enterprise.inspection.llm.credential | credential name | standalone | Names the stored API key of the llm: block for the judge and the scanners. Store the value with enterprise secret set; llm.api_key_env and .env are not read when it is set. Refused under the Secure Client profile |
enterprise.enrollment.mode | auto | manifest (auto) | all | With manifest you publish targets.yaml and the enumerator does nothing. On Windows the first install then needs --manifest (Setup: MANIFEST=) |
enterprise.enrollment.include_users | list | all | Linux and macOS: also enrolls these accounts, bypassing the uid range and the login-shell check; an account still gets a row only for an agent installed in it. Windows: accepted, but every profile is already a candidate, so it changes nothing |
enterprise.enrollment.exclude_users | list | all | Never enrolled; wins over every include. Linux and macOS also match a numeric uid |
enterprise.enrollment.include_groups, exclude_groups | list | all | Linux and macOS: group names or numeric IDs. Windows: local and Active Directory groups by name or SID, and the Microsoft Entra ID groups that a built-in local group lists, by SID (Entra groups on Windows); decided from session tokens (cached for signed-out users) and the local account database |
enterprise.enrollment.exempt_users | list | all | Linux and macOS: inspected but not enrolled. Windows: machine-policy agents keep their rows, so the user is inspected; per-user agents get no new rows |
enterprise.enrollment.unenrolled_users | inspect | deny (inspect) | Linux, macOS | How machine-policy connectors treat users who are not enrolled. On Windows an unenrolled user always fails closed |
enterprise.enrollment.root | inspect | deny | exempt (inspect) | Linux, macOS | root is never enrolled. deny refuses root's hook calls. exempt currently behaves like inspect |
enterprise.enrollment.uid_min | integer (0) | Linux, macOS | 0 reads UID_MIN from /etc/login.defs on Linux (fallback 1000) and uses 501 on macOS |
enterprise.enrollment.uid_max | integer (0) | Linux, macOS | The highest uid enrolled, for local and directory accounts. 0: login.defs UID_MAX (fallback 60000) bounds only local accounts on Linux; macOS uses 2147483646 |
enterprise.enrollment.home_roots | list of absolute paths | Linux, macOS | Extra home parents the guardian may write, beyond /home and /var/home (Linux) or /Users (macOS) |
enterprise.enrollment.agent_prefixes | list of absolute paths | Linux, macOS | Extra administrator install prefixes where the enumerator and guardian look for agent CLIs. Paths under homes and temporary directories are refused |
enterprise.machine_policy.default.* and enterprise.machine_policy.connectors.<name>.* | see the next table | all | Resolution order: the connector's value, then default, then the built-in value. This block does not enable a connector; guardrail.connectors does |
enterprise.trust.mode, enterprise.trust.allowed_signers | authenticode | hash_pinned; SHA-256 thumbprints | Windows | Narrow the standalone lifecycle's payload trust: authenticode refuses a hash-pinned run and any run over a hash-pinned deployment (1639); hash_pinned or unset admits both; allowed_signers pins signers like --allowed-signer. Linux and macOS accept and validate them but do not use them |
enterprise.coexistence.per_user_install | migrate | block | ignore | — | Reserved: accepted and validated, no effect in this release |
enterprise.coexistence.disable_self_update | bool (true) | Windows | Sets HKLM\SOFTWARE\Policies\Cisco\DefenseClaw\DisableSelfUpdate only when the value is absent, which also stops the per-user install.ps1. On every managed host the update notice stays off and the per-user installer, upgrade and rollback refuse, whatever this key says |
enterprise.network.https_proxy, enterprise.network.no_proxy | proxy URL; host list | all | The gateway's outbound proxy: AI Defense, LLM providers (which need an http:// proxy URL), the passthrough, webhooks, the remote model router and telemetry exporters go through it. Linux and macOS also set HTTPS_PROXY and NO_PROXY (both cases) in the gateway's service environment; the Windows gateway sets them in its own process. A change needs a gateway restart |
enterprise.tetragon.mode | off | consume | observe | enforce (consume) | Linux | Use the Tetragon the computer runs as Plane C's process source (consume), also load DefenseClaw's policies in monitor mode (observe), or let two fixed kernel controls deny (enforce). Capped at off when Plane C is off. Windows and macOS accept and ignore it; the Secure Client profile refuses it. See Tetragon (Linux) |
enterprise.tetragon.burn_in | 0 or 24h to 2160h in whole hours (168h) | Linux | Covered agent time per enrolled user, with no would-block hit, before that user is enforced. 0 skips it and status warns. It counts hours of agent use, not calendar time |
enterprise.tetragon.enforce_ack | sha256: and 12 hex digits, a list of up to 4, or empty (empty) | Linux | The control-set digest you approved. A list approves several builds during a ring upgrade. Without a match the controls stay in monitor mode |
enterprise.tetragon.customer_events | agent | off (agent) | Linux | Report the events of your own Tetragon policies when they hit an AI agent. off forwards nothing and keeps the counts. DefenseClaw never changes your policies |
machine_policy key | Values | Built-in default |
|---|---|---|
ownership | merge | verify_only | off | merge |
managed_hooks_only | enforce | preserve | enforce |
foreign_hooks | remove | report | allow | remove |
higher_precedence_sources | fail | warn | fail |
allowed_hooks | list of SHA-256 digests | none; the default list and the connector's list are merged |
version_floor | enforce | report | off; only under connectors.claudecode | enforce; see Claude Code version floor |
How each OS applies these keys to each connector is on Machine policy.
The standalone lifecycle on Linux and macOS also requires config_version: 9 (a config_version: 8 file is migrated when it is applied),
enterprise.profile: standalone if you set it, and data_dir set to exactly
/var/lib/defenseclaw (Linux) or /opt/cisco/defenseclaw/runtime (macOS). If
you set gateway.api_bind or gateway.api_port, they must be 127.0.0.1 and
18970. Connectors are enabled by guardrail.connectors, as in any other
config; see Choose the agents to protect.
Custom LLM providers (llm_providers.custom)
Custom-provider instances are defined once in config.yaml under llm_providers.custom, so the same instance definition can be shared across roles (agent, judge). A role selects one with instance_name; the role wins and the instance fills blanks. defenseclaw setup provider add writes these entries and setup provider remove deletes them; you can also edit llm_providers with defenseclaw config set or by hand.
llm_providers:
custom:
- name: acme-internal-bedrock
base_provider_type: bedrock
base_url: https://llm.internal:8443
domains: [llm.internal]
env_keys: [ACME_BEDROCK_KEY]
allowed_requests: [chat, embedding]
available_models: [us.anthropic.claude-sonnet-4-6]
request_path_overrides:
chat: /openai/v1/chat/completions
tls:
ca_cert_file: /etc/acme/ca.pem # a file, not inline PEM
insecure_skip_verify: false
bedrock:
region: us-east-1
auth_mode: iam_credentials
access_key_env: AWS_ACCESS_KEY_ID
secret_key_env: AWS_SECRET_ACCESS_KEY
session_token_env: AWS_SESSION_TOKEN
inference_profile: "us."
deployment_aliases:
fast: us.anthropic.claude-haiku-4-5-20251001-v1:0
ollama_ports: [11434]An entry carries only the sub-block (bedrock, vertex or azure) matching its base_provider_type. An unknown auth_mode makes the file invalid: defenseclaw config validate exits 1 naming the field and the allowed values (for example llm_providers.custom[0].bedrock.auth_mode is "bogus_mode"; allowed values: api_key, iam_credentials, profile, instance_role.), defenseclaw doctor shows it as a failed Config validation row, and the gateway does not load the file (a reload or start fails and a running gateway keeps its previous configuration). A sub-block from another family is accepted and ignored; once a config write has rendered custom-providers.json, defenseclaw doctor warns about it in the Custom-provider overlay row (overlay sub-block family does not match base_provider_type). Auth modes are the same as on setup llm (api_key / iam_credentials / profile / instance_role for Bedrock; service_account / adc / workload_identity for Vertex; api_key / managed_identity for Azure). Other keys an entry accepts are profile_id (an OpenClaw auth-profile ID) and extra_headers. ollama_ports lists extra loopback ports to treat as Ollama.
The domains array drives the gateway's URL → instance lookup: when an inbound request URL (set on X-DC-Target-URL by fetch-interceptor agents, or recorded in the connector snapshot for native binaries) matches one of the listed hosts, the resolver applies this entry's TLS, base_url and sub-block posture. An entry that declares base_url should also list the matching host in domains.
A custom-providers.json marked _derived_from is rendered from this section on config writes. Do not edit it: the gateway does not read its edits back, defenseclaw doctor reports drift in the Custom-provider overlay row, and defenseclaw doctor --fix regenerates it. An unmarked overlay with request_overrides is a live input the gateway still merges (Custom providers).
Environment variables
Every variable DefenseClaw reads, with defaults, is on Environment variables. DEFENSECLAW_HOME relocates the data directory and DEFENSECLAW_LLM_KEY is the unified LLM key. On a managed standalone device some variables are ignored or may only tighten a setting (Managed hosts).
There is no DEFENSECLAW_GATEWAY_BIND, DEFENSECLAW_DATA_DIR or DEFENSECLAW_LOG_LEVEL. Configure the sidecar API with gateway.api_bind and gateway.api_port, the guardrail proxy with guardrail.host and guardrail.port (gateway.host and gateway.port are the upstream agent gateway). For extra diagnostics set a variable from Debug / verbose logging, such as DEFENSECLAW_SIDECAR_DIAG=1, in the gateway's environment and restart it.
Proxy variables. The telemetry exporters (OTLP, Galileo, Splunk HEC, HTTP JSONL) follow HTTPS_PROXY and NO_PROXY from the gateway's environment; enterprise.network.https_proxy takes precedence, and loopback destinations connect directly. The proxy URL must be http(s)://host[:port]; with a user name or password the gateway logs a warning and the exporters connect directly. Restart the gateway from a shell that has the variables set. Whenever a proxy variable is set, the CLI and gateway add the instance-metadata endpoints (169.254.169.254, 169.254.170.2, fd00:ec2::254) to NO_PROXY.
Per-connector files
defenseclaw setup <connector> writes these agent-side files from config.yaml. They are derived: change the setting in config.yaml, not the file. Hook scripts under ~/.defenseclaw/hooks/ carry a # defenseclaw-derived: header. Doctor warns stale generated script when a script is from an older build or bakes a different fail mode, naming the command that regenerates it. A script edited by hand, or copied from another build, fails the Hook runtime files row (changed since setup) and its freshness row warns a generated script is not the one setup rendered; defenseclaw doctor --fix renders it again.
| Connector | File DefenseClaw mutates |
|---|---|
| OpenClaw | ~/.openclaw/openclaw.json, ~/.openclaw/extensions/defenseclaw/ |
| ZeptoClaw | ~/.zeptoclaw/config.json |
| Claude Code | ~/.claude/settings.json |
| Codex | ~/.codex/config.toml |
| Cursor | ~/.cursor/hooks.json |
| Devin (Devin CLI and Devin Desktop's Devin Local) | ~/.config/devin/config.json or <workspace>/.devin/hooks.v1.json |
| GitHub Copilot CLI | ~/.copilot/hooks/defenseclaw.json by default; <workspace>/.github/hooks/defenseclaw.json with --workspace |
| Antigravity | ~/.gemini/config/hooks.json; Google documents no configuration-home environment override, and DefenseClaw owns only this global registration. Antigravity also discovers <workspace>/.agents/hooks.json, which DefenseClaw does not patch to avoid duplicate ownership. |
| Hermes | ~/.hermes/config.yaml on macOS/Linux or %LOCALAPPDATA%\hermes\config.yaml on native Windows ($HERMES_HOME/config.yaml when HERMES_HOME is set) |
| Kiro | ~/.kiro/hooks/defenseclaw.json (Kiro IDE and kiro-cli --v3), ~/.kiro/agents/defenseclaw.json (Kiro CLI 2.x) and ~/.kiro/settings/cli.json; a workspace copy under <workspace>/.kiro/hooks/ with --workspace |
| OpenCode | ~/.config/opencode/plugins/defenseclaw.js (managed bridge plugin — written whole, not patched; removed on teardown) |
| Amp | ~/.config/amp/plugins/defenseclaw.ts on macOS/Linux or %USERPROFILE%\.config\amp\plugins\defenseclaw.ts on native Windows (managed system policy plugin) |
Before the first mutation, a backup record is stored at ~/.defenseclaw/connector_backups/<connector>/<logical-name>.json. It binds the connector, logical name and absolute target path, and holds the pristine bytes, permissions, pristine hash and post-setup hash. Teardown (or --disable) restores the pristine bytes only when the current file still matches the recorded identity; if it drifted, teardown removes only DefenseClaw-owned entries and keeps unrelated edits.
Hook connectors default to global scope. claw.workspace_dir is empty unless you pass --workspace or set it with config set; GitHub Copilot CLI then uses it for .github/hooks/defenseclaw.json and workspace-local component discovery. Setup without --workspace keeps a pin that is still a folder (it clears one that is not, with a warning). To return to global scope, run defenseclaw config unset claw.workspace_dir, then defenseclaw setup <connector> again. The workspace is one value for the whole install, so setup <connector> --workspace refuses while other connectors are configured; use defenseclaw setup guardrail --workspace <dir> to scope every connector to one folder.
Every hook setup writes the resolved path contract to ~/.defenseclaw/hook_contract_lock.json. Its locations block records the pinned workspace, hook config file, generated script, and the MCP, skills, rules, plugins and agents surfaces DefenseClaw scans. defenseclaw doctor compares the lock against the files the active SDK can load.
Reload without restart
A running gateway applies config.yaml changes by itself. One watcher sees the file (and the rule pack and Rego files it refers to), builds a new policy generation off the hot path and swaps it in atomically. A change that fails to build (an unknown rule ID, a pack whose digest no longer matches) keeps the old generation, shows last_reload_error in /health, fails the Policy row in defenseclaw doctor and records a config.reload.rejected event. Invalid YAML does the same, except that doctor stops at the Config validation row with the line and column and shows no Policy row until the file parses.
Only process-level keys need defenseclaw-gateway restart. A write that touches one prints the command, and the gateway keeps that key's running value until you restart it:
Set guardrail.hook_self_heal (config generation 5, sha256 b0eecf44591d).
Effective policy digest: sha256:4254f65d36b3d7af4e4704a12570e2a4a1e0e5a4063a58d27a18953f5376a8f2
Restart the gateway to apply guardrail.hook_self_heal: defenseclaw-gateway restart| Restart-required key | Why |
|---|---|
data_dir, observability.local.path, observability.local.judge_bodies_path | Storage identity: the files the process opened at start |
gateway (the listener, API port and credentials; except gateway.watcher.* and the gateway.config_reload keys other than mode) | The listeners and credentials the process owns |
guardrail.host, guardrail.port, guardrail.enabled, guardrail.connector, guardrail.scanner_mode, guardrail.retain_judge_bodies | The guardrail listener, whether it runs, and start-up settings |
guardrail.hook_self_heal, guardrail.hook_self_heal_debounce_ms | The hook guard |
claw, agent, routing, plugin_dir | Paths, identity, the model router and the connector plugins, captured at start |
deployment_mode, enterprise.profile, enterprise.network, enterprise.openshell | The deployment boundary |
fleet.enabled, fleet.mqtt_broker_url, fleet.mqtt_require_tls, fleet.ota_key_env, fleet.emergency_key_env, fleet.device_key_env, fleet.mqtt_user_env, fleet.mqtt_pass_env | MQTT connections and signing keys |
environment, tenant_id, workspace_id, discovery_source | Identity stamped on every record from start |
Every other key is hot, including guardrail.mode, guardrail.hook_fail_mode, thresholds, rule packs and rules, admission, asset_policy, scanners, llm_providers, policy_dir, quarantine_dir, observability.destinations and update. The effective policy digest is stamped on /health, /status and every decision event; defenseclaw-gateway policy digest computes it from the file on disk, and the Policy row of defenseclaw doctor compares it with what the gateway applied (Policy generation and digest).
defenseclaw-gateway policy reload asks the running gateway to rebuild the generation now, for scripts and for assets the watcher may not see. Connector wiring (hook scripts, agent files) is not re-applied by a reload: run defenseclaw-gateway restart or defenseclaw setup <connector>. Both commands belong to the Go gateway binary; the Python CLI has no gateway group.
Configuration: one source of truth
Where every DefenseClaw setting lives. config.yaml holds what an administrator decided; hook files and provider files are derived from it; locks and ledgers are evidence; approvals, discovery and quarantine are runtime state. Includes the single config writer, policy generations, and the rules for managed hosts.
Migrate config.yaml from v8 to v9
What the config_version 8 to 9 migration moves into config.yaml, which commands run it, before and after examples for every moved key, how conflicts are recorded in migration-v9.json, and how to go back to DefenseClaw 0.8.x.