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:
| OS | Command |
|---|---|
| Linux | /opt/defenseclaw/bin/defenseclaw-gateway, as root |
| macOS | /opt/cisco/defenseclaw/bin/defenseclaw-gateway, as root |
| Windows | The 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
$LASTEXITCODELinux
Upgrade with the channel you installed from. A host where the package owns the binaries
refuses a payload upgrade (package_owned_binaries).
VERSION=X.Y.Z # the release you deploy
sudo apt install "./defenseclaw-enterprise-${VERSION}-linux-amd64.deb"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
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" --jsonRun 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 --jsonThe 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.jsonThe 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 channel | How 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 Ubuntu | Create 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 |
| RHEL | Create 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 payload | Extract the older release as in Linux payload upgrade, then follow Linux payload rollback for the fapolicyd or non-fapolicyd path |
| macOS | Create 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 exit1603while retiring the previous journal. Before running the older Setup, save the current admin config. Setguardrail.hook_fail_modeand eachguardrail.connectors.<name>.hook_fail_modetoclosedin 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=1and 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 with1603and 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: trueto the Hermespre_tool_callhook. 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/upgraderuns,/verifypasses at first and then, within about ten minutes, exits1603(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/verifypasses. - 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
/upgraderuns,/verifyexits1603with one pending target for that account (canonical hook matrix is absent, a stalehermes@<SID>target) and coverage reads incomplete. The/verifyresult names the account, and it passes once that user reconnects. A user who is signed out is listed as pending and/verifypasses. 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.tomlas a directcmd.execommand. 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/repairkeeps both. Delete the 1.0.5 DefenseClaw hook group from that file by hand, or run a newer Setup's/ensureto 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, notdpkg -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 owndefenseclaw.jsentry. OpenCode V1 is still guarded by thedefenseclaw.jsentry and the file is otherwise harmless. 1.0.6 treats both entries as its own: its nextensureorrepair, 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 asagent_unprotecteduntil its first scan. To clean the file by hand, delete the entry that ends inshare/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 useshare\opencode\defenseclaw.jsand do not knowindex.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/uninstallthen exits1603before 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 theshare\opencodeentry in%ProgramData%\opencode\opencode.json. To use the older Setup, move that one file out ofC:\Program Files\Cisco\DefenseClaw, run its/uninstallagain, and then delete the entry that ends inshare\opencodefrom 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_unprotectedfor such a user; Linux was not tested). Before you roll back, list the users who run OpenCode V2 (theopencodeentries instatus,npm ls -g @opencode/clias 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 afterdnf downgradefinished. 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 timeorthe DefenseClaw gateway is not available), whileenterprise linux statusandverifysay 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" --jsonOn 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 --jsonIf 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-downgradeand deletes the marker, so each rollback needs a new marker. Anensure --from-packageyou run yourself records its result inlast-package-result.jsonlike the install script. - A release that reads
config_version: 8(Linux). If the installed config is version 9, its install script records the failure inlast-package-result.json. Run theensure --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.debbefore dpkg replaces any file, unless the marker/var/lib/defenseclaw-enterprise/allow-downgradeexists. It runs only foraptandapt-get:dpkg -iof an older package is not refused by it, so do not use it to go back. - RHEL.
dnfandrpmrun 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
.rpmfiles withrpm -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:
| Installer | Refusal 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 preinstall | installer 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.7 | Setup 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.
| OS | The kept version 8 config |
|---|---|
| Windows | C:\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.
| OS | Config file | How a change is applied |
|---|---|---|
| Linux | /etc/defenseclaw/config.yaml | defenseclaw-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.yaml | The 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 |
| Windows | C:\ProgramData\Cisco\DefenseClaw\etc\config.yaml | The 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:
- Stop delivering bundles to the computer in your MDM (remove the bundle app or package assignment). A later
BUNDLE=withTRUSTANCHORS=puts it back in bundle mode. - Run Setup as LocalSystem (Run Setup as LocalSystem) with
/uninstall JSON=1, withoutPURGE=1, so each user's%USERPROFILE%\.defenseclawkeeps 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 theuser_registrations_pendingwarning; 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. - 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 thenstatuscounts 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 --jsonOn 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=1If 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:
- Validate before anything changes. It reads the
--configfile, 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 isconfig_invalidand the installed config stays. - Migrate a version 8 config. A
config_version: 8config is migrated to version 9 in memory by the same library as the gateway'sconfig migrate, validated again, and installed in place of the version 8 bytes. NodefenseclawCLI is needed on the host. If your configuration management puts the same version 8 file back,ensureleaves its bytes in place and the gateway migrates it in memory. - Write under the writer lock. It takes
config.yaml.lock, writes the files that changed, and records the config inconfig.generation.jsonwith the actorlifecycleand the reasonenterprise ensure(or the action that ran), when the config changed and when no recorded generation matches the file. - Keep the evidence of a migration. It keeps the source as
config.yaml.v8.bak(root-only) and writesmigration-v9.jsonnext to the config. The record lists everymovedvalue, everyconflictsentry (kept,lost,reason), the audit rows it imported (actions_rows_moved, always0on a managed computer) and how many local block or allow entries in the managed computer'saudit.dbit left in place (actions_rows_ignored, with thelocal_enforcement_entries_ignoredwarning). An inline scanner key in the version 8 file moves to the service.env. Arego/data.jsonleft in the policy folder is read for the migration and ignored from version 9 on; remove it. - 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.
- Report the policy. The result carries the effective policy digest and config
generation (
policy), andpolicy-state.jsonrecords 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 pathand 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.yamlin the lifecycle directory, puts it back in place of the edit, and keeps the edit asrejected-config.yamlnext to it.statuswarns andverifyfails withconfig_rejecteduntilconfig.yamlis written again. - A derived file (a service definition, a machine-policy entry, a hook script) is not
read back. The next
ensureorrepair, or the guardian's next pass, rewrites it from the config, andverifyfails 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.
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux repair --jsonsudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos repair --json& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows repair --profile standalonerepair 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 --jsonOn Windows, reconcile restarts the guardian and waits for a fresh reconcile:
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows reconcile --profile standalone --jsonRepair notes
- What changed (Linux and macOS). The result lists what
repairchanged: 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 saysnothing to repair.repairalways re-applies the deployment, so it stops and restarts every DefenseClaw service (the gateway and the hook guardian are down for a few seconds);ensureleaves a healthy deployment running. The--jsonresult carries the list aschanges. - Disabled and masked units (Linux). A DefenseClaw unit an administrator disabled or
masked is enabled or unmasked again, and the result says so.
verifynames such a unit. - Payload installs (Linux and macOS).
repairkeeps the installed binaries. If they no longer match the deployment record, it stops withpayload_invalid; runrepair --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>.deborsudo 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-enterpriseflags them and the units show as masked. Reinstall the package the upgrade was installing, which also finishes the interrupted lifecycle transaction (recovered_interrupted_transaction). Ifrpm -q defenseclaw-enterpriselists two versions after an interrupted upgrade, runsudo dnf remove --duplicates defenseclaw-enterprise, thensudo dnf reinstall defenseclaw-enterprise.ensure --from-packagedoes not repair the package database. - Deleted accounts (Linux and macOS).
repairalso removes the guardian targets of accounts that no longer exist. Otherwise they stay 10 to 15 minutes, with the warningguardian_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./ensurealso repairs a deployment whoseverifyfails. - 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.
| OS | Restart the gateway | Re-apply the deployment and restart every service |
|---|---|---|
| Linux | sudo systemctl restart defenseclaw-gateway.service | sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux repair --json |
| macOS | sudo launchctl kickstart -k system/com.cisco.defenseclaw.gateway | sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos repair --json |
| Windows | From an elevated PowerShell prompt: & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows repair --profile standalone | The same |
To stop the managed gateway, for example to see what your users get while it is down, and to start it again:
| OS | Stop the gateway | Start it again |
|---|---|---|
| Linux | sudo systemctl stop defenseclaw-gateway-hook.socket defenseclaw-gateway-api.socket defenseclaw-gateway.service | sudo systemctl start defenseclaw-gateway-hook.socket defenseclaw-gateway-api.socket defenseclaw-gateway.service |
| macOS | sudo launchctl bootout system/com.cisco.defenseclaw.gateway | sudo 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 itsenabled).ensurealso 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 channel | Remove the deployment and keep each user's data (Linux/macOS may keep sandbox state) | Remove everything |
|---|---|---|
| Linux payload | sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --json | Add --purge |
| Debian and Ubuntu package | sudo apt remove defenseclaw-enterprise | Run the lifecycle uninstall --purge --json first, then sudo apt purge defenseclaw-enterprise |
| RHEL package | sudo dnf remove defenseclaw-enterprise | Run the lifecycle uninstall --purge --json first, then sudo dnf remove defenseclaw-enterprise |
| macOS | sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos uninstall --json | Add --purge |
| Windows | Setup /uninstall JSON=1, or & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows uninstall --profile standalone --json from an elevated PowerShell prompt | Setup /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.
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --purge --json& 'C:\ProgramData\DefenseClaw-Staging\DefenseClawSetup-Enterprise-Standalone-x64.exe' /uninstall JSON=1 PURGE=1After 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
uninstallfirst, without purge. This also runs when a package install failed and rolled back.apt purgealso deletes what a failed uninstall left of/etc/defenseclaw,/var/lib/defenseclaw(including a kept sandbox store and key),/var/lib/defenseclaw-hook-guardianand/var/log/defenseclaw, and clears the lifecycle directory except forlifecycle.lock. Each user keeps~/.defenseclawand the per-user binaries, because the gateway that removes them is gone by then; runsudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --purge --jsonbefore you remove the package to remove those too. The MDMuninstall.sh --purgedoes this for you. A removal refused withuninstall_precheck_refusedor stopped withuninstall_incompletekeeps 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-resortrpm -e --nopreun defenseclaw-enterpriseremoves 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-sensorand its runtime directories (--keep-statekeeps 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.confnames thedefenseclawaccount 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_remainingand 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_remainingfor 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;ensurerestores 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.yamlto 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 withper_user_hooks_remaining. Fix or remove that row and run the uninstall again. - Per-user state (Linux and macOS).
--purgeremoves 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 removesdefenseclaw-gateway,defenseclaw-acp, the hook helpers (defenseclaw-hook-post,defenseclaw-hook-userand, on Linux,defenseclaw-sensor-helper), launcher links, theuvthe 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 inforeign-hooks-backupstay, and~/.defenseclawis 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
~/.defenseclawholdsconfig.yaml,.env,audit.db,previous/, or the program the per-user installer puts there,.venv/orinstaller/, also when the account never randefenseclaw init),--purgeleaves 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 aper_user_state_remainingwarning). 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 aper_user_state_remainingwarning). 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
~/.defenseclawwent 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 aftermv /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 (SSSDfallback_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 atargets.yamlrow 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 withPURGE=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 newtargets.yaml, and then goes on. No/repairis 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 removeandrpm -ealso 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 theguianduserlaunchd domains of every signed-in account, and removes thedefenseclawlauncher link and both plists from/Library/LaunchAgents. - MDM. Use
uninstall.sh [--purge]on Linux and macOS, oruninstall.ps1on 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_pendinganduser_registrations_failedwarnings. What stays is inert; see Windows: Remove. - Per-user state (Windows).
PURGE=1or--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 inforeign-hooks-backupstay; the folder is removed only when empty. The purge also removes the DefenseClaw files of a per-user install from%USERPROFILE%\.local\binand, once that folder is empty, the folder and its entry in the account's userPath. A signed-out account'sPathcannot be changed, so it keeps that entry. An account whose agent registrations stay (it had no active, connected session) keeps its.defenseclaw, whoseconnector_backupsrestore them; the purge still finishes. Theper_user_state_remainingwarning 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
-
Remove the device from the MDM assignment first. Otherwise the next scheduled
ensureinstalls DefenseClaw again. -
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
DefenseClawevent log. The systemd journal, the Windows Application event log and%WINDIR%\Logs\DefenseClaware not removed. See Logs and events. To review a retained audit database after purge, keep itsaudit.dband companionaudit.db-walandaudit.db-shmfiles together, then run/opt/defenseclaw/bin/defenseclaw-gateway audit export --db <copied-audit.db>as root on Linux (/opt/cisco/defenseclaw/bin/defenseclaw-gatewayon 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. -
Uninstall with purge, as in Uninstall.
-
Confirm that nothing remains:
OS Check Expected Linux systemctl list-unit-files 'defenseclaw*'No units Linux dpkg -s defenseclaw-enterpriseorrpm -q defenseclaw-enterpriseNot installed macOS pkgutil --pkg-info com.cisco.defenseclaw.enterpriseNo receipt macOS ls /opt/cisco/defenseclaw/lifecycleOnly lifecycle.lockWindows Test-Path 'HKLM:\SOFTWARE\Cisco\DefenseClaw\Enterprise'FalseWindows Get-Service DefenseClaw*No services -
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: denyto refuse its calls. On Windows, a cut-off SID must be refused, with an auditedenterprise_managed_sid_unregistereddecision 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 --jsonand 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; useunenrolled_users: denywhen 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.
Managed command availability
Which defenseclaw commands a standard user can run on a managed Linux, macOS or Windows computer, and which are refused, against a per-user install.
Troubleshooting
Fix a standalone DefenseClaw enterprise deployment by lifecycle error code, MDM wrapper code, hook refusal code, or symptom, on Windows, Linux, and macOS.