Configuration

~/.defenseclaw/config.yaml is the single source of truth for operator-owned configuration. Most fields are managed by defenseclaw setup * commands; you can also hand-edit the file. The running gateway watches the active config.yaml, validates the full file on change, and reconciles supported updates without a full process restart. Some storage identity fields still require a real defenseclaw-gateway restart.

The current strict configuration contract is version 8. Existing supported v7 files are converted automatically by the ordinary defenseclaw upgrade transaction. The gateway does not rewrite legacy files at startup and does not run v7 and v8 observability formats in parallel. See Upgrade DefenseClaw for the backup, atomic migration, rollback, and verification flow.

On-disk layout

Doctor cache

~/.defenseclaw/doctor_cache.json is the latest non-dry-run Doctor snapshot. The Textual TUI reads it for the Overview panel instead of repeating network-intensive 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 retain their health-only meaning. repair_summary and repairs form a separate ledger; a failed or blocked repair can make the aggregate outcome fail without increasing the health failure count.

The CLI publishes the cache with an atomic temporary-file replacement after each non-dry-run Doctor invocation, including nonzero outcomes. doctor --fix --dry-run is read-only and never writes it. The TUI marks snapshots older than 15 minutes stale. A later healthy check can show that live health recovered, but does not erase a cached failed or blocked repair. A missing cache is normal before the first Doctor run.

config.yaml schema

The shape below shows the normal source-authoring surface. Every block is optional, and setup commands preserve comments and unrelated hand edits. Use defenseclaw config reference observability for the generated all-knobs reference instead of copying every default into this file.

config_version: 8             # strict current schema; upgrade migrates supported v7 files

claw:
  mode: claudecode             # single-connector mode; setup aliases select this with --connector.
                               # Set to `multi` automatically when more than one
                               # connector is active (see guardrail.connectors below).
                               # This value is mirrored to the OTel resource attr
                               # `defenseclaw.claw.mode`.

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

# One observability graph owns collection, local history, routing, redaction,
# sampling, metrics policy, and every optional destination. Defaults collect
# all logs/traces/metrics, persist collected logs to SQLite, and export every
# capability of an enabled destination unredacted when send/routes are omitted.
# Galileo's omitted preset policy is additionally restricted to the generated
# available galileo-rich-v2 trace-family membership.
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` (and copied
# into per-component blocks via the `--inherit-from` machinery). The
# `role` field decides who consumes this block at resolve time:
#   - `unified` (default): every component that does not declare its
#     own `llm:` reads from here.
#   - `agent`: guardrail.judge.llm stays empty and inherits through
#     the unified merge — proxy connectors only.
#   - `judge`: writes guardrail.judge.llm directly, leaves the top
#     level alone — useful for hook-based connectors that already
#     route the agent's traffic elsewhere.
# See `defenseclaw setup guardrail --llm-role judge_only|judge_and_agent`
# for the connector-aware variant.
llm:
  provider: anthropic          # anthropic | openai | bedrock | vertex_ai | azure | custom
  model: claude-sonnet-4-5
  api_key_env: DEFENSECLAW_LLM_KEY
  base_url: ""                 # optional override; LiteLLM picks a default per provider
  role: unified                # unified | agent | judge
  instance_name: ""            # binds to a ~/.defenseclaw/custom-providers.json entry; required with provider: custom
  region: ""                   # generic regional hint (Bedrock / Vertex); provider-specific sub-blocks below take precedence
  # forward_custom_headers controls whether the guardrail gateway
  # forwards inbound HTTP headers from the agent to the upstream LLM
  # provider on both /v1/chat/completions and the passthrough path
  # (/v1/responses, /v1/messages, Bedrock/Gemini native, ...). Default
  # is on; set to false to suppress all inbound header copying so the
  # upstream only sees the canonical Authorization the gateway re-mints
  # from the secrets sidecar. A small blocklist (proxy-hop, auth, host,
  # X-DC-*, X-DefenseClaw-*, W3C trace context) plus RFC 7230 /
  # printable-ASCII validation and 64-header / 32 KiB caps apply
  # regardless.
  forward_custom_headers: true

  # Provider-specific sub-blocks. Only the one matching `provider`
  # is consulted; the others may exist as leftover state from a
  # previous setup and are ignored at resolve time.
  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. Both
  # `ca_cert_pem` and `insecure_skip_verify` exist so the gateway
  # never has to read another file at request time; `doctor` warns
  # when both are set on the same block.
  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-4o-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
  scanner_mode: local          # local | remote | both
  rule_pack_dir: ~/.defenseclaw/policies/guardrail/default  # path; --rule-pack picks the bundled profile dir
  block_at: ""                 # CRITICAL | HIGH | MEDIUM | LOW; empty -> the rule pack's level
  alert_at: ""                 # same values; never above block_at
  port: 4000                   # guardrail proxy port
  block_message: ""            # custom; empty -> default
  detection_strategy: regex_only  # regex_only | regex_judge | judge_first

  cisco:
    endpoint: ""
    api_key_env: CISCO_AI_DEFENSE_API_KEY
    timeout_ms: 5000

  # When `judge.llm` is omitted, the judge inherits from the top-level
  # `llm:` block. Populate it explicitly to point the judge at a
  # different backend (e.g. an internal Bedrock instance) without
  # changing what the agent talks to.
  judge:
    enabled: false
    model: anthropic/claude-sonnet-4-20250514
    api_base: ""
    api_key_env: DEFENSECLAW_LLM_KEY
    llm: {}                    # same shape as top-level `llm:` above

  hilt:
    enabled: false
    min_severity: HIGH         # stored uppercase; CLI accepts high|medium|low|critical

  # Multi-connector overlay. One gateway can enforce guardrail policy for
  # several hook connectors at once; each key under `connectors` is a
  # connector name (codex, claudecode, antigravity, ...) carrying a
  # subset of the guardrail knobs above. Every field is OPTIONAL and
  # inherits the global `guardrail.*` value when unset. The singular
  # `guardrail.connector` above keeps working for single-connector
  # installs; this map is purely additive. Proxy connectors (openclaw,
  # zeptoclaw) cannot appear here — multi-connector is hook-only.
  # Managed by `defenseclaw setup <connector>` (choosing "Add") and the
  # `defenseclaw guardrail ... --connector X` command group.
  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_dir: ~/.defenseclaw/policies/guardrail/strict  # inherits guardrail.rule_pack_dir
      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

# 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: ""             # optional HMAC for `type: generic`
    min_severity: HIGH

When gateway.api_bind is empty, the sidecar uses 127.0.0.1. The only exception is a host that still carries the removed legacy standalone sandbox (openshell.mode: standalone with a guardrail.host that is non-empty and not the literal localhost): the management API inherits guardrail.host until defenseclaw sandbox legacy-cleanup resets the config. An explicit gateway.api_bind always wins. See Gateway API: bind address.

The openshell: block for the NVIDIA OpenShell sandbox is described in OpenShell sandbox settings below.

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 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, so an install that never picked a connector (a sandbox-only install, for example) names OpenClaw without having it. When only claw.mode names OpenClaw (guardrail.connector is empty and guardrail.connectors has no openclaw entry), gateway.host is loopback, fleet_mode is unset or auto, and OpenClaw is not installed, 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. Instead of reconnecting forever, 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 the Mac app show the same text, and OPENCLAW_GATEWAY_TOKEN is not required. The gateway checks when it starts, so restart it after installing OpenClaw, or set fleet_mode: enabled to dial regardless.

Routing and observability behavior

The routing block affects OpenClaw and ZeptoClaw only when they use the proxy's OpenAI-compatible Chat Completions path. Hook connectors and other provider API shapes keep their existing path. defenseclaw keys list dynamically discovers each non-empty api_key_env; the classifier never receives the key value. See Semantic model routing for the exact lifecycle, privacy boundary, and compatibility matrix.

The source file stays small because omissions compile to explicit effective policy. With observability: {}, all 14 buckets collect logs, traces, and metrics, local SQLite stores all collected logs unredacted, and no remote destination exists. Adding an enabled destination without send or routes selects every bucket, every signal supported by that destination, and profile none (unredacted). A logs-only kind therefore sends all logs; a general OTLP kind sends logs, traces, and metrics. The Galileo preset instead generates one traces-only capability-default route whose event-name selector is restricted to the available family membership in its generated compatibility profile.

An explicit send block or advanced routes block replaces that generated route. For Galileo this is operator intent, not an implicit intersection with profile membership. Explicit policy can narrow buckets and select a destination-specific redaction profile, but any selected nonmember reaches the compatibility projector, is rejected as unsupported_shape, and is reported through destination failure accounting and health. Enumerate reviewed compatible event_names in an advanced route when exact family control is required; inspect the generated membership and effective route with defenseclaw config show --effective --section observability and defenseclaw observability plan before activation.

Multiple destinations are independent fan-out legs. The same collected record can go to SQLite, Splunk, local OTLP, and Galileo, with a different selector and redaction profile on each leg. An optional destination failure does not disable another leg.

For advanced routes, YAML order matters: the first matching route wins for that destination and signal, and an unmatched record is not delivered. Selector fields are ANDed; values within one field are ORed. Supported selectors are buckets, sources, connectors, actions, event_names, and 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, not listed under destinations, and cannot be disabled or filtered. Omitting retention_days uses the seven-day rolling default shown above. Set a larger value only when the additional local storage and retention scope are intentional. retention_days: 0 means retain forever and produces a capacity warning. guardrail.retain_judge_bodies independently controls whether new raw judge bodies are captured.

Destination transport and queue limits

At most 64 destinations may be configured, with names unique after canonical normalization. One advanced routes list has at most 256 entries. Queue-backed destinations default to 2,048 projected records and 67,108,864 bytes; valid bounds are 1..65536 records and 4198400..268435456 bytes. JSONL and console accept only these queue fields.

Splunk HEC, HTTP JSONL, and OTLP additionally default to batches of at most 512 records/8,388,608 fully encoded bytes with a 5,000 ms scheduled delay and a 10,000 ms per-attempt timeout. Batch count is 1..8192 and cannot exceed queue count; batch bytes are 4263936..67108864; delay is 1..600000 ms. Galileo's omitted preset delay resolves to 1,000 ms. Prometheus is pull-based and rejects batch.

If queue count or bytes would overflow, the newest attempted enqueue is dropped; older FIFO work, mandatory SQLite, and sibling destinations remain intact. Transient or ambiguous acknowledgements retry the exact immutable projection and record ID. Remote delivery is not exactly once because an acknowledgement can be lost after receipt. The effective plan shows all resolved adapter/preset defaults.

See Observability for the bucket catalog, capability matrix, route examples, and redaction precedence.

gateway.config_reload.mode controls what happens after a valid config.yaml change:

Live reload rejects storage identity changes such as data_dir, audit DB path, judge bodies DB path, and gateway.device_key_file unless restart mode is enabled or the operator restarts the gateway manually.

The full LLM configuration story — picking a role, binding a custom-provider instance, configuring regional Bedrock / Vertex / Azure backends, and how defenseclaw doctor validates each — lives on Setup → Unified LLM key. The schema above is the on-disk shape; the page is the operator-facing how-to.

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, and 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 to an unblock or an ask are saved to egress.unblocked or egress.block. See also Sandbox. Policy packs, how the layers combine, and the administrator's openshell.admin limits are explained in Sandbox policy packs and admin controls.

The posture is layered. The selected sandbox policy pack supplies every default, the keys below override it, the options of sandbox run 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, so a custom pack is the way to change them: the approvals mode, the review list, mcp.blocked_tools, mcp.project_servers (whether the MCP servers a repository defines may start), and hooks.on_tamper (whether a sandbox whose hooks were bypassed is stopped or only reported).

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
  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
  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
  middleware:
    enabled: false             # reserved; nothing reads it yet
  admin: {}                    # administrator limits; see below

Sandbox keys

Host patterns in egress.block, egress.allow, egress.unblocked, admin.egress_block, and admin.egress_allow_only (and in a pack's egress lists) use the egress proxy's grammar: a host name, *.<host> for every subdomain (not the host itself), 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 of an IPv4 address all match the same entry. A bare * is refused: choose the profile instead (open allows by default, strict turns the web off). Schemes, ports, paths, and wildcards inside a name are refused, and so are host names whose last label does not start with a letter (127.1, 0x7f000001), because resolvers read them as addresses. Matching ignores case and a trailing dot. One list widens a host name: on admin.egress_block, example.net blocks the host and all its subdomains, the way an administrator blocking a domain means it. Every other list matches a host name exactly. Lists hold at most 4096 entries.

Project globs (workdir.masks, workdir.unmask, and sandbox run --unmask, like a pack's masks) are relative to the project folder and use forward slashes. Absolute paths, ~, drive letters, backslashes, and .. segments 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 use letters, digits, ., _, and -, up to 128 characters. An image.harness_versions key can't contain ., which the configuration loader would read as a nested key.

Packs at a glance

The built-in packs are:

• open, the default: open web through the DefenseClaw egress proxy with the exfiltration blocklist, a live project mount, and skip-permissions mode on. A direct connection request is approved automatically unless the policy refuses it (the blocklists, a public IP address, a port off the list) or it reaches into your machine or private network, which asks.
• balanced: a curated developer allowlist, and triaged approvals. The allowlist is the egress proxy's allowlist feed, host for host. The proxy can't see inside HTTPS tunnels, so its source hosts (GitHub, GitLab, Bitbucket) accept pushes and uploads as well as fetches; a push still needs a credential inside the sandbox.
• strict: no web beyond the harness's model provider, manual approvals, copy mode, the harness's own prompts kept, and no MCP servers.

Every built-in pack masks common secret files (.env, .env.*, keys and certificates, cloud, Kubernetes and Docker credentials) and keeps committed templates such as .env.example visible (the pack's workspace.unmask). Whatever the pack, the end-of-session review also flags changes to harness and agent-tool project config (.claude/, .mcp.json, .codex/, .cursor/, .gemini/, AGENTS.md, CLAUDE.md, and similar), to lock files, and to pack.yaml files: a harness run later outside the sandbox acts on them without asking.

Raising the profile above a pack's own network mode, for example profile: balanced on the open pack, brings in the balanced pack's curated allowlist. Allow entries that cover every host or a whole top-level domain (*.com) are ignored, and custom packs may not contain them.

A custom pack is one strict YAML file with the same sections as the built-in ones. Unknown or repeated keys, anchors, symbolic links, and built-in names are refused. The pack file and its directory must belong to you or to root and must not be writable by their group or by every user. A pack in a sticky directory that other users can write to, such as /tmp, loads only when root owns it. Because you own your custom packs, keep them out of folders you mount into a sandbox: a folder that holds the policy is never shared with the sandbox. See Write a custom pack.

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 set to false. Each key is explained, with examples, in Sandbox policy packs and admin controls.

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: []
    egress_block: []         # always blocked, never unblockable
    egress_allow_only: []    # 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

required_pack pins the pack and makes its posture a floor: your keys and run options may tighten its profile, skip-permissions default, workspace mode, MCP import, blocklist feed, and proxy ports, but every attempt to loosen them is refused. That includes a request to skip permissions or to mount a host folder when the required pack keeps the prompts or works on a copy. In a managed_enterprise install, a custom required pack must be a file that root owns and no other user can modify, together with every directory above it, such as an absolute path under an administrator-owned directory. The default pack_dir in the data directory usually does not qualify.

locked keeps the configured value of each listed key against run options that would loosen it, while options that only tighten it still apply: --safe, --copy, --no-mcp, a --profile at least as strict as the configured one, a --pack at least as strict as the configured pack in every setting (or, when pack itself is not locked, in every setting behind a locked key, such as the pack's skip-permissions default for yolo), a smaller --cpu or --memory, and --unmask or --host-port entries the configuration already lists.

require_copy_for entries are absolute path globs or start with ~/. *, ?, and [...] match within one path segment, and ** across segments. A relative entry is refused, because it would never match, and a pattern that starts with **/ covers every mounted folder, since any folder may hold a match below it. The list also covers mounting a folder above a listed project, a project folder DefenseClaw can't check, and differently cased spellings of the path.

Every loosening that 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 administrator owns config.yaml, so the admin block is authoritative. Elsewhere it is still enforced, but it is advisory, because you can edit the file. sandbox policy explain and sandbox doctor say which applies.

Validation and reload

The v8 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. The one exception is entering or leaving the legacy standalone mode (openshell.mode), which needs a gateway restart.

Legacy keys

mode and sandbox_home remain for the removed legacy standalone sandbox. They are read only by the legacy bind rule above and by defenseclaw sandbox legacy-cleanup. policy_dir, version, auto_pair, and host_networking are accepted and ignored. No migration rewrites the block.

guardrail.connectors and claw.mode: multi

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.

claw.mode becomes multi automatically once more than one connector is active. That sentinel is mirrored onto the OTel resource attribute defenseclaw.claw.mode, so a fan-out gateway is distinguishable from a single-connector one in dashboards and SIEM. The singular guardrail.connector is untouched and still drives single-connector installs — the map is purely additive. Proxy connectors (OpenClaw, ZeptoClaw) cannot be entries here; multi-connector is hook-only. Manage these blocks with defenseclaw setup <connector> (choosing Add) and the defenseclaw guardrail ... --connector X command group — see Setup → 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.

How each OS applies these keys to each connector is on Machine policy.

The standalone lifecycle on Linux and macOS also requires config_version: 8, 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-provider overlay (~/.defenseclaw/custom-providers.json)

Custom-provider instances live in a separate JSON overlay so the same instance definition can be shared across roles (agent, judge) and across hosts. The Python merger (_apply_instance_overlay) and the Go dispatcher (buildProviderFromEffective) both apply the same rule: the role wins; the overlay fills blanks.

{
  "providers": [
    {
      "name": "acme-internal-bedrock",
      "base_provider_type": "bedrock",
      "base_url": "https://llm.internal:8443",
      "domains": ["llm.internal"],
      "env_key": "ACME_BEDROCK_KEY",
      "allowed_request_types": ["chat", "embedding"],
      "available_models": ["us.anthropic.claude-sonnet-4-6"],
      "request_path_overrides": {
        "chat": "/openai/v1/chat/completions"
      },

      "tls": {
        "ca_cert_pem": "-----BEGIN CERTIFICATE-----\n...",
        "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",
        "profile_name": "",
        "inference_profile": "us.",
        "deployment_aliases": {
          "fast": "anthropic.claude-3-haiku-20240307-v1:0"
        }
      },

      "vertex": {
        "project_id": "acme-prod-vertex",
        "region": "us-central1",
        "auth_mode": "service_account",
        "service_account_json_env": "GOOGLE_APPLICATION_CREDENTIALS"
      },

      "azure": {
        "endpoint": "https://my-resource.openai.azure.com",
        "api_version": "2024-10-21",
        "auth_mode": "api_key",
        "deployment_aliases": {
          "gpt-4o": "prod-gpt4o-eus"
        }
      }
    }
  ]
}

In practice an entry only carries the sub-block matching its base_provider_type — extras are ignored at dispatch time but defenseclaw doctor warns about family mismatches (e.g. bedrock block with base_provider_type: openai), unknown auth_mode values, and dead overlay fields the role-level config already shadows. 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).

The domains array drives the gateway's URL → overlay 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 overlay entry's TLS, base_url, and sub-block posture. Any entry that declares base_url should also list the matching host in domains; defenseclaw doctor warns when the two diverge.

Environment variables

A handful of high-traffic env vars are inlined below. The full inventory — every variable the CLI and gateway read, with file:line references — lives on Reference → Environment variables.

There is no DEFENSECLAW_GATEWAY_BIND, DEFENSECLAW_DATA_DIR, or DEFENSECLAW_LOG_LEVEL env var today. Use DEFENSECLAW_HOME to relocate the data directory. Configure the sidecar API listener with gateway.api_bind and gateway.api_port, and the separate guardrail proxy listener with guardrail.host and guardrail.port; gateway.host/gateway.port are the upstream agent-gateway address. Set log verbosity through the sidecar's --log-level flag (see defenseclaw-gateway start --help).

Per-connector source-of-truth files

A managed backup record is stored at ~/.defenseclaw/connector_backups/<connector>/<logical-name>.json before the first mutation. The JSON record binds the connector, logical name, and absolute target path and stores 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 managed-file identity. If the file has drifted, connector-specific teardown removes only DefenseClaw-owned entries and preserves unrelated operator edits.

Hook connectors default to global/user scope. claw.workspace_dir is empty unless you pass --workspace; when set, OpenHands uses it for repo-local .openhands/hooks.json, .agents/skills, and deprecated .openhands/skills discovery while still scanning global user skills and the OpenHands public skills cache. Copilot uses it for .github/hooks/defenseclaw.json and workspace-local component discovery. Re-run defenseclaw setup <connector> without --workspace to return to global scope.

Every hook setup also writes the resolved connector path contract to ~/.defenseclaw/hook_contract_lock.json. The locations block records the pinned workspace, hook config file, generated hook script, and the MCP/skills/rules/plugins/agents surfaces that DefenseClaw will scan for that connector. Use defenseclaw doctor to compare that lock against the files the active SDK can actually load.

Reload without restart

defenseclaw-gateway policy reload

Tells the running sidecar to re-read OPA policies from disk without bouncing the daemon. Connector wiring (hook scripts, agent files) is not re-applied — use defenseclaw setup guardrail --restart for that. Note this is on the Go sidecar binary (defenseclaw-gateway), not the Python CLI; the Python CLI has no top-level gateway group.