Plan a rollout

This page walks through a rollout of the standalone profile to a large, mixed fleet, for example 5,000 Windows, Linux, and macOS endpoints. It tells you what to decide and in which order. The install pages and the MDM recipes have the exact commands.

Before you start

Collect the release files for each OS:

DefenseClawSetup-Enterprise-x64.exe is the Secure Client Setup, not the standalone one. The MDM scripts that wrap these files live in packaging/mdm in the repository; Install with an MDM explains them.

Step 1: Choose the agents

List every agent you want to protect under guardrail.connectors in the config. Each key turns that agent on. On Linux and macOS, the config the lifecycle writes when you supply none lists no agents, so it protects nothing. On Windows, install and ensure require a config.

guardrail:
  enabled: true
  mode: observe
  connectors:
    codex: {}
    claudecode: {}
    cursor: {}
    copilot: {}

How each agent is protected depends on the agent and the OS:

Machine-policy agents give the strongest protection: users cannot edit the vendor's policy files, and where DefenseClaw sets the vendor's managed-hooks-only lock, the agent ignores hooks that users add. Machine policy shows which lock is set on which OS. Choose the agents to protect has the full rules.

Step 2: Choose the users

The enumerator decides which users are enrolled. It enrolls a user for an agent only after it finds a supported install of that agent for that user, and it checks again every five minutes. The settings live under enterprise.enrollment and behave differently per OS:

Three cases to plan for:

• Linux directory accounts. SSSD and Active Directory often map users to user IDs above 60000. The UID_MAX cap does not apply to them, so they are enrolled like local users. Set uid_max only if you want to cap directory and local accounts alike. Check a user's ID on a pilot host with getent passwd <user> or id -u <user>.
• One config for several OSes. Windows applies include_groups and exclude_groups too. A Linux group name such as wheel in include_groups does not resolve on Windows, so a new Windows user that no other entry admits stays pending: they get no rows, and their machine-policy calls are refused. Name groups that exist on every OS the config reaches (or by SID on Windows), or use separate configs.
• Windows exclusions. On Windows, excluding a user does not leave them unprotected: their calls through a machine-policy agent are refused. Exclude only accounts that do not run the protected agents. To keep an account working without per-user registrations, list it in exempt_users instead: it keeps its machine-policy rows and is inspected and logged.

Enrollment has every setting.

Step 3: Pilot in observe mode

Pick a pilot ring of a few dozen endpoints that covers every OS, every agent you chose, and some IT staff. Deploy with guardrail.mode: observe. In observe mode policy verdicts never block: DefenseClaw records every decision, including what it would have blocked. The deployment's own checks still apply: a tool call is refused while an unapproved foreign hook is present (with foreign_hooks: remove), or when the user is not enrolled where enrollment is enforced.

1. Install. Run the MDM recipe for each OS. Every run ends with an exit code: 0 on success on every OS. The failure codes are 1, 2 and 75 on Linux and macOS, and 1603, 1618 and 1639 on Windows. See 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 that the users you expect appear for each agent. The enumerator runs every five minutes, so allow a few minutes after a user first installs an agent.
4. Read the decisions. Let people work for a week or two. Review what DefenseClaw would have blocked (Logs and events), and tune policy for legitimate work that it flags.
5. Switch to action mode. Set guardrail.mode: action in the config and deliver it again. You can switch one agent first by setting mode: action under its guardrail.connectors entry. Change the config shows how the change reaches each OS.

Step 4: Handle existing per-user installs

Some users may already run the ordinary per-user DefenseClaw. On a managed computer, the per-user installer (install.sh, install.ps1), defenseclaw upgrade, and the per-user gateway refuse to run.

There is no automatic migration in this release. enterprise.coexistence.per_user_install is reserved: it is accepted and validated but has no effect. Remove per-user installs yourself, before the managed install reaches a computer:

1. Find them. A per-user install lives in the user's home, in ~/.defenseclaw (%USERPROFILE%\.defenseclaw on Windows), with its programs in ~/.local/bin.

2. As that user, remove it. This removes the connector hooks and the programs and keeps the user's data:

   defenseclaw uninstall --binaries --yes

   To remove the data in ~/.defenseclaw as well:

   defenseclaw uninstall --all --binaries --yes

   The commands are the same in PowerShell on Windows.

3. Then deploy the managed install.

A per-user gateway listens on the same loopback port as the managed gateway, 127.0.0.1:18970, which is why you remove the per-user install first.

On Linux and macOS, --adopt-existing covers a different case: DefenseClaw files at the managed paths that no committed deployment owns, such as an earlier manual deployment. install and ensure refuse to run over them unless you pass --adopt-existing, which archives them into the lifecycle directory and takes over. It does not touch per-user installs in users' homes. See Per-user installs on each install page.

Step 5: Expand in rings

Grow the deployment in rings and move on only when a ring is healthy. A possible plan for 5,000 endpoints:

Watch these on every ring:

• MDM detection. The detection script reports the installed version and, optionally, health (Detection).
• Health fields. coverage_complete and security_complete in the lifecycle result (Health fields).
• Enrollment counts in status, against the users you expect.

Two Windows cases keep security_complete at false on a healthy install:

• Windows requires at least one of Codex, Claude Code, or Cursor to be turned on. A Windows deployment that protects only per-user agents or GitHub Copilot reports false.
• With Claude Code turned on, security_complete stays false until an administrator confirms, in a real Claude Code session, that DefenseClaw's managed policy is in effect, and records it with the Windows lifecycle's repair --attest-claude-effective-policy. See Health fields.

Plan for them so a false there does not stop the rollout by mistake. Every other false needs a look.

Step 6: Plan upgrades and rollback

Decide how new releases reach the fleet before the first ring goes out. The same rings work for upgrades: run ensure with the new release on the pilot ring first. On Linux and macOS the package manager, or ensure with a newer payload, upgrades in place. On Windows, ensure with the new Setup program upgrades and refuses to install an older version over a newer one.

Lifecycle covers upgrade, roll back, changing the config, repair, and uninstall.