Configure a standalone deployment

A standalone deployment reads one administrator-owned config.yaml per host. The keys are the same on every OS. The lifecycle validates the whole file before it changes anything: an invalid config is refused, and the host keeps running the config it already has.

This page is the reference for that file. For the terms used here, see Concepts.

Where the config lives

Linux and macOS. The apply job also runs when a file directly inside the secrets or policies directory next to the config is added, removed or replaced. Changes in subdirectories do not trigger it; run ensure yourself. The lifecycle takes its config from the first of these that exists:

1. The file named by --config (an absolute path).
2. The file already at the path in the table. An MDM can stage it there before the package runs.
3. The built-in default: observe mode with no agents selected, so it protects nothing.

The package ships no config. The lifecycle does not check who owns a file you stage yourself, so write it as root and keep it unwritable by other users. The MDM wrapper refuses a config file that a non-administrator can write (mdm_untrusted_input); see Deliver the config.

Windows. Supply the file to ensure (the CLI's --config, Setup's CONFIG= or the wrapper's -ConfigPath). Ensure compares it with the installed copy and reapplies it when it differs. Do not edit the installed copy in place: ensure only compares the file you supply.

Required keys

Set these keys in every standalone config. On Linux and macOS the lifecycle fills in deployment_mode and enterprise.profile when they are missing and refuses conflicting values:

• enterprise.profile. Always set it. When it is unset, Windows and macOS resolve to the Secure Client profile, and the enterprise policy commands refuse to run. The profile cannot change without a reinstall.
• data_dir. On Linux and macOS the service sandbox allows writes only there, so the lifecycle refuses any other value.
• policy_dir. On Linux and macOS a config that leaves it out uses the root-owned folder of policies DefenseClaw ships (/opt/defenseclaw/share/policies on Linux, /opt/cisco/defenseclaw/share/policies on macOS), never a folder inside data_dir, because the gateway loads its policies from there. Set it to /etc/defenseclaw/policies (Linux) or /opt/cisco/defenseclaw/etc/policies (macOS), as the minimal configs do, to keep your own rule packs there.
• API listener. The gateway API is 127.0.0.1:18970 on every OS. Every OS refuses any bind address other than 127.0.0.1; Linux and macOS also refuse any other port.
• guardrail.rule_pack_dir. Set it to "" to select the rule packs built into the gateway. A non-empty value names a rule-pack directory, which only administrators may be able to write.
  • Linux and macOS: when you leave the key out, the gateway uses <policy_dir>/guardrail/default if you created that folder, and otherwise the default pack DefenseClaw ships (/opt/defenseclaw/share/policies/guardrail/default on Linux, /opt/cisco/defenseclaw/share/policies/guardrail/default on macOS), so a config that leaves the key out installs on a fresh host. The lifecycle records the pack the config resolves to: when you create <policy_dir>/guardrail/default later, the next ensure applies the change and restarts the gateway with that pack. Setting rule_pack_dir to the folder you want is clearer and has the same effect. The lifecycle refuses a value that names a folder that does not exist, or one inside data_dir. See Custom rule packs.
  • Windows: when you leave the key out, the gateway uses <policy_dir>/guardrail/default if you set policy_dir outside data_dir, and otherwise the built-in packs. Setup loads every rule pack the config names before it changes anything, and refuses with 1639 a directory that does not exist or that the gateway cannot load.

The whole enterprise block is refused unless deployment_mode is managed_enterprise. In the Secure Client profile the block may contain only profile.

Choose the agents to protect

List each agent under guardrail.connectors. The key is the connector name; the value can be empty ({}) or override guardrail settings for that agent. A config without this map protects nothing.

guardrail:
  enabled: true
  mode: observe          # observe | action (default observe)
  connectors:
    codex: {}            # machine policy
    claudecode: {}       # machine policy
    cursor: {}           # machine policy
    copilot: {}          # machine policy
    devin: {}            # per user
    opencode:
      mode: action       # this agent blocks; the others only observe

• guardrail.mode. observe inspects every call and logs the verdict without blocking. action blocks what policy denies. The default is observe. A connector's own mode overrides the global value for that agent.
• Routes. Each connector is protected in one of three ways. See Machine policy for the full table.

openclaw and zeptoclaw need the guardrail proxy, which a managed host does not run, so they are not managed: Linux and macOS skip them (route unsupported), and Windows writes no targets for them.

Per-user enrollment also depends on the enrollment settings and on a supported version of the agent being installed for that user.

The older single-agent key guardrail.connector also selects an agent. Use the map instead.

Settings reference

This table lists every key under enterprise. An unset key takes the default shown. "Linux and macOS" means the key has no effect on Windows.

Payload trust

How the lifecycle verifies the payload is chosen at the entry point:

On Windows, enterprise.trust in the config then narrows what the standalone lifecycle accepts. It is read from the config you supply, or, for an install, upgrade, repair or ensure without one, from the installed config:

• mode: authenticode admits only Authenticode-signed payloads. The lifecycle refuses with 1639, before any change, a hash-pinned run (such as the unsigned DefenseClawSetup-Enterprise-Standalone-x64.exe, which passes --trust-mode hash_pinned), and any install, upgrade, repair or ensure over a deployment that was installed hash-pinned. Such a deployment keeps admitting its installed payload by the SHA-256 pins it recorded, so it stays hash-pinned. To move it to authenticode, remove it with uninstall --purge and install a signed Setup.
• mode: hash_pinned, like an unset mode, is the minimum: it admits the unsigned payload by its pins, and a signed payload is still verified by its signature. It does not refuse a signed Setup. Use it, or leave mode unset, while you deploy unsigned builds. An empty mode: "" is the same as an unset mode.
• allowed_signers restricts signed payloads to the listed signer certificates, like --allowed-signer. When both are given they must list the same thumbprints, or the run stops with 1639.

Linux and macOS accept and validate enterprise.trust but do not use it: their MDM wrapper checks the package (table above).

disable_self_update

enterprise.coexistence.disable_self_update controls only the Windows HKLM\SOFTWARE\Policies\Cisco\DefenseClaw\DisableSelfUpdate policy value. When the key is true and the value is absent, the lifecycle sets it to 1 and records that it did. It removes the value later only if it set it, so an existing Group Policy value is never changed. The value also stops the per-user install.ps1 on that computer.

Setting the key to false does not bring back update notices or defenseclaw upgrade on any OS. On every host with a managed deployment the update notice stays off, and the per-user installer, the per-user upgrade and rollback commands and a per-user gateway refuse to run, whatever this key says. See Per-user installs.

managed_hooks_only on Windows

Codex always gets its lock on Windows, whatever the key says. Claude Code's Windows drop-in follows the key as on Linux and macOS: enforce, the default, sets allowManagedHooksOnly: true, and preserve leaves the lock out. The key also decides whether the foreign-hook guard covers Codex and Claude Code, on Windows as elsewhere. See Machine policy.

Custom rule packs

The gateway ships three rule packs, default, strict and permissive, under /opt/defenseclaw/share/policies/guardrail on Linux and /opt/cisco/defenseclaw/share/policies/guardrail on macOS. To use your own rules on Linux and macOS:

1. Create the pack in the administrator policy folder, as root: /etc/defenseclaw/policies/guardrail/<name> on Linux, /opt/cisco/defenseclaw/etc/policies/guardrail/<name> on macOS. Start from a copy of a shipped pack. Keep every file and folder owned by root, not writable by group or others, and readable by the gateway (for example 0644 files in 0755 folders). The lifecycle refuses a pack inside data_dir, which the gateway can write.

2. Name the folder for the block threshold you want. The pack folder's name selects the thresholds: strict blocks findings of MEDIUM severity and above, permissive only CRITICAL ones, and any other name, default included, CRITICAL ones.

3. Validate the pack with the gateway's own loader:

   sudo /opt/defenseclaw/bin/defenseclaw-gateway rulepack validate --dir /etc/defenseclaw/policies/guardrail/strict

   On macOS the binary is /opt/cisco/defenseclaw/bin/defenseclaw-gateway. --json prints a versioned result. Enterprise packages ship no defenseclaw CLI, so defenseclaw guardrail validate-pack and defenseclaw setup guardrail from the per-user workflow are not available.

4. Point the config at it with guardrail.rule_pack_dir (or guardrail.connectors.<name>.rule_pack_dir for one agent) and apply the config with ensure --config or through your MDM. The lifecycle refuses a rule_pack_dir that does not exist and restarts the services with the new pack. If the gateway cannot load it, ensure fails and the previous config stays in force.

To change a pack that is in use, the safest route is the same as for a new one: create the edited copy in a new folder that keeps the threshold name (for example /etc/defenseclaw/policies/guardrail-v2/strict), validate it, and switch rule_pack_dir to it, so ensure applies it with rollback. If you edit the files in place instead, validate them and restart the managed gateway: ensure does not track the files under policies, and the gateway reads the pack only when it starts.

Network proxy

enterprise.network sets an outbound proxy for the gateway.

enterprise:
  network:
    https_proxy: http://proxy.corp.example.com:3128
    no_proxy: .corp.example.com,10.0.0.0/8

With https_proxy set, the gateway reaches Cisco AI Defense, LLM providers (the judge and the guardrail proxy), the LLM passthrough, webhooks, the remote model router and the telemetry exporters (OTLP over HTTP and gRPC, Splunk HEC, HTTP JSONL) through the proxy. It opens an HTTP CONNECT tunnel to the destination host name, so the proxy's host rules apply and TLS stays end to end. The gateway's other HTTPS clients take the proxy from HTTPS_PROXY, https_proxy, NO_PROXY and no_proxy:

• https_proxy must be http:// or https:// with a host and optional port. A user name, password, path or query is refused.
• LLM provider calls need an http:// proxy URL. With an https:// URL the gateway refuses those calls rather than connecting directly; the other destinations work with either.
• no_proxy lists hosts, domains and CIDR ranges that connect directly. Loopback destinations always connect directly.
• Webhook, passthrough and telemetry destinations still pass the gateway's address check first, so their host names must resolve on the device.
• The gateway reads enterprise.network only when it starts. A config reload that changes it is reported as restart-required, and the gateway keeps the previous proxy until it restarts. On Linux and macOS, a lifecycle run that applies the changed config restarts the services.
• When https_proxy is empty, the AI Defense client uses the process environment's proxy variables, if any.
• The MDM wrapper's --https-proxy (Linux and macOS) is used only to download the package. It does not configure the gateway.

Observability credentials

A telemetry destination under observability.destinations often needs a credential, such as a Galileo API key or a Splunk HEC token. In the standalone profile, store it as a protected credential, like the AI Defense key, and reference it by name. Do not reference an environment variable: the gateway service does not get the variables of an administrator's shell, so {env: NAME}, token_env and bearer_env do not work in this profile.

NAME follows the credential name rules of the AI Defense key: lowercase letters, digits and dashes, starting with a letter or digit. A destination sets either the credential field or the environment field, not both.

1. Store the credential, the same way as the AI Defense key (see Store the key for macOS, Windows and --from-file). On Linux:

   read -rs GALILEO_API_KEY
   printf '%s' "$GALILEO_API_KEY" | sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise secret set --name galileo-api-key --from-stdin
   unset GALILEO_API_KEY

   enterprise secret set needs an installed deployment. On a new host, install with a config that does not reference the credential yet, or with the destination set to enabled: false, which resolves no credentials.

2. Reference it in the config and apply the config as usual:

   observability:
     destinations:
       - name: galileo
         kind: otlp
         preset: galileo
         protocol: http/protobuf
         endpoint: https://api.galileo.ai/otel/traces
         headers:
           Galileo-API-Key: {credential: galileo-api-key}
           project: defenseclaw
           logstream: production

The gateway reads the credential the same way as the AI Defense key: through systemd LoadCredential= on Linux with systemd 247 or later, through its group from the root-owned file on older Linux and on macOS, and as its service identity on Windows. The value never appears in the config, the effective configuration, status output or logs.

Before it applies a config, the lifecycle checks that every credential an enabled destination references is stored and passes the file checks in Where the key is stored. Otherwise it refuses the config, names the credential and the destination field, and keeps the running config. enterprise secret remove likewise refuses a credential that an enabled destination of the installed config still references, because the gateway could not start without it: remove the reference and apply the config first. To rotate a credential, run enterprise secret set again with the same name. Outside the standalone profile a credential reference never resolves, so a config with an enabled destination that uses one is refused.

Sample configs

Each sample is an observe-mode starter: it inspects Codex, Claude Code, Cursor and Copilot (and OpenCode on Linux and macOS), logs every verdict and does not block on policy verdicts. Change guardrail.mode to action when you are ready to block.

config_version: 8
deployment_mode: managed_enterprise
data_dir: /var/lib/defenseclaw          # must be exactly this path
policy_dir: /etc/defenseclaw/policies
gateway:
  api_bind: 127.0.0.1
  api_port: 18970
guardrail:
  enabled: true
  mode: observe                         # observe logs verdicts; action blocks
  rule_pack_dir: ""                     # the built-in rule packs
  connectors:                           # the agents to protect
    codex: {}
    claudecode: {}
    cursor: {}
    copilot: {}
    opencode: {}
enterprise:
  profile: standalone
  inspection:
    ai_defense:
      enabled: false                    # true after you store the key
      credential: ai-defense-api-key
  enrollment:
    mode: auto
    exclude_users: []
    unenrolled_users: inspect
    root: inspect
  machine_policy:
    default:
      ownership: merge
      managed_hooks_only: enforce
      foreign_hooks: remove
      higher_precedence_sources: fail
  coexistence:
    disable_self_update: true
  network:
    https_proxy: ""
    no_proxy: ""

config_version: 8
deployment_mode: managed_enterprise
data_dir: /opt/cisco/defenseclaw/runtime    # must be exactly this path
policy_dir: /opt/cisco/defenseclaw/etc/policies
gateway:
  api_bind: 127.0.0.1
  api_port: 18970
guardrail:
  enabled: true
  mode: observe                             # observe logs verdicts; action blocks
  rule_pack_dir: ""                         # the built-in rule packs
  connectors:                               # the agents to protect
    codex: {}
    claudecode: {}
    cursor: {}
    copilot: {}
    opencode: {}
enterprise:
  profile: standalone                       # macOS otherwise means Secure Client
  inspection:
    ai_defense:
      enabled: false                        # true after you store the key
      credential: ai-defense-api-key
  enrollment:
    mode: auto
    exclude_users: []
    unenrolled_users: inspect
    root: inspect
  machine_policy:
    default:
      ownership: merge
      managed_hooks_only: enforce
      foreign_hooks: remove
      higher_precedence_sources: fail
  coexistence:
    disable_self_update: true
  network:
    https_proxy: ""
    no_proxy: ""

config_version: 8
deployment_mode: managed_enterprise
gateway:
  api_bind: 127.0.0.1
  api_port: 18970
guardrail:
  enabled: true
  mode: observe                         # observe logs verdicts; action blocks
  rule_pack_dir: ""                     # the built-in rule packs
  connectors:                           # the agents to protect
    codex: {}
    claudecode: {}
    cursor: {}
    copilot: {}
enterprise:
  profile: standalone                   # Windows otherwise means Secure Client
  inspection:
    ai_defense:
      enabled: false                    # true after you store the key
      credential: ai-defense-api-key
  enrollment:
    include_users: []                   # empty: every eligible profile
    exclude_users: []
  machine_policy:
    default:
      foreign_hooks: remove
  coexistence:
    disable_self_update: true

On Windows, keep the file as your input to ensure, not as a hand-edited copy under C:\ProgramData. Deliver it as shown in Deliver the config.

Next steps