Upgrade, repair and remove

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 also a rolled_back warning. Look up the error 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, and the rollback does not remove it, even after a first install.

Only one lifecycle run works at a time. On Linux and macOS a run that finds another one in progress waits 5 seconds and exits 75 (busy); pass --lock-wait <duration> (at most 15m) to wait longer. The apply trigger and the deb, rpm and pkg install scripts wait up to 10 minutes, 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 (the macOS pkg has no removal script). On Windows a busy run exits 1618. MDM agents retry both.

A config.yaml or credential written while a run holds the lock is applied by a follow-up transaction of that run (warning input_changed). When the run fails instead, the apply trigger runs ensure again once it ends; a newer config.yaml written during a failed in-place apply is put back and applied then, and only the edit the failed run checked is kept as rejected.

The examples use these paths:

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

Upgrade

Windows

Run the new release's Setup with /ensure. When the Setup is newer than the installed version, ensure upgrades in place. It keeps the installed config unless you also pass CONFIG=.

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

• Setup accepts only absolute paths. It refuses relative paths and paths with environment variables in them.
• In Intune, make each new version supersede the previous app, with Uninstall previous version set to No.

Linux

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

VERSION=1.4.0   # the release you deploy
sudo apt install "./defenseclaw-enterprise-${VERSION}-linux-amd64.deb"

VERSION=1.4.0
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.

VERSION=1.4.0
sudo mkdir -p "/var/tmp/defenseclaw-${VERSION}"
sudo tar -xzf "defenseclaw-enterprise-${VERSION}-linux-amd64.tar.gz" -C "/var/tmp/defenseclaw-${VERSION}" --no-same-owner
cd "/var/tmp/defenseclaw-${VERSION}"
sudo ./defenseclaw-gateway enterprise linux upgrade --payload "$PWD" --json

Run the new release's defenseclaw-gateway from the extracted directory. The payload must be owned by root and must not be writable by group or others.

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=1.4.0
sudo installer -pkg "./defenseclaw-enterprise-${VERSION}-darwin-arm64.pkg" -target /
sudo cat /opt/cisco/defenseclaw/lifecycle/last-package-result.json

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, which re-renders the hooks and plugins of every user it covers, before it starts the new gateway. A user who was signed out during the upgrade is re-rendered by the guardian's pass at their next sign-in; until that pass 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, so that agent's telemetry is lost until the agent is restarted.

Roll back

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 (downgrade_refused).

• Linux packages. The package's install script runs ensure --from-package without --allow-downgrade, so after the package manager installs the older package the lifecycle refuses with downgrade_refused and records that in last-package-result.json. Run the ensure --from-package --allow-downgrade command above to apply the older release.
• macOS. The package's preinstall script refuses an older package before any file changes, unless the marker exists. The postinstall script passes --allow-downgrade to the lifecycle and deletes the marker, so each rollback needs a new marker.
• MDM wrapper. The Linux wrapper installs .rpm files with rpm -U, so it refuses older RHEL packages.

Change the config

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

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:\Staging\DefenseClawSetup-Enterprise-Standalone-x64.exe' /ensure CONFIG=C:\Staging\config.yaml JSON=1

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, so compliance checks see it. Push a corrected config to clear it; pushing the previous config again clears it too.

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 (for example a <policy_dir>/guardrail/default you created for a config that leaves rule_pack_dir out), but it does not track the contents of the files under policies. The gateway reads rule packs and policies when it starts, so after you edit a rule pack or policy in place, restart the managed gateway. A config change that points guardrail.rule_pack_dir at another folder is applied by ensure 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 applies a changed config stops and starts the services, so the new proxy is used. A config reload inside a running gateway reports a change to enterprise.network as restart-required and keeps the previous proxy until the gateway restarts. See Network proxy.

The profile cannot change in place. To move between Secure Client and standalone, uninstall one and install the other.

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. To force a user in or keep one out, change enterprise.enrollment in the config and apply it as described 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.

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

sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos repair --json

& 'C:\Staging\DefenseClawSetup-Enterprise-Standalone-x64.exe' /repair JSON=1

• 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 because they were not running, DefenseClaw's machine policy entries it rewrote, and the users and agents whose hooks the guardian rewrote. On a healthy deployment it says nothing to repair. The --json result carries the list as changes, and an ensure that re-applies the deployment lists its changes the same way.
• Linux and macOS, payload installs. 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.
• Linux package installs. To restore the binaries, reinstall the package: sudo apt install --reinstall ./<package>.deb or sudo dnf reinstall ./<package>.rpm.
• Deleted accounts (Linux and macOS). repair also removes the guardian targets of accounts that no longer exist. Otherwise they stay until the enumerator removes them, 10 to 15 minutes after the account is deleted: meanwhile status, verify and reconcile show the warning guardian_target_account_removed and do not fail on it. See New, changed and removed users.
• Windows. Use the Setup of the release that is installed. /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. This is the Setup form of --attest-claude-effective-policy. See Health fields.

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

Restart the managed gateway

defenseclaw-gateway start, stop and restart control the per-user gateway, and on a managed host they refuse, also when you run them as root; run as root, the refusal names the commands below. Restart the managed gateway through the service manager instead. On Linux systemd keeps the hook and API sockets open while the gateway restarts, so a hook that connects meanwhile waits; on macOS a hook that runs during the restart fails closed.

Restart the gateway after you edit a rule pack or policy file in place. Config changes, secrets and upgrades restart it on their own.

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; see below.
• It removes DefenseClaw's entries from vendor machine policy. Your own policy entries stay. On Linux and macOS it restores the preimages it recorded.
• It stops and removes the services.

Config, credentials, state, and logs stay unless you purge.

• Linux packages. Removing the package runs the lifecycle uninstall first. apt purge then deletes /etc/defenseclaw, /var/lib/defenseclaw, /var/lib/defenseclaw-hook-guardian, /var/lib/defenseclaw-enterprise, and /var/log/defenseclaw. It keeps the defenseclaw account. To delete the account, run sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --purge --remove-service-account --json before you remove the package.
• macOS. A pkg has no uninstaller. The lifecycle removes the binaries itself and forgets the package receipt (com.cisco.defenseclaw.enterprise).
• Registrations left (Linux and macOS). Each user's registrations are removed as that user. If one cannot be removed, the result has the error per_user_hooks_remaining for that user and agent, with the reason, and the uninstall stops before it removes the binaries those registrations run: the deployment record and state stay. Fix the cause, or remove DefenseClaw's entries from that user's agent config, and run the same uninstall again. ensure restores the deployment instead.
• Per-user state (Linux and macOS). --purge also removes each enrolled user's DefenseClaw folder (~/.defenseclaw, with its hook credentials), as that user. It first restores the files of any agent that DefenseClaw changed and still has backups for there, for example one set up by an earlier release. Two things stay: ~/.defenseclaw/foreign-hooks-backup (the user's own hooks that the foreign-hook policy moved aside) and the hook scripts in ~/.defenseclaw/hooks, each replaced by a stub that exits 0, because an agent that is still running may call it. Delete the folder once the user's agents have restarted.
• 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, OpenCode, and a DefenseClaw Copilot user hook file) from every signed-in user's agent config. An uninstall from an elevated administrator prompt or from Add/Remove Programs removes none, and users who are signed out 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, also removes each enrolled account's %USERPROFILE%\.defenseclaw, whether or not the account is signed in. The same two things stay as on Linux and macOS. The per_user_state_remaining warning names each folder it could not remove, with the reason.

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --purge --remove-service-account --json

& 'C:\Staging\DefenseClawSetup-Enterprise-Standalone-x64.exe' /uninstall JSON=1 PURGE=1

After an uninstall, ask users to restart running agents. An agent that loaded the hook command before the uninstall may report a hook launch failure until it restarts.

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 (where the uninstall run itself is logged) are not removed. See Logs and events.

3. Uninstall with purge, as shown in Uninstall.

4. Confirm that nothing remains:

   OS	Check	Expected
   Linux	systemctl list-unit-files 'defenseclaw*'	No units
   Linux	dpkg -s defenseclaw-enterprise or rpm -q defenseclaw-enterprise	Not installed
   macOS	pkgutil --pkg-info com.cisco.defenseclaw.enterprise	No receipt
   macOS	ls /opt/cisco/defenseclaw	No such directory
   Windows	Test-Path 'HKLM:\SOFTWARE\Cisco\DefenseClaw\Enterprise'	False
   Windows	Get-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. Each user's hook and telemetry credentials are bound to that user's uid or SID and authenticate only while the guardian's authorization ledger protects that user, so they stop working on the guardian's next pass after the removal. They never reach management routes, other connectors, or another user's identity.
• 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.
• Revoke ACP credentials. If the user has an ACP enrollment, revoke it with enterprise acp revoke and the same selectors you enrolled with. See ACP guard.
• 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.