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:

KindFilesWhat 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-v9Keep; 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 inventoryReported, 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
device.key
claude-code-hook.sh
codex-hook.sh
… (one script per agent you set up)
defenseclaw
defenseclaw-gateway
defenseclaw-acp
skill-scanner
mcp-scanner

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.

PathWhat it isEdit it?
config.yamlYour 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.jsonGeneration, SHA-256, actor and time of each write to config.yaml.No.
custom-providers.jsonCustom LLM providers, derived from llm_providers.No. defenseclaw doctor --fix regenerates it.
config.yaml.v8.bak, migration-v9.jsonKept by the config_version 9 migration.Read them. defenseclaw config migrate --ack marks the record read.
.envProtected tokens and API keys.No. Never print it. Use defenseclaw keys.
audit.dbThe local audit database (SQLite).No. Do not open it with a second writer or attach it to a ticket.
gateway.logThe gateway's output.Read it locally; check excerpts before sharing.
logs/install-*.logOne log per install, upgrade or rollback.Read it.
logs/hook-failures.jsonlHook 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.pidRecords of the running gateway and watchdog.No.
gateway.jsonlExists 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: HIGH

Other top-level keys

Defaults from the loader. Omitted keys take these values.

KeyDefaultWhat it does
data_dir~/.defenseclawThe 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.dbThe 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, policiesQuarantined files, connector plugins, policy assets.
environmentdetected (macos, windows, linux, ...)Stamped on every record. Restart required.
tenant_id, workspace_id, discovery_sourceemptyIdentity stamped on every record. Restart required.
deployment_modeemptymanaged_enterprise on a managed device. Restart required.
claw.modeopenclawThe 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.jsonWhere the OpenClaw install is looked up.
claw.workspace_diremptySet by setup <connector> --workspace or config set; scopes hooks to one folder, and setup without --workspace keeps it (Per-connector files).
gateway.host, gateway.port127.0.0.1, 18789The upstream agent gateway (OpenClaw and ZeptoClaw fleet link).
gateway.fleet_modeautoauto, enabled or disabled: when to dial host:port (OpenClaw fleet link).
gateway.token_envDEFENSECLAW_GATEWAY_TOKENThe variable that holds the sidecar API token (Keys).
gateway.api_port, gateway.api_bind18970, emptyThe sidecar REST API. Empty api_bind binds 127.0.0.1 (Gateway API).
gateway.device_key_file<data_dir>/device.keyThe device key.
gateway.auto_approve_safefalseAuto-approve safe requests from the upstream gateway.
gateway.reconnect_ms, gateway.max_reconnect_ms800, 15000Reconnect backoff to the upstream gateway.
gateway.approval_timeout_s30Seconds to wait for an approval.
gateway.watchdog.enabled, .interval, .debouncetrue, 30, 2The health watchdog: poll interval in seconds and consecutive failures before an alert.
gateway.watcher.*onThe install watcher for new skills, plugins and MCP servers; take_action: false alerts only.
watch.debounce_ms, watch.auto_block500, trueDebounce for file events, and whether a rejected install is blocked.
watch.rescan_enabled, watch.rescan_interval_min, watch.rescan_content_gatedtrue, 60, truePeriodic rescan of installed assets; content gating skips a target whose content did not change.
llm.timeout, llm.max_retries30, 2Seconds and retries for the unified LLM block.
decision_model.enabledfalseThe 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_connectorsemptyConnectors (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_block1, 0.30, 0.75, escalateSeconds 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.endpointhttps://us.api.inspect.aidefense.security.cisco.comThe AI Defense inspection endpoint.
cisco_ai_defense.api_key_env, .timeout_msCISCO_AI_DEFENSE_API_KEY, 3000The key variable, and the request timeout.
notifications.enabledtrue on macOS and native Windows, else falseDesktop notifications master switch (defenseclaw setup notifications).
notifications.block_enforced, .hitl_approvaltrueNotify on a real block, and on a pending approval.
notifications.block_would_blockfalseAlso notify when observe mode would have blocked.
notifications.sources.hook, .guardrail, .asset_policytruePer-source switches.
notifications.dedup_window, .max_per_minute30 seconds, 12Duplicate suppression and rate cap.
guardrail.stream_buffer_bytes1024Buffer for streamed proxy responses.
guardrail.judge.timeout, .adjudication_timeout30, 5Seconds for a judge call, and for adjudication.
guardrail.judge.max_parallelAutomaticMost 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_bodyemptyAdditional 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, .exfiltrueWhich judge categories run when the judge is enabled.
guardrail.judge_sweeptrueRun the full judge on content the regex triage found no signal in.
guardrail.retain_judge_bodies, .judge_persist_queue_depthtrue, 1024Keep raw judge bodies in judge_bodies.db, and the async write queue depth. Restart required.
guardrail.hook_self_heal, .hook_self_heal_debounce_mstrue, 500Re-install a deleted DefenseClaw hook block while the gateway runs. Restart required.
guardrail.chains.root_scopefalseManaged 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, .pathsalert, built-in listThe 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

KeyDefaultMeaning
guardrail.profiles.<name>noneA 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_inventoryallIDE extension and plugin inventory scope: all, ai_only or off. See IDE plugin inventory.
ai_discovery.include_user_principalfalseSend 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.

KeyDefaultMeaning
guardrail.rule_packdefaultThe 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>noneA 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_atemptyThe 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_levelfullHow 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.tracefalseLog 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)
HIGH

The 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.

KeyDefaultMeaning
admission.<type>.scan_on_installtrueScan a new asset when it is installed.
admission.<type>.allow_list_bypass_scantrueAn asset on the allow list skips the scan. false scans it anyway.
admission.<type>.actions.<severity>see belowOne 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_listbuilt inAssets 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.

KeyDefaultMeaning
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).

KeyDefaultMeaning
scanners.skill_scanner.policyquietThe scan policy preset: quiet, strict, balanced, permissive, low-noise, or custom.
scanners.skill_scanner.policy_filenone{path, digest} of your policy file, pinned by digest. Used only with policy: custom and required there.
scanners.skill_scanner.use_llmtrueThe LLM analyzer.
scanners.skill_scanner.use_behavioral, enable_meta, use_triggerfalseThe behavioral, meta and trigger analyzers.
scanners.skill_scanner.lenienttrueTolerate malformed skills instead of failing them.
scanners.skill_scanner.llm_consensus_runs0Run 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_sourceinheritinherit 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_severityHIGHThe 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_minMEDIUMThe review (warn) band starts here. It must not be above fail_on_severity.
scanners.skill_scanner.analyzers.virustotaloff{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.enabledfalseCisco AI Defense and OSV dependency checks.
scanners.skill_scanner.timeouts.scan_s300Seconds 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_instructionsfalseAlso scan prompts, resources or server instructions.
scanners.mcp_scanner.judge_source, llminheritAs for the skill scanner.
scanners.mcp_scanner.unverified_serverwarnWhat 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.yarabundled rulesinclude_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

KeyDefaultMeaning
update.checktrueThe 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.channelstableThe only channel.
update.sourceemptyWhere 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.

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 openclaw and zeptoclaw connectors dial;
  • codex and claudecode dial only when gateway.host is 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 send or routes takes every bucket, every signal it supports, and profile none. A logs-only kind sends all logs; a general OTLP kind sends logs, traces and metrics. The Galileo preset generates one traces-only capability-default route restricted to its available family membership.
  • An explicit send or routes block replaces the generated route. A selected nonmember of the Galileo family is rejected as unsupported_shape and 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 keeps retention_days (default 7; 0 retains forever and warns about capacity). The same window bounds AI discovery history in <data_dir>/inventory.db. max_store_mb (default 0, off) is an opt-in size cap for audit.db in MiB, 64 or more.

Destination transport and queue limits

LimitValue
Destinationsat most 64, names unique after canonical normalization
Advanced routes per destinationat 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:

ModeBehavior
hotDefault. Reload, validate, diff and reconcile in the running gateway.
restartValidate 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 below

Sandbox keys

KeyDefaultValues and rules
enabledfalseThe 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.
binaryopenshellThe 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_port0The 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_port0The 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 installWhere 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.
yolonullSkip-permissions mode for the harness. null follows the pack.
keep_headlessfalsetrue 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.
llmautoThe 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_mb0Copy-mode size limit in MiB, 0–1048576. 0 follows the pack.
workdir.git_depth200History depth of the copy-mode clone, 0–1000000. 0 uses 200.
workdir.undo_ignored.enabledfalseWhether 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_mb500The 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_exitaskWhat 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_mb0Report 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_uploadsfalsetrue 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_ms30000–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_proposalsnullWhether 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.importnullWhether 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_telemetryfalseWhether 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_deliveryproviderHow 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
KeyValuesEffect
required_packPack reference, like packEvery run uses this pack, and its profile, skip-permissions default, workspace mode, MCP import, blocklist feed, and proxy ports are floors.
required_pack_digestsha256: and 64 lowercase hex digitsPins the required pack's content: the digest defenseclaw sandbox pack show reports. Needs required_pack.
min_profileopen, balanced, strictThe loosest profile allowed.
allow_yolotrue, false, nullfalse keeps every harness's permission prompts.
allow_mounttrue, false, nullfalse forces copy mode and refuses every host folder mount.
allow_host_portstrue, false, nullfalse refuses every host port.
allow_unblocktrue, false, nullfalse 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_modetrue, false, nullfalse refuses learn mode.
allowed_harnessesHarness names, at least oneOnly these harnesses may run. Leave the key out for no limit: an empty list is refused.
egress_blockHost patternsAlways blocked, for every sandbox. Nothing unblocks or approves them. A host name also blocks its subdomains (example.net covers www.example.net).
egress_allow_onlyHost patterns, at least oneLeave 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_uploadstrue, falsetrue 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_forPath globs, at most 1024Projects that must run in copy mode.
max_resources.cpu, max_resources.memorySame formats as resourcesCeilings for every sandbox.
lockedUp to 16 of pack, profile, yolo, workdir.mode, workdir.unmask, mcp.import, mcp.host_ports, resourcesKeys 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_port and egress_port must differ when both are set;
  • when enabled is true, the effective ingress and egress ports must differ from each other, from gateway.api_port, and from guardrail.port. A derived port that would pass 65535 (a gateway.api_port of 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_digest must be a well-formed digest and needs admin.required_pack, and every admin.locked entry 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 keyTypeInherits when unset
enabledbool pointer — omit = inherit (on); false = explicitly off (drops it from the active set, removes its hooks)on
modeobserve | actionguardrail.mode
hook_fail_modeopen | closedguardrail.hook_fail_mode
block_messagestringguardrail.block_message
rule_packa preset (default, strict, permissive) or a guardrail.custom_packs nameguardrail.rule_pack
block_atCRITICAL | HIGH | MEDIUM | LOW (any case) — lowest severity that blocksguardrail.block_at, then the rule pack's level
alert_atsame values — lowest severity that alerts; never above the block levelguardrail.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.

KeyValues (default)OSNotes
enterprise.profilesecure_client | standalone (Windows and macOS: secure_client; Linux: standalone)allLinux accepts only standalone
enterprise.inspection.ai_defense.enabledbool (false)allAdds Cisco AI Defense to the local engine
enterprise.inspection.ai_defense.credentialcredential nameallLowercase 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.credentialcredential namestandaloneNames 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.modeauto | manifest (auto)allWith manifest you publish targets.yaml and the enumerator does nothing. On Windows the first install then needs --manifest (Setup: MANIFEST=)
enterprise.enrollment.include_userslistallLinux 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_userslistallNever enrolled; wins over every include. Linux and macOS also match a numeric uid
enterprise.enrollment.include_groups, exclude_groupslistallLinux 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_userslistallLinux 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_usersinspect | deny (inspect)Linux, macOSHow machine-policy connectors treat users who are not enrolled. On Windows an unenrolled user always fails closed
enterprise.enrollment.rootinspect | deny | exempt (inspect)Linux, macOSroot is never enrolled. deny refuses root's hook calls. exempt currently behaves like inspect
enterprise.enrollment.uid_mininteger (0)Linux, macOS0 reads UID_MIN from /etc/login.defs on Linux (fallback 1000) and uses 501 on macOS
enterprise.enrollment.uid_maxinteger (0)Linux, macOSThe 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_rootslist of absolute pathsLinux, macOSExtra home parents the guardian may write, beyond /home and /var/home (Linux) or /Users (macOS)
enterprise.enrollment.agent_prefixeslist of absolute pathsLinux, macOSExtra 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 tableallResolution 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_signersauthenticode | hash_pinned; SHA-256 thumbprintsWindowsNarrow 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_installmigrate | block | ignore—Reserved: accepted and validated, no effect in this release
enterprise.coexistence.disable_self_updatebool (true)WindowsSets 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_proxyproxy URL; host listallThe 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.modeoff | consume | observe | enforce (consume)LinuxUse 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_in0 or 24h to 2160h in whole hours (168h)LinuxCovered 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_acksha256: and 12 hex digits, a list of up to 4, or empty (empty)LinuxThe 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_eventsagent | off (agent)LinuxReport 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 keyValuesBuilt-in default
ownershipmerge | verify_only | offmerge
managed_hooks_onlyenforce | preserveenforce
foreign_hooksremove | report | allowremove
higher_precedence_sourcesfail | warnfail
allowed_hookslist of SHA-256 digestsnone; the default list and the connector's list are merged
version_floorenforce | report | off; only under connectors.claudecodeenforce; 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.

ConnectorFile 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 keyWhy
data_dir, observability.local.path, observability.local.judge_bodies_pathStorage 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_bodiesThe guardrail listener, whether it runs, and start-up settings
guardrail.hook_self_heal, guardrail.hook_self_heal_debounce_msThe hook guard
claw, agent, routing, plugin_dirPaths, identity, the model router and the connector plugins, captured at start
deployment_mode, enterprise.profile, enterprise.network, enterprise.openshellThe 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_envMQTT connections and signing keys
environment, tenant_id, workspace_id, discovery_sourceIdentity 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.