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

NeedDetails
Administrator rightsYour MDM runs commands as SYSTEM on Windows and as root on Linux and macOS
WindowsA machine-wide PowerShell 7, deployed first (requirements)
Linuxsystemd 239 or later and a .deb or .rpm distribution (requirements)
macOSApple silicon, macOS 13.0 or later (requirements)
AgentsA version the connector page supports, installed for each user who runs it
Cisco AI Defense keyOptional (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 signed checksums.txt, checksums.txt.bundle and 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 upgrade and defenseclaw rollback refuse (Managed command availability). Your MDM delivers each release, pinned by its SHA-256 from a checksums.txt that 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.

config.yaml (excerpt)
guardrail:
  enabled: true
  mode: observe
  connectors:
    codex: {}
    claudecode: {}
    cursor: {}
    copilot: {}
AgentsHow
Codex, Claude Code, Cursor, GitHub Copilot, OpenCodeMachine policy: applies to every user of the computer
Devin, Antigravity, Hermes, Amp, KiroPer-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_MAX cap does not apply to them; set uid_max only to cap both.
  • One config for several OSes. A Linux group name such as wheel does 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.

  1. Install with the MDM recipe for each OS. Success is 0; failures are 1, 2, 75 (Linux, macOS) or 1603, 1618, 1639 (Windows) (Exit codes).
  2. Check health. Run status and verify on a few hosts and read coverage_complete and security_complete (Status and verify).
  3. 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.
  4. Read the decisions for a week or two (Logs and events) and tune the policy for legitimate work it flags.
  5. Switch to action mode. Set guardrail.mode: action and deliver the config again, or set mode: action for 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:

  1. Find them: ~/.defenseclaw (%USERPROFILE%\.defenseclaw on Windows), programs in ~/.local/bin.
  2. As that user, run defenseclaw uninstall --binaries --yes (add --all to 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.
  3. 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.

RingEndpointsModeMove on when
PilotAbout 50 (1%), every OS and agentobserveEvery install exits 0, verify passes, decisions reviewed
EarlyAbout 500 (10%)observe, then actionNo unexpected blocks for a week in action
BroadAbout 2,000 (40%)actionDetection and health stay green
EveryoneThe restaction

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.