Upgrade, repair and remove

Upgrade, roll back, change the config, repair, and uninstall a standalone DefenseClaw enterprise deployment on Windows, Linux, and macOS, with a decommission checklist.

Every change to a deployment goes through the lifecycle: the managed config, a protected credential or a new release. Standard users cannot make these changes.

Each mutating action is a transaction. It takes the lifecycle lock, records what it will change, applies the change, starts the services in order, verifies the result and rolls back if any step fails. A failed action has already restored the previous deployment; its result carries the error that caused the failure and, on Linux and macOS, a rolled_back warning. Look up the code in Troubleshooting.

On Linux and macOS, when the gateway fails to start during an install or upgrade, the result also carries a short excerpt of the gateway's own output (for example a rule pack that does not load), and the lifecycle keeps the captured output in last-activation-failure.log in the lifecycle directory (/var/lib/defenseclaw-enterprise on Linux, /opt/cisco/defenseclaw/lifecycle on macOS). Only root can read it; a rollback does not remove it, and a later run that commits a deployment does.

Only one lifecycle run works at a time. On Linux and macOS a run that finds another in progress waits 5 seconds and exits 75 (busy); --lock-wait <duration> (at most 15m) waits longer. The apply trigger waits up to 10 minutes, and so does any ensure --reason path without --lock-wait; the deb, rpm and pkg install scripts wait up to 8, so a change made during another run is applied after it. The deb and rpm removal scripts wait the same, and a removal that still finds the lock busy fails without deleting anything. On Windows a busy run exits 1618. MDM agents retry both.

A deb or rpm upgrade holds the apply trigger from before the package manager replaces any file until its postinstall has applied the package, so a config.yaml pushed before the package is applied by the new version. When the package run keeps the last applied config because it rejected config.yaml, the install output says so.

A config.yaml or credential written while a run holds the lock, or a run given --config, is applied by a follow-up transaction of that run (warning input_changed), so the later file is the one in force. When the run fails instead, the apply trigger runs ensure again once it ends, and only the edit the failed run checked is kept as rejected. On Linux, when the failed run is the apply trigger itself, a transient timer (defenseclaw-enterprise-apply-retry.timer) starts it again after 30 s, then 60 s and 120 s if the same config.yaml keeps failing. After the third retry the run warns retry limit reached; run ensure once the cause is fixed.

The examples use these paths:

OSCommand
Linux/opt/defenseclaw/bin/defenseclaw-gateway, as root
macOS/opt/cisco/defenseclaw/bin/defenseclaw-gateway, as root
WindowsThe standalone Setup, DefenseClawSetup-Enterprise-Standalone-x64.exe, or the installed C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe, from an elevated PowerShell

If you deploy through an MDM, the wrapper scripts run these same actions; see Upgrades, rollback and config changes.

Upgrade

On Linux and macOS, a user's sandbox daemon is not restarted while that user has a sandbox running; ensure reports "pending restart" and the launcher restarts an idle, outdated daemon on the next command. See Upgrade, roll back, uninstall.

Windows

Run the new release's Setup with /ensure. When the Setup is newer than the installed version, ensure upgrades in place and keeps the installed config unless you also pass CONFIG=. Setup accepts only absolute paths. For Intune, see Intune on Windows.

& 'C:\ProgramData\DefenseClaw-Staging\DefenseClawSetup-Enterprise-Standalone-x64.exe' /ensure JSON=1
$LASTEXITCODE

Linux

Upgrade with the channel you installed from. A host where the package owns the binaries refuses a payload upgrade (package_owned_binaries).

Debian and Ubuntu package
VERSION=X.Y.Z   # the release you deploy
sudo apt install "./defenseclaw-enterprise-${VERSION}-linux-amd64.deb"
RHEL package
VERSION=X.Y.Z   # the release you deploy
sudo dnf upgrade "./defenseclaw-enterprise-${VERSION}-linux-amd64.rpm"

The package's install script runs ensure --from-package and writes the result to /var/lib/defenseclaw-enterprise/last-package-result.json. The script never fails the package transaction, so read that file or run verify afterwards. A later ensure or repair that applies the deployment removes a failed result.

If the computer runs Tetragon, a release that changes a kernel control changes the digest that enterprise.tetragon.enforce_ack approves, so with mode: enforce every user falls back to monitor mode (kernel_enforce_ack_stale) until the approval matches: push the old and the new digest as a list while the rings upgrade (Upgrades).

For a payload archive, extract the new release into a root-only folder. On hosts without fapolicyd, run enterprise linux upgrade --payload after extraction. On hosts with fapolicyd, use the staged-payload trust and two-stage flow below.

Linux payload upgrade

Payload archive
VERSION=X.Y.Z   # the release you deploy
ARCH=amd64      # or arm64
PAYLOAD="/root/defenseclaw-enterprise-${VERSION}"
sudo install -d -o root -g root -m 0700 "$PAYLOAD"
sudo tar -xzf "defenseclaw-enterprise-${VERSION}-linux-${ARCH}.tar.gz" \
  -C "$PAYLOAD" --no-same-owner --no-same-permissions
sudo chmod -R go-w "$PAYLOAD"

Without fapolicyd:

sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux upgrade --payload "$PAYLOAD" --json

Run the new release's defenseclaw-gateway from the extracted folder. The payload must be owned by root and not writable by group or others, so extract it into a root-only folder, never a shared one such as /var/tmp. The folder must also allow execution: on a CIS host /tmp and /var/tmp are mounted noexec.

With fapolicyd, trust the staged payload before running its gateway. Add the entry for a new payload path; update an existing entry if you extracted again into that path or changed its files. Reuse the entry for an unchanged staged folder. The tarball steps give both staged trust commands. Then stage the upgrade without starting services, update the existing installed-tree trust entry, check execution as the service user, and start and verify:

sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux ensure --payload "$PAYLOAD" --no-start --json
sudo fapolicyd-cli --file update /opt/defenseclaw/ --trust-file defenseclaw && sudo fapolicyd-cli --update
sudo -u defenseclaw /opt/defenseclaw/bin/defenseclaw-gateway --version-json
sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux ensure --payload "$PAYLOAD" --json
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify --json

The fapolicyd update is asynchronous. If the service-user check is denied immediately after --update, retry it after fapolicyd finishes syncing; it must pass before the final ensure. Check that defenseclaw-gateway.service is active afterward.

macOS

Install the new .pkg. Its install script runs ensure --from-package. If the lifecycle fails, the script fails the installation, so your MDM reports it.

VERSION=X.Y.Z   # the release you deploy
sudo installer -pkg "./defenseclaw-enterprise-${VERSION}-darwin-arm64.pkg" -target /
sudo cat /opt/cisco/defenseclaw/lifecycle/last-package-result.json

The config after an upgrade

The administrator config is the policy; an upgrade keeps its intent. A config_version: 8 config that the previous release installed is migrated to config_version: 9 by the first ensure of the new release, on every OS. See What ensure does with the config, and Roll back for going back to a release that reads version 8.

Per-user credentials after an upgrade

An upgrade from a release in which every user of a connector shared one hook and telemetry credential gives each user credentials bound to their uid or SID, and the new gateway refuses the shared ones. On Windows the lifecycle restarts the guardian and waits for a fresh reconcile before it starts the new gateway; a user signed out during the upgrade is re-rendered at their next sign-in, and until then their managed hooks fail closed. On every OS, an agent that was already running keeps the telemetry credential it started with, the new gateway refuses it, and that agent's telemetry is lost until the agent is restarted.

On a managed Windows upgrade from 1.0.6, an administrator's owner write can remove the OWNER RIGHTS entry from an enrolled, signed-out account's .defenseclaw files. Setup restores that entry only for this upgrade case, when the account owns the files and their access lists match the exact owner-rewritten form. It opens the managed folder and its children without following junctions. The upgrade leaves Claude Code or Codex repair pending only when it can read their active machine registration and prove that its runtime is closed or has no selected generation, which makes the registered hook fail closed. status and verify name the account and the pending repair until sign-in. Missing registration, an open runtime, another owner, extra write permission, a link, or other untrusted state still refuses the upgrade. Correct the state, have the account sign in, and run Setup /ensure JSON=1 again.

An account with no active Windows session (signed out or disconnected) does not fail a managed Windows upgrade because the hooks of an earlier release (up to 1.0.6) still sit in its agent configuration. The guardian installs the new hooks only in the account's own session, so when an earlier release's hook lock names the target and a read-only check shows that the only difference from this release is the earlier render of the hook command, the connector is pending until the account signs in: status and verify show it as pending, and the previous release's DefenseClaw hook keeps running for that account until it signs in and the guardian updates it. That hook runs the same hook binary and arguments, so the gateway still decides its calls; it differs only when PowerShell runs in Constrained Language mode and the launcher never starts, where it allows the call (this release's hook refuses it). Any other difference (a deleted or replaced hook file, a link, another owner, a drifted runtime), a lock this release wrote, and an account with an active session whose repair fails still fail the upgrade. With the administrator's hook fail mode open, a signed-out Claude Code or Codex account whose machine registration is proven waits as well. For these two the machine hook is this release's own, so status and verify say that the machine hook is in place and the account's registration finishes when it signs in (the previous release's hook is what keeps running only for Copilot, Antigravity and Kiro); with fail mode closed they keep the closed-registration proof described above. When one account has connectors of several kinds, its reason names each group, for example devin: not guarded until this account signs in; copilot: the previous release's DefenseClaw hook keeps running until this account signs in and the guardian updates it.

Roll back

With bundle trust anchors, DefenseClaw refuses to install a release below the confirmed bundle's min_product_version: on Linux and macOS from 1.0.4, in Windows Setup from 1.0.6. The lifecycle reason is product_floor_refused, but an older package's preinstall does not necessarily print that code. The rollback marker, --allow-downgrade and uninstall --keep-state do not lift this floor. A package older than 1.0.4 does not check the floor itself and can complete below it. A floor that cannot be read refuses the install too. Check bundle status for current.min_product_version and install a release that meets it; to go below it, contact your administrator. A reinstall at the floor is allowed by this check, including 1.0.8 over 1.0.8 with a confirmed 1.0.8 floor. Release floor limits says when the floor is checked, where each installer reports a refusal, and what older packages and Windows Setup do.

A failed action rolls itself back. You only need the steps below to go back to an older release on purpose. Try the rollback on one test host before the fleet. Every lifecycle refuses an older release unless you ask for the rollback. Windows Setup stops with exit 1603 and the code downgrade_refused, and the macOS package records downgrade_refused in last-package-result.json. The Debian and RHEL packages start every refusal with its code (defenseclaw-enterprise: downgrade_refused: ... refusing to downgrade to <version>. Nothing was changed.) and exit with 1; rpm, dnf and apt show that text only, and last-package-result.json keeps the result of the package that is applied. rpm and dnf run the older package's own preinstall, so a package before 1.0.9 prints the same refusal without the code; the apt hook of the installed package names it for any older package. dpkg -i skips the apt hook, so dpkg -i of a package before 1.0.9 prints the refusal without the code. For an Intune Win32 deployment, remove the superseding Required assignment before assigning the older app; otherwise Intune can reapply the newer release.

Going back to a release that reads config_version: 8. An upgrade rewrites a version 8 config as version 9 in place, and an older release refuses that file. Give the older release your own version 8 config, or the copy the upgrade kept (config.yaml.v8.bak, root-only, next to the installed config). A release that reads version 9 needs no version 8 file.

OS and channelHow to go back
Windows/ensure refuses to install an older version (downgrade_refused, exit 1603). Run the older release's Setup with /upgrade CONFIG=<version 8 config> JSON=1: an explicit upgrade does not compare versions. A Setup before 1.0.4 tries once to replace the hook program, so while agents run hooks it can stop with 1603 and roll back to the installed release; run it again, or run it while agents are idle. A Setup before 1.0.7 replaces the programs in bin with a step that briefly leaves no startable hook, so an agent that starts a hook in that moment gets an error and runs that one tool call with no DefenseClaw decision; Setup 1.0.7 and later swap them in one step where the volume allows it (NTFS without a filter that refuses hard links); otherwise they keep the earlier step. The older release's Setup does the replacing on a rollback, so roll back while agents are idle. Uninstalling and installing the older release also works
Debian and UbuntuCreate the root-owned rollback marker, then install the older package: sudo touch /var/lib/defenseclaw-enterprise/allow-downgrade, then sudo apt install --allow-downgrades ./defenseclaw-enterprise-<older>-linux-amd64.deb. Its postinstall applies the installed config if compatible. If it refuses a version 9 config, finish with sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux ensure --from-package --allow-downgrade --config <version 8 config> --json
RHELCreate the same marker, then sudo dnf downgrade ./defenseclaw-enterprise-<older>-linux-amd64.rpm (rpm -U refuses an older package). If its postinstall refuses a version 9 config, use the same ensure --from-package --allow-downgrade --config <version 8 config> recovery
Linux payloadExtract the older release as in Linux payload upgrade, then follow Linux payload rollback for the fapolicyd or non-fapolicyd path
macOSCreate the root-owned rollback marker, then install the older package: sudo touch /opt/cisco/defenseclaw/lifecycle/allow-downgrade, then sudo installer -pkg ./defenseclaw-enterprise-<older>-darwin-arm64.pkg -target /. An older release that reads config_version: 9 applies the installed config and is done (last-package-result.json reads ok). Only a release that reads version 8 fails on the version 9 config; then run sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos ensure --from-package --allow-downgrade --config <version 8 config> --json
  • Windows rollback to 1.0.0–1.0.2 from an open-mode deployment: These published Setups cannot collect a runtime generation with hook_fail_mode: open; they may install the older version, then exit 1603 while retiring the previous journal. Before running the older Setup, save the current admin config. Set guardrail.hook_fail_mode and each guardrail.connectors.<name>.hook_fail_mode to closed in a compatible config, then apply it with the installed 1.0.4 Setup /ensure CONFIG=<closed config> JSON=1. Run that Setup's /verify JSON=1 and resolve any pending users before the rollback. Pass the same closed config to the older Setup /upgrade; that release cannot provide open-mode managed hooks. If the older Setup already committed with 1603 and reports a journal retirement error, run the 1.0.4 Setup /ensure CONFIG=<desired admin config> JSON=1; it recovers the committed journal and validates and collects the old generation. Do not delete the journal or runtime files by hand. Version 1.0.3 understands open-mode generations.
  • Windows rollback to 1.0.0–1.0.3 with Hermes users: Since 1.0.4, Setup adds fail_closed: true to the Hermes pre_tool_call hook. Releases 1.0.0 to 1.0.3 do not know that setting and read the hook as not their own. If a Hermes user is signed out when the older Setup /upgrade runs, /verify passes at first and then, within about ten minutes, exits 1603 (canonical hook matrix is absent, extra or stale target hermes@<SID>). It passes again once that user signs in, because the older guardian then rewrites the hook. To avoid the failure, roll back while Hermes users are signed in, or uninstall the newer release and install the older one: signed-out users then stay pending until they sign in, and /verify passes.
  • Windows rollback to 1.0.4 with a disconnected Hermes user: if a Hermes user's session is disconnected when the published 1.0.4 Setup /upgrade runs, /verify exits 1603 with one pending target for that account (canonical hook matrix is absent, a stale hermes@<SID> target) and coverage reads incomplete. The /verify result names the account, and it passes once that user reconnects. A user who is signed out is listed as pending and /verify passes. Roll back while Hermes users are signed in, or have them sign in again afterwards.
  • Windows rollback to 1.0.2 with Codex users: 1.0.5 registers the Codex hook in %ProgramData%\OpenAI\Codex\requirements.toml as a direct cmd.exe command. The published 1.0.2 Setup removes only its own form of that entry, so after the rollback the file holds both the 1.0.5 entry and the 1.0.2 entry. Both run the installed 1.0.2 hook: every Codex call is still decided and either entry can block it, but each Codex event runs the hook twice and writes two audit rows. A 1.0.2 /repair keeps both. Delete the 1.0.5 DefenseClaw hook group from that file by hand, or run a newer Setup's /ensure to go back to one entry.
  • Packages refuse an older release unless the root-owned marker exists, and the postinstall deletes the marker, so each rollback needs a new one. On Debian and Ubuntu use apt, not dpkg -i.
  • Rollback from 1.0.6 to 1.0.5 with OpenCode (tested on Linux): 1.0.6 registers the OpenCode plugin folder (share/opencode) in the managed OpenCode config (/etc/opencode/opencode.json, /Library/Application Support/opencode/opencode.json, %ProgramData%\opencode\opencode.json). 1.0.5 does not know that entry, and nothing of 1.0.6 runs during the rollback, so the entry stays next to 1.0.5's own defenseclaw.js entry. OpenCode V1 is still guarded by the defenseclaw.js entry and the file is otherwise harmless. 1.0.6 treats both entries as its own: its next ensure or repair, or an uninstall, rewrites the file to the single folder entry (or removes it) and keeps your own entries. Until then 1.0.5 can show the stale 1.0.6 OpenCode V1 warnings as agent_unprotected until its first scan. To clean the file by hand, delete the entry that ends in share/opencode.
  • Windows rollback from 1.0.6 to 1.0.4 or 1.0.5, then uninstall: 1.0.6 keeps the managed OpenCode plugin at C:\Program Files\Cisco\DefenseClaw\share\opencode\index.js. 1.0.4 and 1.0.5 use share\opencode\defenseclaw.js and do not know index.js, and nothing of 1.0.6 runs during the older Setup's /upgrade, so the file stays after the rollback. That older Setup's /uninstall then exits 1603 before it changes anything and names the file (refusing to remove unexpected file from managed install root: ...\share\opencode\index.js). Uninstall with the 1.0.6 or a later Setup instead: it removes the file and the share\opencode entry in %ProgramData%\opencode\opencode.json. To use the older Setup, move that one file out of C:\Program Files\Cisco\DefenseClaw, run its /uninstall again, and then delete the entry that ends in share\opencode from the OpenCode file (see the note above). Going forward to 1.0.6 again needs no step. Linux packages remove the file with the 1.0.6 package, and on macOS the 1.0.5 lifecycle removes it as a file the earlier release wrote, so neither has this leftover.
  • Rollback from 1.0.6 to 1.0.5 while a user runs OpenCode V2 (macOS pkg, Linux packages): 1.0.5 guards OpenCode V1 only and cannot be changed. During a package rollback only the older package's scripts run, so 1.0.6 cannot warn or stop it, and the root-owned marker is created by hand. After the rollback that user's OpenCode V2 runs unguarded, and on macOS 1.0.5 gives no warning for it (a Windows 1.0.5 reports agent_unprotected for such a user; Linux was not tested). Before you roll back, list the users who run OpenCode V2 (the opencode entries in status, npm ls -g @opencode/cli as each user) and have them put OpenCode V1 back (npm uninstall -g @opencode/cli && npm install -g opencode-ai@1.18), or accept that they run unguarded until you go forward again. Going forward again to 1.0.6 guards them without any other step.
  • Rollback to the published 1.0.2 (Linux packages): while the older package swaps the gateway, the 1.0.2 managed hook can take longer than 5 seconds to answer a call. In one RHEL test, 26 of 960 Claude Code and Codex calls did so, all during the package downgrade; each was still decided, and no call policy refuses was allowed. Releases from 1.0.3 answer or fail closed within 4 seconds. Roll back while agents are idle.
  • Rollback to 1.0.3 or 1.0.4 with a large audit store (Linux): When the 1.0.3 or 1.0.4 gateway first starts on a large audit store (/var/lib/defenseclaw/audit.db), it is busy with that store and does not answer hooks in time. On RHEL with a 1.4 GB store this lasted 3.5 to 7.5 minutes after dnf downgrade finished. Rolling back to the published 1.0.4 with a 1.5 GB store, it lasted about 4 minutes. Meanwhile managed hooks deny agent tool calls and prompts (the DefenseClaw gateway did not answer in time or the DefenseClaw gateway is not available), while enterprise linux status and verify say ok. Roll back while agents are idle, or tell users to retry once the gateway answers.

Linux payload rollback

After extracting the older payload, choose a config that its release reads. On a host without fapolicyd, run:

COMPATIBLE_CONFIG=/root/compatible-config.yaml  # set to a config the older release reads
sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux upgrade --payload "$PAYLOAD" --allow-downgrade --config "$COMPATIBLE_CONFIG" --json

On a host with fapolicyd, first trust the staged older payload. Add trust for a new payload path, update it if files at a trusted path changed, or reuse an unchanged entry as described in the tarball steps. Then stage the rollback without starting services, update the installed-tree entry, check execution as defenseclaw, and activate the older release:

COMPATIBLE_CONFIG=/root/compatible-config.yaml  # set to a config the older release reads
sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux ensure --payload "$PAYLOAD" --allow-downgrade --config "$COMPATIBLE_CONFIG" --no-start --json
sudo fapolicyd-cli --file update /opt/defenseclaw/ --trust-file defenseclaw && sudo fapolicyd-cli --update
sudo -u defenseclaw /opt/defenseclaw/bin/defenseclaw-gateway --version-json
sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux ensure --payload "$PAYLOAD" --allow-downgrade --config "$COMPATIBLE_CONFIG" --json
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify --json

If fapolicyd has not yet applied the trust update, retry the service-user check after it finishes syncing. It must pass before the final ensure. Check that defenseclaw-gateway.service is active afterward.

Roll back notes per channel

  • Linux packages and macOS. The package's preinstall script refuses an older package before any file changes, unless the marker exists: the package manager reports the failure and the deployed release keeps running. With the marker, the postinstall runs ensure --from-package --allow-downgrade and deletes the marker, so each rollback needs a new marker. An ensure --from-package you run yourself records its result in last-package-result.json like the install script.
  • A release that reads config_version: 8 (Linux). If the installed config is version 9, its install script records the failure in last-package-result.json. Run the ensure --from-package --allow-downgrade --config ... command right after the package manager finishes: until then the older release cannot read a version 9 config, so a restart of its services fails.
  • Debian and Ubuntu. An apt hook shipped with the package (/etc/apt/apt.conf.d/50defenseclaw-enterprise) refuses an older .deb before dpkg replaces any file, unless the marker /var/lib/defenseclaw-enterprise/allow-downgrade exists. It runs only for apt and apt-get: dpkg -i of an older package is not refused by it, so do not use it to go back.
  • RHEL. dnf and rpm run the installed package's scripts after the older files are in place, so only the older package's own preinstall can refuse the downgrade.
  • Tetragon (Linux). A failed or interrupted run that rolls itself back stops a sensor helper that loaded Tetragon policies, deletes those defenseclaw-* policies, and only then puts the previous files back. Your own Tetragon policies are not touched. A deliberate rollback to a release before Tetragon support leaves those policies loaded, so clean them up first; see Remove the policies, or downgrade.
  • MDM wrapper. The Linux wrapper installs .rpm files with rpm -U, so it refuses older RHEL packages.

Release floor limits

On Linux and macOS, every install, upgrade, repair and ensure checks the confirmed bundle's release floor before it changes anything, including a repair or ensure that keeps the recorded release. A version that is not a release (for example dev) never meets a floor. If that check cannot read the floor, the run refuses (product_floor_refused).

The floor is read from the confirmed bundle's manifest. If another file of the confirmed bundle cannot be read, repair and ensure keep the config the last deployment committed, repair the host and warn bundle_state_unreadable. With --config, or with no committed config, the run stops with that code as an error instead. To replace the damaged bundle, contact your administrator.

Package scripts shipped in 1.0.4 and later run the same check before they replace files, but only with a gateway that has the check: the installed gateway when it is 1.0.4 or later, or else the retained floor checker, a copy of the gateway that a non-purge uninstall keeps in the lifecycle directory. A checker that is there but cannot be read, is not a root-owned file only root can change, or does not run, refuses the install. The preinstall has nothing to check with when the installed gateway is older than 1.0.4 or gone and there is no retained floor checker: for example, an older package was installed below the floor, or an uninstall warned floor_checker_not_kept. The preinstall of a 1.0.4 or later package then installs its files; its postinstall ensure refuses a release below the floor, after the files are in place. A package older than 1.0.4 has no floor check in any of its scripts and completes below the floor. The apt hook of an installed 1.0.4 or later package runs the check for older packages installed through apt or apt-get.

Packages older than 1.0.4 installed through rpm, dnf, dpkg -i or the macOS Installer run their own older scripts, which do not check the floor. dpkg -i does not run the apt hook.

Windows Setup. From 1.0.6, Setup /install, /upgrade, /repair and /ensure check the floor before they change anything, with the Setup's own verified copy of DefenseClaw, and refuse a release below it (product_floor_refused, exit 1603). A floor that cannot be read refuses too. The check also works after an uninstall that kept the state. A 1.0.5 or older Setup does not check the floor and can install below it.

Refusal messages. These are excerpts from a confirmed 1.0.8 floor; the ellipsis omits the older installer's rollback instruction:

InstallerRefusal excerpt and result
RPM %prein (also Debian preinst and the apt hook)defenseclaw-enterprise: product_floor_refused: refusing to install 1.0.5: the signed policy bundle needs DefenseClaw 1.0.8 or later, and this is 1.0.5; … Nothing was changed. RPM exits 1. Packages before 1.0.9 print the same text without product_floor_refused:. The preinstall does not update /var/lib/defenseclaw-enterprise/last-package-result.json.
macOS pkg preinstallinstaller reports an error running package scripts. /var/log/install.log contains product_floor_refused: Refusing to install DefenseClaw 1.0.5: the signed policy bundle needs DefenseClaw 1.0.8 or later, and this is 1.0.5; … Nothing was changed. The pkg records product_floor_refused in errors[].code at /opt/cisco/defenseclaw/lifecycle/last-package-result.json.
Windows Setup 1.0.7Setup returns 1603; with JSON=1, errors[].code is product_floor_refused and errors[].message begins product_floor_refused: the signed policy bundle needs DefenseClaw 1.0.8 or later, and this is 1.0.7; …; nothing was changed. Windows Setup reports this in its result, not in a last-package-result.json file.

The 1.0.8 pkg and RPM reinstall at the confirmed 1.0.8 floor complete; the floor check also permits the matching Windows Setup version. Other lifecycle checks still apply.

On every OS, a 1.0.6 or later release that finds itself below the floor reports product_below_floor in status, verify and bundle status. It is a warning only: the policy keeps enforcing and nothing is repaired or reinstalled. bundle status shows the floor as current.min_product_version; check it before deploying an older release.

To roll back to 1.0.4, the confirmed floor must be unset or 1.0.4 or lower. If the floor is higher, contact your administrator before the rollback. Keep package deployment under administrator control, and check that the release you install meets the floor first. See Roll back for the supported procedure.

The kept version 8 config

Going back to a release that reads config_version: 8. An upgrade rewrites a config_version: 8 administrator config as config_version: 9 in place, and an older release refuses that file. Give the older release a version 8 config explicitly: your own version 8 administrator config, or the copy the upgrade kept next to the installed file (config.yaml.v8.bak, root- or SYSTEM-only). That copy exists only after a version 8 to 9 migration and holds the config as it was before it, so prefer your own current administrator config when you have one. The commands below pass it as CONFIG= or --config. A release that reads config_version: 9 needs no version 8 file.

OSThe kept version 8 config
WindowsC:\ProgramData\Cisco\DefenseClaw\etc\config.yaml.v8.bak
Linux/etc/defenseclaw/config.yaml.v8.bak
macOS/opt/cisco/defenseclaw/etc/config.yaml.v8.bak

Change the config

The managed config is administrator-owned. For what it contains, see Configuration.

OSConfig fileHow a change is applied
Linux/etc/defenseclaw/config.yamldefenseclaw-enterprise-apply.path runs ensure --reason path when the file changes, or when a file directly inside /etc/defenseclaw/secrets or /etc/defenseclaw/policies is added, removed or replaced
macOS/opt/cisco/defenseclaw/etc/config.yamlThe com.cisco.defenseclaw.apply daemon runs ensure --reason path when the file changes, or when an entry directly inside etc/secrets or etc/policies is added, removed or replaced, at most once every 30 seconds
WindowsC:\ProgramData\Cisco\DefenseClaw\etc\config.yamlThe lifecycle does not watch it. Run Setup /ensure again with the new file

Bundle mode. On a device whose MDM installed bundle trust anchors, the config comes only from signed bundles. ensure --config, Setup CONFIG= or a wrapper run with a config that is not the current bundle's is refused with bundle_required, and on Linux and macOS an edit of the installed file is reverted to the bundle's config. Deliver a new bundle instead. The rest of this section is for devices without bundle trust anchors.

Leave bundle mode on Windows. /repair, a new CONFIG= and moving the anchor file away do not turn bundle mode off: while a signed bundle is current, Setup still refuses CONFIG= with bundle_required. To go back to a local admin config:

  1. Stop delivering bundles to the computer in your MDM (remove the bundle app or package assignment). A later BUNDLE= with TRUSTANCHORS= puts it back in bundle mode.
  2. Run Setup as LocalSystem (Run Setup as LocalSystem) with /uninstall JSON=1, without PURGE=1, so each user's %USERPROFILE%\.defenseclaw keeps the user's own files (it loses only the files the managed runtime wrote there; see Windows: Remove). It removes the trust anchors, the bundle state and the rest of the machine state (Remove). It removes the connector registrations of each user with an active (connected) session. A user who is signed out, or whose session is disconnected, keeps an inert registration and is named in the user_registrations_pending warning; that is expected here and needs no /repair. From an elevated prompt instead of LocalSystem every user is named, except the Claude Code registration of the account running Setup, which is removed.
  3. Run Setup as LocalSystem with /ensure CONFIG=<file> JSON=1. It installs again from that config and enrolls the users again: a signed-in user at once, a signed-out user at their next sign-in (until then status counts their connectors as pending). Later changes go through /ensure CONFIG= as on any device without anchors.

A change is applied by the apply trigger on Linux and macOS. While it runs, status reports the change as pending apply (ok: true, pending_apply: true, a lifecycle_busy warning) and verify reports lifecycle_busy; both exit 75. That is not a failure, so run them again. A hand edit of the config as root is applied, not reported as drift.

On Linux and macOS you can also hand the new file to ensure. It validates the file, installs it as the managed config (mode 0640, owner root, group of the service account), and applies it:

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux ensure --config /root/defenseclaw-config.yaml --json

On Windows, pass the new file to the same release's Setup. ensure sees that the config differs from the installed one and applies it:

& 'C:\ProgramData\DefenseClaw-Staging\DefenseClawSetup-Enterprise-Standalone-x64.exe' /ensure CONFIG=C:\ProgramData\DefenseClaw-Staging\config.yaml JSON=1

If the new config is invalid, ensure fails and the installed config stays (config_invalid on Linux and macOS; on Windows the reason is in errors[].message). When an edit made in place is rejected, the lifecycle puts the last applied config back and keeps the edit as rejected-config.yaml; verify fails with config_rejected until the file is written again. A change to enterprise.network takes effect when the gateway restarts, and the profile cannot change in place: uninstall one and install the other.

Applying a config change

status and verify wait up to 5 seconds for a running apply trigger. If it is still running (usually under a minute), they exit 75 and say a configuration change is being applied: status reports it as pending apply (ok: true, pending_apply: true, a lifecycle_busy warning), verify as the lifecycle_busy error. That is not a failure and needs no repair: run them again when it finishes.

A hand edit of the config is applied, not reported as drift. When you edit the managed config.yaml in place as root (keeping its mode and owner), the apply trigger picks the change up and runs ensure, so after the trigger finishes (about 20 seconds on a Mac, usually under a minute) the new file is the applied config and verify finds nothing to report. An immediate verify while the trigger runs answers lifecycle_busy, not drift. verify reports drift for the installed files, binaries and entries the config produces, and for a rejected edit (config_rejected), not for a valid edit of the config itself. ensure --config with the reviewed file puts the reviewed version back and records it as the applied config.

In bundle mode (bundle trust anchors installed), the managed config is the current bundle's config. On Linux and macOS the apply trigger reverts an edit to that config. Windows does not watch the file: the edit stays until a later Setup /ensure or /repair without CONFIG= puts the bundle's config back and keeps the edit as rejected-config.yaml.

Invalid and rejected configs

If the new config is invalid, ensure fails and does not apply it: on Linux and macOS with config_invalid, and on Windows with another code whose reason is in errors[].message. The installed config stays as it was. On Linux and macOS, when ensure rejects a config that was edited in place (it fails validation, or the services do not come up healthy with it), the lifecycle puts the last applied config back and keeps the rejected file as rejected-config.yaml in the lifecycle directory. Until the config file is written again, status warns and verify fails with config_rejected. Push a corrected config or the previous one to clear it.

The apply trigger watches the config file and the top level of the secrets and policies directories. ensure re-applies when the config or a secret changed, when an installed file, binary or machine-policy entry drifted, or when the rule pack a setting resolves to changed, but it does not track the contents of the files under policies. The gateway reloads a rule pack when its files change; a custom pack edited in place no longer matches its pinned digest and is refused until the config pins the new one. Pointing guardrail.rule_pack at another pack is applied like any other config change; see Custom rule packs.

A change to enterprise.network (the outbound proxy) takes effect only when the gateway restarts. On Linux and macOS a lifecycle run that changes it restarts the gateway; a config reload inside a running gateway reports it as restart-required and keeps the previous proxy. See Network proxy. The profile cannot change in place: to move between Secure Client and standalone, uninstall one and install the other.

What ensure does with the config

The lifecycle is the only writer of config.yaml on a managed host. ensure, install, upgrade and repair apply a config the same way: validate before anything changes, migrate a version 8 config to version 9, write under the writer lock, keep the migration evidence (config.yaml.v8.bak, migration-v9.json), regenerate everything derived, and report the effective policy digest. If any step fails, the transaction rolls back.

What ensure does in order

The lifecycle is the only writer of config.yaml on a managed host: the local config tools refuse, as Policy changes on a managed host lists. ensure is the action an MDM runs; install, upgrade and repair apply a config the same way. In order, on Linux and macOS:

  1. Validate before anything changes. It reads the --config file, or the installed config, and checks the schema, the runtime load, the fixed layout, the rule packs and every protected credential the file names. A failure is config_invalid and the installed config stays.
  2. Migrate a version 8 config. A config_version: 8 config is migrated to version 9 in memory by the same library as the gateway's config migrate, validated again, and installed in place of the version 8 bytes. No defenseclaw CLI is needed on the host. If your configuration management puts the same version 8 file back, ensure leaves its bytes in place and the gateway migrates it in memory.
  3. Write under the writer lock. It takes config.yaml.lock, writes the files that changed, and records the config in config.generation.json with the actor lifecycle and the reason enterprise ensure (or the action that ran), when the config changed and when no recorded generation matches the file.
  4. Keep the evidence of a migration. It keeps the source as config.yaml.v8.bak (root-only) and writes migration-v9.json next to the config. The record lists every moved value, every conflicts entry (kept, lost, reason), the audit rows it imported (actions_rows_moved, always 0 on a managed computer) and how many local block or allow entries in the managed computer's audit.db it left in place (actions_rows_ignored, with the local_enforcement_entries_ignored warning). An inline scanner key in the version 8 file moves to the service .env. A rego/data.json left in the policy folder is read for the migration and ignored from version 9 on; remove it.
  5. Regenerate what is derived. Service definitions, the runtime descriptor and DefenseClaw's machine-policy entries are written from the config and never read back; the guardian renders each user's hook scripts and registrations from it within a minute. Anything that drifted is rewritten, whoever changed it.
  6. Report the policy. The result carries the effective policy digest and config generation (policy), and policy-state.json records them once the gateway reports the same digest. See Effective policy digest.

If any step fails, including the checks after the services start, the transaction rolls back, and the generation file and the migration files go back with it. On Windows the Setup transaction does the same: it migrates a version 8 config, keeps the same two files, records the generation with the actor lifecycle and reports policy. On Linux and macOS the result's changes list says what was written, for example migrated /etc/defenseclaw/config.yaml to config_version 9 (N values moved, 0 conflicts; the v8 file is kept as /etc/defenseclaw/config.yaml.v8.bak, the --config a rollback to a config_version 8 release needs). Windows Setup results report policy and the installed version, and a changes list when the run wrote something: the same migration line, a config applied to the running gateway without a restart, a replaced unparseable config, repaired hook runtime access or restored bundle files. A run that wrote nothing has no changes key. Conflicts add a config_migration_conflicts warning.

Edits made on the host

On Linux and macOS a valid in-place edit is applied by the apply trigger. A rejected edit is reverted and kept as rejected-config.yaml. A derived file (service definition, machine-policy entry, hook script) is rewritten from the config by the next ensure, repair or guardian pass.

On Windows nothing watches the installed config, and ensure compares only the file you supply, so do not edit the installed copy; run Setup /ensure with the new file.

On Linux and macOS config.yaml is root-owned (0640, group of the service account), so a standard user cannot edit it. An administrator's in-place edit is handled like a push from the MDM:

  • A valid edit is applied by the apply trigger's ensure --reason path and recorded as the next generation.
  • A rejected edit (validation fails, or the services do not come up healthy) is reverted. The lifecycle keeps a root-only copy of the last applied config as committed-config.yaml in the lifecycle directory, puts it back in place of the edit, and keeps the edit as rejected-config.yaml next to it. status warns and verify fails with config_rejected until config.yaml is written again.
  • A derived file (a service definition, a machine-policy entry, a hook script) is not read back. The next ensure or repair, or the guardian's next pass, rewrites it from the config, and verify fails on the drift until then.

Rotate the AI Defense key

Store the new value under the same credential name. On Linux and macOS the command then runs ensure; on Windows it restarts the gateway. See AI Defense key.

Add or remove users

The enumerator enrolls users automatically, within 5 minutes of their sign-in. On Windows, Claude Code is enrolled within 5 minutes of its first start in that account (its build is verified then), so a user who signs in and opens Claude Code later waits from that start; until then its calls are refused (enrollment). To force a user in or keep one out, change enterprise.enrollment in the config and apply it as in Change the config. See Enrollment.

Repair

repair re-applies the installed deployment: files, owners and modes, service definitions and machine policy entries. Then it starts and verifies the services. On Linux and macOS the owners and modes include every file the gateway and the hook guardian keep in the gateway data folder, the hook guardian folders and next to config.yaml (the audit store, the device identity key, the hook tokens, the service .env), so a chown -R or chmod -R over the deployment is undone without losing the audit history or the device identity. A file with a second name (a hard link) is not changed; the error names it. Every lifecycle run first takes away the permission bits that private folders have beyond their managed mode, and a run that rolls back does not open them again.

Linux
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux repair --json
macOS
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos repair --json
Windows
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows repair --profile standalone

repair stops and restarts every DefenseClaw service for a few seconds and lists what it changed (nothing to repair on a healthy deployment); ensure leaves a healthy deployment running. It also removes the guardian targets of deleted accounts. For Linux package installs, reinstall the package to restore binaries. On Windows the installed CLI repairs the deployment without a payload, so it cannot put back a file that went missing. For that, run the Setup of the installed release with /repair JSON=1 from an elevated PowerShell prompt, as & .\DefenseClawSetup-Enterprise-Standalone-x64.exe /repair JSON=1 in the folder that holds it. Setup is not installed on the computer: use the copy in your MDM package or the release download.

To re-run the guardian now, and repair DefenseClaw's machine-policy entries, without re-applying the deployment files, use reconcile:

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux reconcile --json

On Windows, reconcile restarts the guardian and waits for a fresh reconcile:

& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows reconcile --profile standalone --json

Repair notes

  • What changed (Linux and macOS). The result lists what repair changed: the files it rewrote or whose mode or owner it restored, the services it started, the machine policy entries it rewrote, and the users and agents whose hooks the guardian rewrote. On a healthy deployment it says nothing to repair. repair always re-applies the deployment, so it stops and restarts every DefenseClaw service (the gateway and the hook guardian are down for a few seconds); ensure leaves a healthy deployment running. The --json result carries the list as changes.
  • Disabled and masked units (Linux). A DefenseClaw unit an administrator disabled or masked is enabled or unmasked again, and the result says so. verify names such a unit.
  • Payload installs (Linux and macOS). repair keeps the installed binaries. If they no longer match the deployment record, it stops with payload_invalid; run repair --payload <dir> with the same release's payload. On a Linux tarball host with fapolicyd, trust the staged payload and use the two-stage flow to restore the installed binaries before starting services.
  • Linux package installs. To restore the binaries, reinstall the package: sudo apt install --reinstall ./<package>.deb or sudo dnf reinstall ./<package>.rpm. A power loss or reset during a package upgrade can leave the binaries and units the package was writing empty: rpm -V defenseclaw-enterprise flags them and the units show as masked. Reinstall the package the upgrade was installing, which also finishes the interrupted lifecycle transaction (recovered_interrupted_transaction). If rpm -q defenseclaw-enterprise lists two versions after an interrupted upgrade, run sudo dnf remove --duplicates defenseclaw-enterprise, then sudo dnf reinstall defenseclaw-enterprise. ensure --from-package does not repair the package database.
  • Deleted accounts (Linux and macOS). repair also removes the guardian targets of accounts that no longer exist. Otherwise they stay 10 to 15 minutes, with the warning guardian_target_account_removed. See New, changed and removed users.
  • Windows. Use the installed CLI's repair (above), or the Setup of the release that is installed when a file must be restored from the payload. /ensure also repairs a deployment whose verify fails.
  • Claude Code attestation (Windows). After you confirm that a real Claude Code session runs DefenseClaw's managed hooks, record it with /repair ATTESTCLAUDEEFFECTIVEPOLICY=1 JSON=1 (the Setup form of --attest-claude-effective-policy). See Health fields.

Restart the managed gateway

defenseclaw-gateway start, stop and restart control the per-user gateway, and on a managed host they refuse, also as root. The refusal points to deployment status. Use the commands below to restart the managed gateway.

OSRestart the gatewayRe-apply the deployment and restart every service
Linuxsudo systemctl restart defenseclaw-gateway.servicesudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux repair --json
macOSsudo launchctl kickstart -k system/com.cisco.defenseclaw.gatewaysudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos repair --json
WindowsFrom an elevated PowerShell prompt: & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows repair --profile standaloneThe same

To stop the managed gateway, for example to see what your users get while it is down, and to start it again:

OSStop the gatewayStart it again
Linuxsudo systemctl stop defenseclaw-gateway-hook.socket defenseclaw-gateway-api.socket defenseclaw-gateway.servicesudo systemctl start defenseclaw-gateway-hook.socket defenseclaw-gateway-api.socket defenseclaw-gateway.service
macOSsudo launchctl bootout system/com.cisco.defenseclaw.gatewaysudo launchctl bootstrap system /Library/LaunchDaemons/com.cisco.defenseclaw.gateway.plist

On Linux stop the two sockets with the service: a socket that still listens starts the gateway again at the next hook. While the gateway is stopped, hooks answer enterprise_managed_gateway_not_running and block the call (allow it under the administrator's hook_fail_mode: open, see below), and status exits 1 with verify_failed errors that name the gateway as not active. The gateway stays stopped until you start it again or run repair.

A managed hook that meets a restarting gateway retries for about 3 seconds, so a quick restart is not visible to the agent. With the default closed fail mode, a longer restart blocks each call. Tool-call hooks give the gateway up to about 3.5 seconds from contact, capped at 4 seconds from hook launch, then block with enterprise_managed_gateway_no_answer. The administrator's hook_fail_mode: open allows a call only while the hook proves the gateway service is stopped (no gateway took the call); a restart the hook cannot prove stopped, no answer in time, integrity, peer-verification, credential and rate-limit refusals still block. For connectors whose foreign-hook guard checks the session with the gateway (foreign_hooks: remove, the default), open runs a call only on Linux and macOS, for an agent process with a current clean-session note. DEFENSECLAW_STRICT_AVAILABILITY=1 closes outages too. ensure applies most config changes, including connector enabled changes on managed Linux and macOS, in the running gateway without a restart when the new generation is confirmed; a change to a process-level key (gateway.*, enterprise.network, the other enterprise keys) restarts it and takes two to six minutes.

Gateway restarts and hook timing

A managed hook that meets a restarting gateway (a refused or dropped connection, a stopped service) sends its call again for up to about 3 seconds from the start of the hook, so a quick restart is not visible to the agent. With the default closed fail mode, a restart that lasts longer blocks each call within those 3 seconds: on Linux, where the call waits in the socket systemd holds, the block names enterprise_managed_gateway_restarting; on macOS and Windows it is enterprise_managed_gateway_not_running.

A hook for a tool call (PreToolUse and the like) waits up to about 3.5 seconds from gateway contact for its decision, within a 4-second cap from hook launch, whatever holds it up (a restart, an upgrade, a repair, a configuration change or a gateway too busy to answer). With the default closed fail mode it then blocks the call with enterprise_managed_gateway_no_answer, so DefenseClaw never holds an agent's tool call for more than about 5 seconds. A decision that waits on Cisco AI Defense or the LLM judge gets up to about 4 seconds, then is blocked the same way. Prompts and session, stop and other events keep their whole budget. Lifecycle runs run at a lower CPU priority than the hooks on every OS, so a repair does not take the CPU the hooks need to answer in time.

A gateway too busy to answer blocks a tool call only when this budget runs out, never before it, so a burst makes calls wait longer before it blocks any. Measured on Windows Server 2025 with 8 vCPUs in action mode: when one account starts 60 tool calls at once, each in a new session, every 15 seconds, about 9 in 10 calls get their decision within the budget (median about 2.8 seconds) and the rest are blocked at the budget with enterprise_managed_gateway_no_answer. That is about 6 such calls per vCPU at once. In observe mode the same burst was answered in full. On Linux, measured on a per-user install on RHEL 9.8 with 4 vCPUs, up to 3 interactive agents per vCPU working at once got every tool-call decision within 2 seconds (613 calls, maximum 1.9 seconds). See Many agents on one Linux host.

While a Setup, pkg or rpm run holds the gateway, the block names the run: "DefenseClaw is being installed or upgraded on this computer, and its gateway is stopped until that run finishes or is recovered. Try again in a moment", and it points the administrator to the platform's status command. The call is still blocked. Retry when the run ends. A run that was stopped before it finished leaves the same block until it is recovered. A refusal with its own cause keeps its own text.

The administrator's hook_fail_mode: open allows a call only while the hook proves the gateway service is stopped (no gateway took the call). A restart the hook cannot prove stopped blocks, and so does a hook that reaches its answer deadline without a decision. Integrity, peer-verification, credential and rate-limit refusals still block. Connectors whose foreign-hook guard checks the session with the gateway (foreign_hooks: remove, the default) block outages too (Foreign-hook guard). DEFENSECLAW_STRICT_AVAILABILITY=1 closes outages too. See Fail modes.

A running standalone gateway detects edits to a rule pack or policy file. If the pack is pinned, an in-place edit fails its digest check and the gateway keeps the previous policy generation. Stage the edited pack in a new folder, validate and pin its new digest, then apply it with ensure --config. A restart alone cannot apply a mismatched pack and may leave the gateway unable to start.

Secrets and upgrades restart the gateway on their own. On every OS, ensure applies a config change that only touches keys the gateway reloads in place (most of them) in the running gateway, without a restart, and waits until the gateway reports the new policy: the policy generation on /health goes up by one. On Linux and macOS a file that differs only in bytes (comments, line endings, a BOM, quoting) is applied the same way: the config generation goes up, the effective policy digest stays, and the gateway keeps running. On Windows the change is applied the same way when the installed release is current and the supplied config differs from the installed one only in such keys: ensure replaces config.yaml with its access control kept, waits up to 30 seconds for the gateway to report the new policy, and verifies the deployment. The result lists the change and the warning ensure_config_applied; no service stops. Such an ensure takes about a minute, most of it the verify. On Windows two more kinds of change take this path:

  • A file that changes no setting: other line endings, comments or formatting.
  • A change of who is enrolled or which connectors are: the user and group lists of enterprise.enrollment (include_users, exclude_users, include_groups, exclude_groups, exempt_users) and the connector set (guardrail.connectors.<name> and its enabled). ensure also refreshes the enrolled targets, and the hook guardian reloads the config and registers or removes the hooks without a restart.

If the gateway does not report the policy in time, or the lifecycle lock is busy, ensure puts the previous config back and runs the lifecycle transaction instead. A change to a process-level key runs it too: gateway.*, guardrail.hook_self_heal, enterprise.network, the other enterprise keys and the keys that Source of truth lists. The other enterprise keys include enterprise.machine_policy (for example managed_hooks_only): the gateway reads them only at start, so they need a restart. A change whose only such keys are enterprise.machine_policy.default.managed_hooks_only or enterprise.machine_policy.connectors.claudecode.managed_hooks_only restarts only the hook guardian and then the gateway. The other services keep running. ensure waits until every enrolled target verifies with the new setting before it restarts the gateway, and the setting is machine wide, so an enrolled account that is signed out does not block it. On the 1.0.8 test VM this took about 65 seconds. If the guardian or the gateway does not prove the change, the previous config goes back, and the lifecycle transaction below applies the change instead. The transaction is the one an upgrade runs, with the installed release's own payload: it stops every service, puts the same release back in place, starts the services and verifies the deployment. On the 1.0.8 test VM the ensure took about 110 seconds, against about a minute for a change applied in the running gateway. Before 1.0.8 the same change took about 183 seconds. It skips a fixed wait of about 65 seconds when every service stopped cleanly; a service that did not stop cleanly keeps the full wait, and a slower or busier host takes longer, so give the MDM script a time limit of several minutes. Nothing is upgraded: the result carries the warning ensure_config_restart, which names the keys that made it restart. Only a newer release reports ensure_upgrade. When the transaction fails or rolls back, the warning is ensure_config_failed instead: the change is not confirmed applied, and the errors say what failed.

Uninstall

Uninstall does the following on every OS:

  • It first stops what could put registrations back: on Linux and macOS the guardian and the apply trigger, and on Windows it revokes every per-user enrollment.
  • It removes DefenseClaw's hook registrations from each user's agent config. On Windows this runs as each signed-in user after the uninstall has committed.
  • It removes DefenseClaw's entries from vendor machine policy. Your own entries stay. On Linux and macOS it restores the preimages it recorded.
  • It stops and removes the services.

Restart agents after an uninstall: a session that started earlier keeps the hook it read at its start, and once the hook binary is gone it runs that hook as a missing command, so its tool calls run without DefenseClaw. To go back to an older release without that window, use Roll back.

A standalone uninstall also removes the config, credentials, most machine state and logs. Each user's ~/.defenseclaw and per-user binaries stay; --purge removes everything DefenseClaw installed (on macOS, macOS lets only a process with Full Disk Access delete the _defenseclaw account, so from an ssh session or MDM agent without it the delete is refused (eDSPermissionError); the uninstall then completes with a service_account warning that gives the two dscl commands to run from a Terminal or MDM script that has Full Disk Access), and --keep-state keeps machine state for a reinstall.

Install channelRemove the deployment and keep each user's data (Linux/macOS may keep sandbox state)Remove everything
Linux payloadsudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --jsonAdd --purge
Debian and Ubuntu packagesudo apt remove defenseclaw-enterpriseRun the lifecycle uninstall --purge --json first, then sudo apt purge defenseclaw-enterprise
RHEL packagesudo dnf remove defenseclaw-enterpriseRun the lifecycle uninstall --purge --json first, then sudo dnf remove defenseclaw-enterprise
macOSsudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos uninstall --jsonAdd --purge
WindowsSetup /uninstall JSON=1, or & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows uninstall --profile standalone --json from an elevated PowerShell promptSetup /uninstall JSON=1 PURGE=1, or add --purge

Removing a Linux package runs the lifecycle uninstall first, without purge; run uninstall --purge --json before removing the package to remove per-user data too.

Linux: remove everything
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --purge --json
Windows: remove everything
& 'C:\ProgramData\DefenseClaw-Staging\DefenseClawSetup-Enterprise-Standalone-x64.exe' /uninstall JSON=1 PURGE=1

After an uninstall or a reinstall, ask users to restart running agents; an agent reads its hooks when it starts.

What uninstall keeps

The registrations go before the hook binary and the runtime descriptor. An agent session that started before the uninstall keeps the hook registration it read at its start until it is restarted; once the uninstall has removed the hook binary, such a session runs that hook as a missing command, which the agent treats as a non-blocking hook error, so its tool calls run without DefenseClaw. Restart the agents after an uninstall. To go back to an older release without that window, use Roll back instead of an uninstall followed by an install: the rollback replaces the release in place and the hooks stay registered.

On a standalone deployment it also removes the config, credentials, most machine state and logs, with the kept-sandbox exception below. Each user's ~/.defenseclaw and per-user binaries stay. A purge removes DefenseClaw-owned per-user entries and binaries; an account's other files inside ~/.defenseclaw stay, and the folder goes only when empty. The Secure Client profile keeps its machine state unless you purge.

On Linux and macOS, the default uninstall removes the deployment, config, credentials, logs, most gateway and guardian state, most lifecycle state and the service account. When an account keeps sandboxes, the gateway's registration store (/var/lib/defenseclaw/sandbox on Linux or /opt/cisco/defenseclaw/runtime/sandbox on macOS) stays if it contains a file, and its key (redaction-correlation.key in the same parent) stays if it is a regular file. They are root-owned while the service account is gone; the next ensure adopts them. The lifecycle directory also keeps the root-only record of the sandbox setup those sandboxes were made under (openshell-state.kept.json) and retained-state.json, the root-only record of the state folders the uninstall kept, and the kept data folder holds a root-only .defenseclaw-retained marker. The next ensure uses them to adopt the kept state, then removes them. The root-owned lifecycle.lock stays so waiting runs keep using the same lock. Use --purge for a clean image or to remove the retained sandbox store, key and setup record. Purge in the first removal: a purge runs the deployment's own binary, which a payload uninstall, apt remove, dnf remove and the MDM removal scripts delete. After one of those, install the package or payload again and purge, or delete /var/lib/defenseclaw (macOS: /opt/cisco/defenseclaw/runtime) and the lifecycle directory by hand. A purge also deletes each enrolled account's sandboxes and any sandbox work not pulled yet. On Linux, the files in /etc/defenseclaw/policies stay unless you purge. To turn the deployment on again with the same config, run ensure --from-package --config <file> on a package host; a payload uninstall removes the binaries, so stage the payload again and run its ensure --payload <dir> --config <file>. On a fapolicyd host, follow the staged-payload trust and two-stage tarball install steps; refresh an existing /opt/defenseclaw/ trust entry with --file update after staging, or use --file add if no entry exists. Add --keep-state to keep the machine state for a reinstall instead.

Uninstall notes

  • Linux packages. Removing the package runs the lifecycle uninstall first, without purge. This also runs when a package install failed and rolled back. apt purge also deletes what a failed uninstall left of /etc/defenseclaw, /var/lib/defenseclaw (including a kept sandbox store and key), /var/lib/defenseclaw-hook-guardian and /var/log/defenseclaw, and clears the lifecycle directory except for lifecycle.lock. Each user keeps ~/.defenseclaw and the per-user binaries, because the gateway that removes them is gone by then; run sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --purge --json before you remove the package to remove those too. The MDM uninstall.sh --purge does this for you. A removal refused with uninstall_precheck_refused or stopped with uninstall_incomplete keeps the package files: read /var/lib/defenseclaw-enterprise/last-package-result.json, fix the named cause and run the removal again. On RHEL, the last-resort rpm -e --nopreun defenseclaw-enterprise removes the files without cleaning registrations, which then name a missing binary until removed manually.
  • Tetragon (Linux). Uninstall deletes the defenseclaw-* policies the sensor helper loaded in Tetragon before it removes any file, so no control keeps denying after the helper is gone. It then removes the helper's state in /var/lib/defenseclaw-sensor and its runtime directories (--keep-state keeps the state). Tetragon itself and your own policies stay. See Remove the policies, or downgrade.
  • Linux uninstall with the package kept. The package's /usr/lib/tmpfiles.d/defenseclaw.conf names the defenseclaw account the uninstall removed, so the uninstall writes an override of the same name in /etc/tmpfiles.d; the next install or removing the package removes it.
  • macOS. A pkg has no uninstaller. The lifecycle removes the binaries itself and forgets the package receipt (com.cisco.defenseclaw.enterprise).
  • Registrations left, warning (Linux and macOS). Each user's registrations are removed as that user. If the user's home is unavailable, the recorded home of a removed or re-homed account is gone, or a re-homed account's old home cannot be trusted, uninstall warns with per_user_hooks_remaining and goes on. The warning names what may remain; remove DefenseClaw's entries from the named agent config, and for a re-homed account follow the clearing paths in Warnings.
  • Registrations left, error (Linux and macOS). Other registration removal failures report per_user_hooks_remaining for each user and agent and stop uninstall before removing the binaries those registrations run. The deployment record and state stay. Fix the reported cause and rerun the same uninstall; ensure restores the deployment instead. A user's worker that runs out of time (60 seconds) is retried once with five minutes.
  • Manifest rows (Linux and macOS). Uninstall resolves each row of targets.yaml to its account the way reconcile does. When a row does not resolve (the account does not exist, or the directory does not answer), uninstall refuses before it stops any service or removes any policy and names the row with per_user_hooks_remaining. Fix or remove that row and run the uninstall again.
  • Per-user state (Linux and macOS). --purge removes known DefenseClaw-owned entries in each enrolled user's home, as that user. It first stops the user's per-user gateway and watchdog, if one runs, and restores files that DefenseClaw changed and still has backups for. It then removes managed hook scripts, hook credentials, the session cache and other known files inside ~/.defenseclaw. From ~/.local/bin, it removes defenseclaw-gateway, defenseclaw-acp, the hook helpers (defenseclaw-hook-post, defenseclaw-hook-user and, on Linux, defenseclaw-sensor-helper), launcher links, the uv the per-user installer added when unchanged, and its bookkeeping. For an account enrolled only for machine-policy connectors, it removes the same known entries, including ~/.defenseclaw/session-facts.json. The same rule applies to an eligible account without per-user hook enrollment. Unrelated account files and saved originals in foreign-hooks-backup stay, and ~/.defenseclaw is removed only when empty. The purge follows no symlink and leaves the user's own tools in ~/.local/bin. The result names retained entries and each account whose state it removed or left alone, with the reason (a home that is not trusted or not available, a hook removal that failed, or a gateway that could not be stopped). Fix the cause and run the same uninstall again.
  • A user's own install from before the enrollment (Linux and macOS). If an enrolled account had its own DefenseClaw install before the enrollment (its ~/.defenseclaw holds config.yaml, .env, audit.db, previous/, or the program the per-user installer puts there, .venv/ or installer/, also when the account never ran defenseclaw init), --purge leaves that folder and the install's binaries exactly as they are and names the account in the result (kept the DefenseClaw per-user data of user <name> ... and a per_user_state_remaining warning). A machine uninstall never deletes or moves an account's own data. No ~/.defenseclaw-backup-* folder is made. The enrollment shares that folder: the uninstall, with or without --purge, puts back the install's hook scripts and hook settings, connector backups, hook contract lock and session cache as they were before the enrollment, and each agent config those backups name when the uninstall left it as it was before the own install (an agent config changed while the computer was managed stays as it is and is named in a per_user_state_remaining warning). The Claude Code hook script the enrollment replaced with a blocker comes back too.
  • A user whose home is gone (Linux and macOS). When an enrolled user's home folder was deleted and its parent folder still holds other entries, the hooks and ~/.defenseclaw went with it. The uninstall warns (per_user_hooks_remaining) with the home and goes on. A home that does not answer, or whose parent folder is missing, empty (the mount point of an unmounted volume) or cannot be read, is not available rather than gone. So is a home moved or renamed aside: its parent folder still holds another folder the account owns (for example after mv /home/<user> /home/.<user>-away, or /Users/<user> on macOS), and that folder keeps the agent configs with DefenseClaw's hook entries. For an account that still exists, the uninstall refuses before it changes anything (uninstall_precheck_refused): the services, the machine policy and the hooks and Claude Code blockers of every other user stay. It names the home: mount it, or move it back to its home path, and run the uninstall again. A home that goes away while the uninstall runs stops it later (uninstall_incomplete), with the binaries, the deployment record and the services kept. A per-domain home layout (SSSD fallback_homedir = /home/%d/%u) looks the same when the only account of a domain had its home folder deleted: recreate that folder as a folder the account owns, then run the uninstall again. Removing the account does not end the stop while a targets.yaml row names it (see Manifest rows).
  • A deleted enrolled account (Windows). When an enrolled local account was deleted since the hook enumerator's last pass, Setup /uninstall (also with PURGE=1) runs that pass itself: it restarts the enumerator, which drops the account's rows, waits up to three minutes for the guardian to take the new targets.yaml, and then goes on. No /repair is needed. If the rows are still listed after the wait, nothing was removed: run the uninstall again a few minutes later. When the enumerator's scheduled pass already dropped the rows just before the uninstall, the uninstall starts the same wait without a restart, and restarts the enumerator once if it then still finds the deleted account.
  • Sandboxes (Linux and macOS). The uninstall stops the sandbox daemon and OpenShell gateway of each account. On Linux, apt remove, dnf remove and rpm -e also stop the sandbox user units in the user manager of every signed-in account before the package's files go. When a user manager still runs one of those units after three stops, or does not answer, the removal fails and keeps the package files; the message names the accounts. Stop the units as each named user (systemctl --user stop defenseclaw-sandbox.socket defenseclaw-sandbox.service defenseclaw-openshell-gateway.service) or sign the user out, then run the removal again. On macOS the uninstall unloads both sandbox LaunchAgents from the gui and user launchd domains of every signed-in account, and removes the defenseclaw launcher link and both plists from /Library/LaunchAgents.
  • MDM. Use uninstall.sh [--purge] on Linux and macOS, or uninstall.ps1 on Windows. See Install with an MDM.
  • Windows per-user registrations. Acting as a user needs that user's session token, which only LocalSystem can obtain. An MDM uninstall runs as LocalSystem and removes DefenseClaw's hooks and plugins (Amp, Antigravity, Devin, Hermes, Kiro, OpenCode, and a DefenseClaw Copilot user hook file) from the agent config of every user with an active (connected) session. An uninstall from an elevated administrator prompt or from Add/Remove Programs removes none, and users who are signed out, or whose session is disconnected, keep theirs. The result lists them in the user_registrations_pending and user_registrations_failed warnings. What stays is inert; see Windows: Remove.
  • Per-user state (Windows). PURGE=1 or --purge, run as LocalSystem, removes known DefenseClaw-owned entries in each enrolled account's %USERPROFILE%\.defenseclaw, whether or not the account is signed in. Unrelated account files and saved originals in foreign-hooks-backup stay; the folder is removed only when empty. The purge also removes the DefenseClaw files of a per-user install from %USERPROFILE%\.local\bin and, once that folder is empty, the folder and its entry in the account's user Path. A signed-out account's Path cannot be changed, so it keeps that entry. An account whose agent registrations stay (it had no active, connected session) keeps its .defenseclaw, whose connector_backups restore them; the purge still finishes. The per_user_state_remaining warning names retained account entries and each folder it could not remove, with the reason.

After an uninstall

After an uninstall, and again after a reinstall (including an MDM remove and re-add), ask users to restart running agents. An agent reads its hooks when it starts. On Linux and macOS, while the managed hook binary is still present but its runtime descriptor has been removed, a retained hook command denies tool calls even after DefenseClaw's machine-policy entry is removed; Stop and session-end events receive a neutral allow. Once the binary is removed, a session that retained its command may report a hook launch failure (a Copilot CLI session does not: its DefenseClaw command exits 0 once the deployment is removed). An agent left running through the uninstall and the reinstall keeps running without DefenseClaw until it restarts. On Linux and macOS, the ensure result, status and verify name each user whose agent sessions started before the deployment was activated, with the agent_sessions_restart_required warning.

Decommission checklist

  1. Remove the device from the MDM assignment first. Otherwise the next scheduled ensure installs DefenseClaw again.

  2. Keep what you need. A purge deletes the config, the data directory (with the audit database), the guardian state, the lifecycle state and DefenseClaw's log directory. Copy them first. On Windows, uninstall also unregisters the DefenseClaw event log. The systemd journal, the Windows Application event log and %WINDIR%\Logs\DefenseClaw are not removed. See Logs and events. To review a retained audit database after purge, keep its audit.db and companion audit.db-wal and audit.db-shm files together, then run /opt/defenseclaw/bin/defenseclaw-gateway audit export --db <copied-audit.db> as root on Linux (/opt/cisco/defenseclaw/bin/defenseclaw-gateway on macOS) or & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw-gateway.exe' audit export --db <copied-audit.db> from an elevated Administrator prompt on Windows. The export opens the copy read-only and does not need the former deployment's config.

  3. Uninstall with purge, as in Uninstall.

  4. Confirm that nothing remains:

    OSCheckExpected
    Linuxsystemctl list-unit-files 'defenseclaw*'No units
    Linuxdpkg -s defenseclaw-enterprise or rpm -q defenseclaw-enterpriseNot installed
    macOSpkgutil --pkg-info com.cisco.defenseclaw.enterpriseNo receipt
    macOSls /opt/cisco/defenseclaw/lifecycleOnly lifecycle.lock
    WindowsTest-Path 'HKLM:\SOFTWARE\Cisco\DefenseClaw\Enterprise'False
    WindowsGet-Service DefenseClaw*No services
  5. Ask users to restart their agents.

Contain an incident

  • Disable the account in your directory or on the host, then remove it from enrollment. DefenseClaw inspects and blocks agent actions; it does not disable accounts. Per-user hook and telemetry credentials are bound to their uid or SID and stop authenticating on the guardian's next pass after removal. They never reach management routes, other connectors or another user's identity. On Linux and macOS, machine-policy hooks keep inspecting a removed account by default; set unenrolled_users: deny to refuse its calls. On Windows, a cut-off SID must be refused, with an audited enterprise_managed_sid_unregistered decision while the hook is in force (see Review the audit log).
  • Check the machine policy after removal. On managed Windows, Claude Code, Codex and Cursor must refuse the cut-off account even with zero enrolled users for that agent. Run & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise policy verify --json and review each enabled agent. If its policy is missing, keep the account disabled, stop that agent with application control, and repair the deployment before allowing agent use. On Linux and macOS the policy stays machine-wide; use unenrolled_users: deny when enrollment alone must refuse a call.
  • Rotate the per-user credentials on Linux and macOS when a user's credentials may have been copied to another account or host. See Rotate per-user credentials.
  • Keep the evidence. Copy the audit database and the logs before you uninstall or purge anything.
  • Treat root or administrator compromise as an endpoint incident. The deployment's protections assume that the administrator boundary holds (see the threat model). Reimage the host rather than repairing it in place.