Plan a rollout
Plan a DefenseClaw enterprise rollout. Choose agents and users, pilot in observe mode, remove per-user installs, and expand in rings.
Roll out the standalone profile to a large, mixed fleet, for example 5,000 Windows, Linux and macOS endpoints. This page says what to decide and in which order. The install pages and the MDM recipes have the commands.
Before you start
| Need | Details |
|---|---|
| Administrator rights | Your MDM runs commands as SYSTEM on Windows and as root on Linux and macOS |
| Windows | A machine-wide PowerShell 7, deployed first (requirements) |
| Linux | systemd 239 or later and a .deb or .rpm distribution (requirements) |
| macOS | Apple silicon, macOS 13.0 or later (requirements) |
| Agents | A version the connector page supports, installed for each user who runs it |
| Cisco AI Defense key | Optional (key) |
The release files for each OS are listed in What you deliver.
DefenseClawSetup-Enterprise-x64.exe is the Secure Client Setup; use the
-Standalone- one.
Agents with administrator rights
DefenseClaw does not defend a computer from its administrators. An agent that runs
with unrestricted sudo or administrator rights can remove it. Keep agents on
standard accounts.
Where releases come from
One workflow publishes every release: the Release workflow of the DefenseClaw
repository, run on main. It signs checksums.txt with cosign (a keyless signature,
stored as checksums.txt.bundle) under the identity
https://github.com/cisco-ai-defense/defenseclaw/.github/workflows/release.yaml@refs/heads/main
and the issuer https://token.actions.githubusercontent.com. The installers and
defenseclaw upgrade compile that identity in; no config key or environment
variable changes it.
update.source(https://only) changes only where release bytes are fetched. A mirror must serve the same signedchecksums.txt,checksums.txt.bundleand files, unchanged, and the tools need cosign 2.0 or later.- The checksum-only fallback exists only for the official source.
- Managed hosts do not update themselves:
defenseclaw upgradeanddefenseclaw rollbackrefuse (Managed command availability). Your MDM delivers each release, pinned by its SHA-256 from achecksums.txtthat you verified once (hash-pinned trust).
Step 1: Choose the agents
List every agent to protect under guardrail.connectors. Each key turns that agent
on; with none, nothing is protected. A key that names no DefenseClaw connector (a
misspelled agent) is refused before anything changes: Linux and macOS ensure
stop with config_invalid and name the key; Windows Setup refuses it the same way.
guardrail:
enabled: true
mode: observe
connectors:
codex: {}
claudecode: {}
cursor: {}
copilot: {}| Agents | How |
|---|---|
| Codex, Claude Code, Cursor, GitHub Copilot, OpenCode | Machine policy: applies to every user of the computer |
| Devin, Antigravity, Hermes, Amp, Kiro | Per-user: the guardian writes and repairs each enrolled user's config |
Machine-policy agents give the strongest protection: users cannot edit the vendor's policy files, and where DefenseClaw sets the managed-hooks-only lock the agent ignores hooks users add (Machine policy). The full rules are in Choose the agents to protect.
Step 2: Choose the users
The enumerator enrolls a user for an
agent only after it finds a supported install of that agent for that user, and it
checks every five minutes. By default it picks interactive local and directory users
on Linux and macOS, and every interactive profile on Windows. Narrow the set with
enterprise.enrollment (include_users, exclude_users, group filters,
exempt_users); settings differ a little per OS
(What each OS honors).
- Linux directory accounts. SSSD and Active Directory often map users above
60000. The
UID_MAXcap does not apply to them; setuid_maxonly to cap both. - One config for several OSes. A Linux group name such as
wheeldoes not resolve on Windows, so a new Windows user that no other entry admits stays pending and its machine-policy calls are refused. Use groups that exist everywhere, SIDs on Windows, or separate configs. - Windows exclusions. An excluded Windows user is not left unprotected: their
calls through a machine-policy agent are refused. List accounts that must keep
working without registrations in
exempt_users; they are inspected and logged.
Step 3: Pilot in observe mode
Pick a pilot ring of about 50 endpoints that covers every OS, every chosen agent and
some IT staff, and deploy with guardrail.mode: observe.
- Install with the MDM recipe for each OS. Success is
0; failures are1,2,75(Linux, macOS) or1603,1618,1639(Windows) (Exit codes). - Check health. Run
statusandverifyon a few hosts and readcoverage_completeandsecurity_complete(Status and verify). - Check enrollment. Confirm the expected users appear for each per-user agent. A machine-policy-only Linux or macOS deployment can show an empty Enrollment section while its users are protected.
- Read the decisions for a week or two (Logs and events) and tune the policy for legitimate work it flags.
- Switch to action mode. Set
guardrail.mode: actionand deliver the config again, or setmode: actionfor one agent first (Change the config).
Step 4: Handle existing per-user installs
On a managed computer the per-user installer, defenseclaw upgrade and the per-user
gateway refuse to run (see Managed command availability). Nothing migrates a per-user install. Remove them before the
managed install reaches a computer:
- Find them:
~/.defenseclaw(%USERPROFILE%\.defenseclawon Windows), programs in~/.local/bin. - As that user, run
defenseclaw uninstall --binaries --yes(add--allto delete the data). On Windows always use--all --binaries --yes. If the user set up Claude Cowork, they also remove the DefenseClaw plugin in Claude Desktop (Customize > Plugins, then the ... menu on DefenseClaw, Remove); until then Cowork tool calls are blocked. - Deploy the managed install.
A per-user gateway listens on the managed port, 127.0.0.1:18970. If one still
holds it, the install on Linux and macOS stops with api_port_held, naming the
process. Stop it or move it, then run ensure again. On Linux and macOS
--adopt-existing covers a different case: DefenseClaw files at the managed paths
that no deployment owns (Linux).
Step 5: Expand in rings
Move on only when a ring is healthy.
| Ring | Endpoints | Mode | Move on when |
|---|---|---|---|
| Pilot | About 50 (1%), every OS and agent | observe | Every install exits 0, verify passes, decisions reviewed |
| Early | About 500 (10%) | observe, then action | No unexpected blocks for a week in action |
| Broad | About 2,000 (40%) | action | Detection and health stay green |
| Everyone | The rest | action |
Watch on every ring: MDM detection, coverage_complete
and security_complete (Health fields),
enrollment counts for per-user agents, and the effective policy digest (on Linux and
macOS it should match across hosts that got the same config;
digest).
On Linux computers that run Tetragon, kernel controls follow the same rings
(Tetragon on a Linux fleet).
Two Windows cases keep security_complete at false on a healthy install: no Codex,
Claude Code or Cursor turned on, and Claude Code on without the administrator's
attestation. On Linux and macOS a
healthy install keeps it at false with only hook_process_fail_open (for an enabled
Codex, Claude Code or other agent whose hook can let a call run) and, on Linux,
unprivileged_user_namespaces and unprivileged_ptrace while the kernel allows them.
Every other false needs a look.
Step 6: Plan upgrades and rollback
Run ensure with the new release on the pilot ring first. An upgrade keeps the
administrator config; ensure migrates an older config_version and keeps a backup
(details).
Lifecycle covers
upgrade,
roll back,
changing the config,
repair and
uninstall.
Next: Install with any MDM to deploy the pilot ring.
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.
Enterprise concepts
A glossary of the terms used in DefenseClaw's enterprise deployment docs, from profiles and the lifecycle to enrollment, machine policy, health fields, and the Windows, Linux, and macOS security terms.