Enterprise deployment
What DefenseClaw enterprise hardening is, which profile to choose, what runs on each endpoint, and what a standard user can and cannot change on Windows, Linux, and macOS.
Enterprise deployment installs DefenseClaw as operating-system services that administrators own. Users, and the agents they run, cannot stop the services or change the policy.
Is this for you?
One person, one computer: use the open-source install (Quickstart).
A fleet your IT team manages: use enterprise deployment. You need an MDM,
configuration-management tool or administrator shell that runs commands as SYSTEM or
root, and agents that run as standard users. In the config it is
deployment_mode: managed_enterprise (definition).
Ready? Deploy to a fleet has six steps.
Two profiles
| Detail | Standalone | Secure Client |
|---|---|---|
| Choose it when | You deploy with an MDM, package or admin shell | You run Cisco Secure Client |
| Platforms | Windows, Linux, macOS | Windows, macOS |
| Who decides | The local policy engine, plus Cisco AI Defense when you store a key | Cisco AI Defense only |
| Documented in | This section | Secure Client |
One profile per computer, fixed at install (enterprise.profile and
DEFENSECLAW_ENTERPRISE_PROFILE must agree). With neither set, Windows and macOS use
secure_client and Linux uses standalone, so set enterprise.profile: standalone
on Windows and macOS.
The rest of this section covers the standalone profile.
What runs where
Every endpoint runs four services and one program: the gateway decides on each tool call, the guardian repairs each user's hooks, the enumerator finds the users, and the sensor helper answers discovery questions. The hook is an administrator-owned program the agent runs as the user.
List view for small screens. Use the expand button to open the drawing.
TrustedZ0 · Admin (root · SYSTEM)
- MDM or adminruns the lifecycle
- installsGuardianZ1
- writesConfig and policyZ3
- writesAgent machine policyZ3
PrivilegedZ1 · Services
- Guardiankeeps hooks in place
- adds hooks, as the userAI agentZ4
ProtectedZ3 · Admin-owned files
- Config and policysecrets
- read byGatewayZ2
- Agent machine policyCodex · Claude Code
- registers hooksAI agentZ4
UntrustedZ4 · User session (the user)
- AI agentruns as the user
- runsdefenseclaw-hook
- defenseclaw-hookruns on each hooked tool call
- asks · caller checkedGatewayZ2
RestrictedZ2 · Gateway (service account)
- Gatewayallows or blocks
How far the hook reaches depends on the connector. Claude Code, Codex, Cursor, GitHub
Copilot and OpenCode load DefenseClaw's hooks from administrator-owned machine policy,
so a supported client starts with them. Per-user connectors (Devin, Antigravity, Hermes,
Amp, Kiro) are registered only in the agent's default config: a session started with
another config home, devin --config <file> or Hermes --safe-mode has no hook
inspection for its tool calls. Managed status and verify report a running bypass and
write an audit alert. The threat model lists each case.
The gateway listens on 127.0.0.1:18970; the guardian reconciles every minute and the
enumerator runs every five. Service names per OS are in
Concepts, and the files in each zone
in the threat model and the install pages
(Windows,
Linux,
macOS).
Who can change what
Administrators and the MDM write the config, policies, secrets, binaries, services and
vendor machine policy. A standard user, and any agent they run, can write none of them;
an agent with unrestricted sudo or administrator rights is an administrator. The
guardian repairs DefenseClaw's entries in each user's agent config, and the
foreign-hook guard handles hooks a user adds. The
threat model lists
what a standard user cannot do and the risks that remain.
Policy changes on a managed host
On a managed standalone host, config.yaml and the policy assets it names are
the only policy. Only the lifecycle (and a migration it runs) writes the config.
Under the Secure Client profile none of this applies. The model is in
Configuration: one source of truth.
On Linux and macOS the enterprise package installs defenseclaw as a launcher
that runs only the commands in
Managed command availability. Every other command prints this and exits 2:
This computer is managed; use `defenseclaw status` for your protection state, `defenseclaw sandbox status` for your sandboxes and `defenseclaw sandbox policy explain` for your policy. For administrator views, run `sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status`, `sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify`, or `sudo /opt/defenseclaw/bin/defenseclaw-gateway audit export --since 2h`. The managed launcher does not offer doctor, alerts, or tui.
This computer is managed; use `defenseclaw status` for your protection state, `defenseclaw sandbox status` for your sandboxes and `defenseclaw sandbox policy explain` for your policy. For administrator views, run `sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status`, `sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos verify`, or `sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway audit export --since 2h`. The managed launcher does not offer doctor, alerts, or tui.The first message is the Linux text and the second is the macOS text; the administrator-view commands name the installed gateway of that platform.
Windows has no launcher: defenseclaw.exe there is the administrator command. Setup puts no DefenseClaw command on PATH, so run it by its full path: & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' ... in PowerShell, or "C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe" ... in cmd.exe. It refuses the per-user writers itself:
| Attempt on managed Windows | Result |
|---|---|
config set, config unset | Exit 3: This device is managed: change config.yaml in the admin config (MDM or management plane); config set did not change it |
skill, mcp, plugin or tool with block, allow or unblock | Exit 3, naming the asset_policy key in the admin config and saying the command did not change it |
init, quickstart, guardrail, policy activate | Exit 2: not a command of the administrator's defenseclaw.exe |
A standard account's & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' status (and status --json) shows that
account's own Claude Code and Cowork protection state and its own last Cowork
event, which the gateway service reads for the account that asks, never
another account's. From an elevated prompt status names the administrator's
enterprise windows status --profile standalone.
The table below is for a per-user CLI left from an earlier install on Linux and macOS.
Local writers refuse
A per-user Python CLI left from an earlier install also finds the host managed. It refuses these attempts, also for root, and writes nothing:
| Attempt | Result |
|---|---|
defenseclaw config set KEY VALUE, config unset KEY | Exit 3: error: This device is managed: change config.yaml in the admin config (MDM or management plane), not on the device |
defenseclaw skill, mcp, plugin or tool with block, allow or unblock | Exit 3: This device is managed: the asset_policy block and allow lists are set in the admin config (MDM or management plane) |
defenseclaw init, defenseclaw quickstart, and any command that needs a per-user config | Exit 3: This device is managed: DefenseClaw is configured by your administrator (MDM or management plane), so there is no per-user config to create and 'defenseclaw init' does not apply. Nothing was changed. |
guardrail block-at, policy activate, the setup commands that write config, the TUI config editor | Refused by the same writer. The TUI shows Config save failed: and the message |
POST or DELETE on the gateway's /enforce/block, POST on /enforce/allow | HTTP 403 with {"error": "managed_device", "detail": "policy changes are made in the management plane"} |
The gateway records each refusal in the audit log with
outcome=refused reason=managed_device. On Linux and macOS the launcher (for
config, guardrail, policy and asset writers, setup, upgrade,
rollback and uninstall) and the CLI report through the hook socket, so a
standard user's refusal is recorded with the account the kernel reports
(actor=uid:501 user=alice). On Windows defenseclaw.exe reports its refusals
on the gateway's refusal pipe, which names the account from its Windows token
(actor=sid:S-1-5-21-... user=HOST\alice); a standard account's enterprise windows lifecycle command is recorded with reason=elevation_required
(Windows).
To block or allow an asset, add it to asset_policy in the admin config and
apply the config:
asset_policy:
skill:
denied:
- name: acme-unapproved-skill
reason: not approvedRuntime actions stay allowed
Quarantine and restore, runtime disable and enable, approvals (HITL) and discovery are runtime state, not policy.
The environment cannot weaken the host
Every DEFENSECLAW_* variable
has a managed setting in the registry. ignore
variables read as unset, from the process environment and from .env files.
tighten_only variables (DEFENSECLAW_STRICT_AVAILABILITY and
DEFENSECLAW_MANAGED_TRUST_STRICT_ANCESTORS) count only
when they make the setting stricter. Managed hooks ignore DEFENSECLAW_HOOK_MAX_BODY
and keep their fixed 1 MiB body cap. allow variables are read as set. A
forged DEFENSECLAW_DEPLOYMENT_MODE or DEFENSECLAW_ENTERPRISE_PROFILE
cannot make the host look local: the host is managed because config.yaml
says so. Hook fail mode comes only from installed policy; the agent environment cannot change it. defenseclaw doctor names ignored variables, never their values.
Local block and allow rows are ignored
The gateway decides from
asset_policy, not from the actions table of audit.db. When ensure
migrates a config on a host that holds such rows, it adds the warning
local_enforcement_entries_ignored.
Supported platforms and agents
Windows x64 (PowerShell 7 required), Linux with systemd 239 or later, and macOS 13 or later on Apple silicon (requirements). Agents are protected through machine policy (Claude Code, Codex, Cursor, GitHub Copilot, OpenCode) or per user (Devin, Antigravity, Hermes, Amp, Kiro). OpenClaw and ZeptoClaw are not supported. See the support matrix.
A minimal config
The administrator config is one YAML file. This one protects Codex and Claude Code
in observe mode. Where it goes on each OS, and every enterprise.* setting, are in
Configuration.
config_version: 9
deployment_mode: managed_enterprise
# data_dir: Linux /var/lib/defenseclaw, macOS /opt/cisco/defenseclaw/runtime,
# Windows leave unset. The path is fixed.
enterprise:
profile: standalone
gateway:
api_bind: 127.0.0.1
api_port: 18970
guardrail:
enabled: true
mode: observe # observe | action
connectors:
codex: {}
claudecode: {}Nothing is protected until you list agents under guardrail.connectors. Observe mode
records every decision without blocking on policy verdicts; set mode: action to
enforce. The AI Defense key never goes in the config
(Cisco AI Defense key).
Next steps
Deploy to a fleet, Plan a rollout, Install on one computer and the threat model.
Add a connector without losing audit history
Use defenseclaw setup <connector> to add or reconfigure agent wiring while preserving audit history for every connector.
Deploy to a fleet
The six steps to deploy DefenseClaw enterprise to managed Windows, Linux and macOS endpoints, from choosing a profile and agents to your MDM recipe, config, ensure and a ringed rollout.