Upgrade DefenseClaw
Upgrade with one command. The latest release's own installer performs the upgrade, keeps your configuration and data, and rolls back on failure.
defenseclaw upgrade installs the latest release and keeps your configuration, audit data, device key and agent setup. 1.0.5 upgrades any 1.0 release and is tested from 1.0.4, 1.0.3 and 1.0.2. An upgrade from 0.8.8, 0.8.9 or 0.8.10 still runs, but it is a legacy path that is no longer tested; see Upgrading from 0.x to 1.0.
Upgrade
defenseclaw upgradeThe command downloads the latest release's installer (install.sh on macOS and Linux, install.ps1 on Windows), checks it against that release's checksums.txt and runs it. The installer:
- Downloads the release and checks every file. With
cosign2.0 or later installed, it also verifies the Sigstore signature and stops if that fails. - Builds the new version next to the running one and checks that it starts and that your configuration can be migrated.
- Stops the gateway, keeps the current install in
~/.defenseclaw/previous, swaps in the new version and runsdefenseclaw migrate. - Starts the gateway and waits for it to report healthy.
An upgrade refreshes the installed hooks. Per-user hooks honor an explicitly saved outage mode; when it is unset, the default and permissive policies let a gateway outage run with a warning, and strict blocks it. A verified gateway that gives no final decision blocks. An answered or local failure blocks; restart running agents so they discard old hook and native telemetry settings already loaded in memory. 1.0.0–1.0.3 setup also saved open on its own for an observe-mode Cursor, and those releases did not record whether the user chose it. The upgrade keeps that saved open, so strict does not close it, and names it with the defenseclaw config unset command that lets the policy tier decide. Managed standalone hooks default closed and honor an administrator's explicit outage-only open; Secure Client keeps its managed fail mode.
While an install or upgrade of your account runs, DefenseClaw refuses every agent call that gets no answer from the gateway. The window lasts as long as the installer holds its install lock (.install.lock in ~/.defenseclaw); in practice it is the time the gateway is stopped for the swap. It holds in every policy tier, with a saved open too: an install or upgrade is not a gateway outage, so the default policy's warning-and-run does not apply to a call that gets no answer. The strict policy tier also refuses calls the running gateway could answer. The agent shows this message (tool call reads prompt, tool result or request for other events):
DefenseClaw blocked this tool call: DefenseClaw is being installed or upgraded for this account, and its gateway starts again when that is done. Try again in a moment; if the installer has stopped, run the installer again to finish or undo the interrupted install.For a few seconds while the installer swaps the hooks, a hook from the release you upgrade from (1.0.4 or earlier) can show its own generic text instead, for example that the gateway is unreachable, that a gateway cold start failed, or that you should run defenseclaw-gateway restart. That text comes from the older release and cannot change; you do not need to restart anything, wait for the installer to finish and retry. How long the window lasts depends on the machine. The installer waits up to 3 minutes for a slow gateway start, and the window ends when the installer exits, also if it fails. Calls the gateway answers before the stop or after the start are not affected. Retry the step after the installer prints Installed DefenseClaw, or check with defenseclaw-gateway status. If the installer was killed, its lock counts only while the process that made it still runs; once that process is gone, calls follow the normal outage rule again, and you run the installer again to finish or undo the change.
An upgrade from 1.0.3 or an earlier 1.0 release prints this line once, after Upgraded from, when your configuration saves no hook fail mode for an active connector and its policy tier now lets a gateway outage run:
Gateway outages now let calls run with a warning (the default and permissive policies). Run `defenseclaw guardrail fail-mode closed` to keep blocking them.Releases before 1.0.4 blocked those calls. The line is not printed when a fail mode is saved (globally or for a connector), in the strict tier, or on a managed install. How the saved mode and the policy tier combine is in Fail modes.
When sandboxes are on (openshell.enabled: true) and your OpenShell gateway runs a release older than 0.1.6, the upgrade also prints, after Upgraded from, why no sandbox runs and the fix. defenseclaw doctor fails its Gateway check until OpenShell is upgraded:
Sandboxes: OpenShell 0.1.3 runs no DefenseClaw sandbox: OpenShell 0.1.6 or later is required; upgrade OpenShell to 0.1.6 in place. Until then DefenseClaw starts no sandbox and `defenseclaw doctor` fails its Gateway check. Stop running sandboxes first, then run: defenseclaw sandbox setup --install-openshellEnd every running agent session before upgrading. Quit OpenCode and Amp
processes completely, then start a new agent process after the installer
reports the gateway healthy. OpenCode and Amp load their DefenseClaw plugin
once per process. The installer checks for running OpenCode and Amp processes
before stopping the gateway and refuses the swap if it finds one; close it and
run the installer again. A previous release's plugin already loaded in memory
cannot gain the new install-lock check: with hook_fail_mode: open, it may
allow tool calls if the gateway is stopped, even after the installer replaces
the plugin on disk. Keep those agents closed until the gateway is healthy.
Managed installs keep the fail mode the administrator set.
If a step fails, the installer puts the previous version back, restarts it and keeps the failed attempt in ~/.defenseclaw/.failed-<time>. Every run writes a log to ~/.defenseclaw/logs/. On Windows the installer continues in a new PowerShell window so the running command can release its files.
| Command | What it does |
|---|---|
defenseclaw upgrade | Upgrade to the latest release. Asks before changing anything. |
defenseclaw upgrade --yes | The same, without prompting. |
defenseclaw upgrade --version X.Y.Z | Install a specific release, newer or older. |
defenseclaw rollback | Put back the install that the last upgrade replaced. Run it again to roll forward. |
defenseclaw migrate --check | List pending config migrations. Exit 0: can be applied. 1: cannot. 2: the config is from a newer release. |
To go back to an earlier release, use defenseclaw rollback or defenseclaw upgrade --version X.Y.Z. Running an older release's installer (install.sh or install.ps1 of that release) directly over a newer install is not a supported downgrade: the older installer does not know the hook entries the newer release wrote. On Windows it adds its own Claude Code hook beside them: until the repair below, Claude Code tool calls fail in the older release's hook (unknown flag: --connector), and defenseclaw doctor reports two DefenseClaw PreToolUse handlers. If that happened, run the newer release's install command again, then go back with one of the two commands above.
Going from 1.0.4 straight to 1.0.2 on macOS or Linux, with either command or with the 1.0.2 installer, leaves a hook helper that 1.0.2 cannot use, so every agent hook call prints an error. See defenseclaw_api_listener_foreign: command not found after going back to 1.0.2. From 1.0.5 on, going back to 1.0.2 is clean.
If the defenseclaw command does not start, run the install command again. It repairs any install and keeps your data:
curl -LsSf https://github.com/cisco-ai-defense/defenseclaw/releases/latest/download/install.sh | bashirm https://github.com/cisco-ai-defense/defenseclaw/releases/latest/download/install.ps1 | iexOpen a new terminal afterwards if the installer asks you to.
Running sandboxes refuse tool calls while the gateway restarts
A running OpenShell sandbox keeps running, but its hooks fail closed while the gateway is stopped (usually under a minute). Upgrade between sessions, or let the agent retry afterwards.
An upgrade from 1.0.3 or earlier refuses, and changes nothing, while that release's gateway runs a sandbox. Those sessions keep the network broker of the OpenShell release they started with, which DefenseClaw cannot contain. The installer names each one with the command that ends it: defenseclaw sandbox stop NAME, or defenseclaw sandbox delete NAME for a completed or failed MicroVM, which deletes its work. Save the work you need, end them, then run the upgrade again. When the gateway is not running the installer cannot ask it, so end your sandboxes before you upgrade.
For a legacy MicroVM guest, save accessible work before upgrading. If it is ready afterward, keep the guest: run defenseclaw sandbox stop NAME and defenseclaw sandbox start NAME. See Known limits for completed or failed guests and data-loss risks.
Update notices
When a newer release exists, interactive commands and the TUI show one line: DefenseClaw X.Y.Z is available (you have A.B.C) — run 'defenseclaw upgrade'. The check runs at most once a day and never in scripts, JSON output or CI. Nothing is installed unless you run defenseclaw upgrade. Turn the notice off with defenseclaw config set update.check false. To install from a mirror, see Update settings and mirrors.
Update settings
| Key | Default | What it does |
|---|---|---|
update.check | true | Show the update notice. Also off with DEFENSECLAW_NO_UPDATE_CHECK=1. |
update.channel | stable | The release channel. stable is the only one. |
update.source | https://github.com/cisco-ai-defense/defenseclaw | Where release files come from. Set an https:// base URL for a mirror. |
defenseclaw config set update.check falseOn Windows the DisableSelfUpdate enterprise policy also turns the notice off. A managed device does not self-update; the lifecycle applies updates.
Install from a mirror
defenseclaw config set update.source https://mirror.example.com/defenseclawThe mirror must serve the paths GitHub serves: releases/latest (a redirect to the newest tag) and releases/download/<tag>/ with the installer, the release files, checksums.txt and checksums.txt.bundle.
update.source changes only where files come from. The certificate identity that signed the official releases is built into DefenseClaw, so a mirror must serve the official signed checksums.txt and its bundle, and the machine needs cosign 2.0 or later. Without it, the upgrade stops before it runs anything. update.source must be an https:// URL: defenseclaw config set refuses an http:// one and asks for an https:// URL. DEFENSECLAW_REPO is the deprecated alias and takes a GitHub owner/name or an https:// URL, with the same refusal for anything else; update.source wins when both are set. A first install has no config.yaml, so use DEFENSECLAW_REPO for the installer there (Installer).
Upgrading from 0.x to 1.0
1.x replaces the 0.x upgrade system. Every path below keeps your configuration and data. The 0.8.10 release is the bridge: a 0.8.8, 0.8.9 or 0.8.10 install finds the 1.x release through its own defenseclaw upgrade. This is a legacy path that is no longer tested. On Windows, the 0.8.10 Claude Code hook can let tool calls run without a check while the upgrade runs, and the upgrade does not check that every hook an agent registered was replaced: end every agent session before you upgrade from 0.8.x and start new ones afterwards.
Which command to run
| Installed | Run |
|---|---|
| 0.8.8, 0.8.9 or 0.8.10 on macOS or Linux | defenseclaw upgrade --yes |
| 0.8.7 or older on macOS or Linux | The install.sh command on Install |
| Any 0.x version on Windows | The install.ps1 command on Install |
| The 0.8.x macOS app | Download DefenseClawMac-<version>-macos-arm64.dmg from the latest release once; later updates use the app's Update button |
defenseclaw upgrade on 0.8.7 or older, and on Windows, stops with a message such as missing release-provenance.json; refusing before services are stopped. Nothing was changed; use the install command.
What changes
config.yamlbecomes the only place your policy lives (config_version: 9). Under the derived admission gate, LOW and INFO skill findings now allow. With a judge, the skill scanner defaults toquiet;warnfindings enter the review queue.- Audit retention (
observability.local.retention_days) defaults to 7 days; 0.8.x used 90. Restore it withdefenseclaw config set observability.local.retention_days 90. - A new audit history starts. The first time 1.x opens the audit database it deletes the audit events, scan results and findings 0.x recorded (a one-time privacy cutover: 0.x history can hold unredacted content). The installer says so before it upgrades. Configuration, inventory and connector setup are kept. The 0.x database stays in
~/.defenseclaw/previous/data/audit.db, anddefenseclaw rollbackbrings it back. The next upgrade moves it to~/.defenseclaw/backups/audit-history-<version>-<time>; remove that folder when you no longer need it. - A damaged 0.8.x audit database (SQLite "Rowid N out of order") is rebuilt in place. One that cannot be rebuilt is kept as
audit.db.corrupt-<time>, anddefenseclaw doctorlists it. Work on a copy of the main file with its-wal,-shmand-journalfiles; never repair the archive itself. - Existing MCP servers keep running. At its first start the gateway records a baseline for each one (one scan; findings raise alerts) instead of admitting it again. A server the scanner cannot start shows
scan failedindefenseclaw mcp listand is not blocked. A server on a block list stays blocked. See MCP servers that can no longer be scanned. - Installs older than 0.8.5 get the schema-v8 observability conversion first, and an installed local observability bundle is refreshed.
- Shared hosts:
defenseclaw-gateway startandrestartin 0.8.4 and older stop every gateway process the account may signal. Do not run them withsudoon a shared host. 0.8.5 and later stop only their own.
Windows: moving from the Setup package
Run the install.ps1 command. The installer imports a 0.8.x DefenseClawSetup-x64.exe installation: it stops its gateway, removes its program folder, sign-in entry, Add/Remove Programs entry and PATH entry, keeps your configuration and data in %USERPROFILE%\.defenseclaw, and keeps the old program files in %USERPROFILE%\.defenseclaw\previous\legacy-setup. Connector hooks are rewritten to the new paths when the gateway starts. The /repair, /uninstall and DELETEUSERDATA=1 options of the old Setup do not apply.
The installer's summary says the audit history 0.8.10 recorded is not carried over and names the copy under previous\data\audit.db.
To check an old DefenseClawSetup-x64.exe, compare its SHA-256 (Get-FileHash -Algorithm SHA256) with its entry in that release's checksums.txt, after verifying the signature of checksums.txt. The 0.8.x Setup files are not Authenticode-signed, so their own /verify always fails; that does not mean the file changed.
Rollback
defenseclaw rollbackRollback swaps the live install with the one the last upgrade replaced: programs, Python environment, configuration and data as they were at upgrade time. Anything written since moves into ~/.defenseclaw/previous and returns when you roll forward. One previous install is kept, and rollback needs no network.
A previous install that never ran defenseclaw init has no configuration, and what rollback does then depends on the gateway:
-
If the gateway is running, rollback must start the previous gateway, which refuses with
no config.yaml exists yet. Rollback then undoes itself and exits 1; the current install stays, with its gateway. The installer also says the previous install's files are in~/.defenseclaw/previous/dataand to fix the cause and run rollback again. There is nothing to fix there: stay on the current install, or stop the gateway withdefenseclaw-gateway stopand roll back as below. -
If the gateway is stopped, rollback completes and exits 0, and the previous install runs with no
config.yaml. Rundefenseclaw initto set it up, or rundefenseclaw rollbackagain to roll forward to your current install and its configuration. -
Between releases from 1.0.1 on, rollback also carries your sandbox setup: sandbox records, hook bindings and harness images. A release before 1.0.1 cannot take over that setup.
-
After rolling forward again, a retained sandbox can still run the older release's supervisor even when the restored gateway is healthy. If
sandbox connect NAMEsayslegacy sandbox running, save accessible work first (defenseclaw sandbox pull NAME --applyfor a copy, or--branchor--patch-out FILE) and confirm the project, branch or patch file contains it, then rundefenseclaw sandbox stop NAME,defenseclaw sandbox start NAMEanddefenseclaw sandbox connect NAME. A MicroVM stop requests a disk sync; if the sync fails, changes since its last successful sync may be lost. Keep the gateway running until you have saved work you need. -
Each install shows only its own audit events. Read the other install's with
~/.defenseclaw/previous/bin/defenseclaw-gateway audit export --db ~/.defenseclaw/previous/data/audit.db. -
Rollback restarts the restored gateway if the current gateway is running or the saved install records that it was running, and waits up to 3 minutes. If both were stopped, the restored gateway stays stopped; start it with
defenseclaw-gateway startwhen you are ready to resume agent work. This also applies when rolling back to 0.8.x and rolling forward again. If a required restart does not start or, on Windows, cannot be proven, rollback exits1and the installer undoes the rollback. On Windows that exit code is the installer's: from a desktop terminal,defenseclaw rollbackexits0once the installer window has opened its log (it waits up to 450 seconds, and exits1when the installer ends before it opens a log or is still running without one after the wait), so read the result in that window or its log (%USERPROFILE%\.defenseclaw\logs\install-<time>.log), then checkdefenseclaw --versionanddefenseclaw doctor. On Windows, it tries to restart and prove the install it started from. If recovery remains pending, the installer keeps the lifecycle record and install lock. On Windows, when recovery is unfinished, the gateway is down and a hooks directory exists, the installer tries to close installed hooks. If hook closure succeeds, they block tool calls until the gateway runs again. If the gateway is running or no hooks directory exists, the installer does not force hooks closed. If the installer warns that hooks could not be closed, they follow the configured outage fail mode, so a hook configured open may allow tool calls. Stop agent activity, fix the reported cause and run the recovery command the installer prints. Then retrydefenseclaw rollback. -
On Linux and macOS, an incomplete restore leaves an unfinished snapshot or rollback hold; run the same install command again to put the previous install back. The installer does not force hooks closed during that pending recovery. Existing hooks that run while the gateway stays down follow their configured outage mode: in
closedthey block calls they receive, and inopenthey may allow them. Stop agent activity until recovery finishes. -
If undoing the rollback also fails, either installer can report the rollback target installed with its gateway down and agent hooks not guarded. Windows then attempts the hook closure above if its conditions are met. Stop agent activity and follow the recovery command the installer prints.
-
If an upgrade or rollback is interrupted, run the same command again. The installer first restores the install it was replacing.
-
Rolling back to 0.8.x, and the Windows 0.8.7-0.8.10 Setup case, are covered in Roll back to 0.8.x.
-
Running the installer again for the build you have is a repair: it keeps the rollback copy you have. Installing another build of the same version, such as the next release candidate, works like an upgrade: the installer says before the swap that it keeps the installed build in
~/.defenseclaw/previous, and rollback returns to that build. -
On Windows,
defenseclaw rollbackto a release that checks the Codex program it set up (1.0.4 and later) is refused before anything changes when Codex was updated after DefenseClaw set it up, or is no longer where it was. The refusal names Codex and the file, then says:DefenseClaw <version> does not start with an agent program it did not set up, so the rollback would stop half-way. Nothing was changed. Put that version back and run 'defenseclaw rollback' again, or stay on DefenseClaw <current>. A rollback to 1.0.0-1.0.3 or 0.8.10 completes with a warning instead: that release starts without Codex hooks until you rundefenseclaw setup codexafter the rollback. -
On Windows, when the previous install's folder belongs to another account and cannot be removed or set aside, the new rollback copy is kept in
.failed-kept-previous-<time>-new(or the older one in.failed-kept-previous-<time>). The summary then replacesUndo with: defenseclaw rollbackwith the steps to undo: an administrator removesprevious, you rename the kept folder toprevious, then rundefenseclaw rollback. Remove the kept folder when you no longer need it. -
Before it runs the saved installer, rollback checks it against the SHA-256 the install recorded in
~/.defenseclaw/receipts/installer.sha256. If the installer was changed after the install, rollback stops and changes nothing.defenseclaw upgrade --version <your version> --yessaves a verified copy again.
Roll back to 0.8.x
On a managed Linux or macOS computer with bundle trust anchors, a rollback must
also meet the confirmed bundle's min_product_version. See Roll
back and the release floor
limits, including
packages older than 1.0.4 and Windows Setup.
defenseclaw rollback restores the version 8 config.yaml saved when the upgrade started, with data.json and the block and allow entries in audit.db. Policy edits you made after the upgrade stay in ~/.defenseclaw/previous and return when you roll forward. 0.8.x has no rollback command. To return to 1.x, run the command the rollback prints, or run the install command again:
bash ~/.defenseclaw/previous/installer/install.sh --rollbackA 0.8.x release you install yourself, without defenseclaw rollback, refuses a version 9 file (Configuration schema v8 is required); Going back to 0.8.x lists the manual steps.
A Windows 0.8.7-0.8.10 Setup install cannot be restored by defenseclaw rollback; it refuses and changes nothing. Run defenseclaw uninstall, download that release's DefenseClawSetup-x64.exe and run it in your desktop session. Your data from before the upgrade is in %USERPROFILE%\.defenseclaw\previous.
Agent hook entries live in each agent's own settings, so the swap does not restore them. Before it restores the older install, the rollback has the current gateway rewrite every hook entry the older release would not recognise, so that release's defenseclaw uninstall still removes it. The settings file from before the change is kept in ~/.defenseclaw/previous/data/backups/claudecode-settings.before-rollback.json. If the rewrite fails, the rollback still completes and warns; remove those entries from the agent's settings by hand.
Migrations
defenseclaw migrate brings configuration and data to the current schema. The installer runs it after every swap; running it again is safe. --check lists the pending steps without changing anything.
| Exit code | Meaning |
|---|---|
0 | Done, or nothing to do |
1 | A step failed; the installer restores the previous install |
2 | The configuration was written by a newer DefenseClaw than this one |
Config migration
The step from config_version: 8 to 9 moves the decisions 0.8.x kept outside config.yaml into it: admission and thresholds from policies/rego/data.json, the skill_actions, mcp_actions and plugin_actions keys, rule_pack_dir, the scanner switches, and your skill, MCP server and plugin block and allow entries from audit.db. It keeps config.yaml.v8.bak, renames data.json to data.json.migrated-v9, and writes migration-v9.json with every value it moved and every conflict it settled. An unmodified install moves one value. defenseclaw doctor shows a Config migration row until you run defenseclaw config migrate --ack. Preview with defenseclaw config migrate --dry-run. Until the file is migrated, the gateway reads a version 8 file as if it were migrated, in memory only.
Migrate config.yaml from v8 to v9 shows before and after for every key and covers going back. On a managed standalone host, the lifecycle migrates the administrator config.
Block and allow entries keep applying across an upgrade, but config.yaml records no time for them: tool list shows UPDATED as - for every entry there, before and after an upgrade, and an entry moved from 0.8.x audit.db does not keep its 0.8.x time.
One built-in policy is retired: 0.8.x listed the host-firewall template firewall-deny-default as a policy. 1.0 has three named policies, default, strict and permissive; policy list no longer shows the template and policy activate refuses it.
Shipped policy files
Every upgrade brings the Rego modules in ~/.defenseclaw/policies/rego (admission.rego, guardrail.rego) to the new release. The previous copies go to ~/.defenseclaw/backups/rego-<time>/. A module you edited is replaced too, and the upgrade names it; re-apply your change from the backup, or keep your own rules in a file of another name. An unmodified module the release no longer ships, such as the 0.8 sandbox.rego, moves to the same backup. Unedited guardrail rule packs in ~/.defenseclaw/policies/guardrail are updated the same way; an edited pack is kept.
defenseclaw init writes a missing module, updates an unedited one and keeps an edited one. A policy_dir outside ~/.defenseclaw is left alone; the upgrade lists the modules there that differ. A policy_dir written as ~/<folder> is saved as an absolute path.
Troubleshooting
Fixes for installer messages and failed upgrades on macOS, Linux and Windows.
- Known limits: Claude Code's typed shell, Codex, Copilot CLI, Antigravity, the local Splunk bridge, managed Linux and macOS scans, scanners on macOS, Linux sign-out, identity, upgrade and policy limits, agent messages that are not from DefenseClaw, and sandboxes.
defenseclaw: command not found
Cause. ~/.local/bin is not on your PATH (macOS and Linux), or the terminal predates the install (Windows).
Fix. Run the line the installer printed, add it to your shell profile and open a new shell. On Windows open a new terminal. If the launcher is missing, run the install command again.
Check. defenseclaw --version prints a version.
The installer stops before changing anything
Cause. The platform is unsupported: an Intel Mac, Windows on ARM64 or x86. Rosetta and x64 emulation do not change that.
Fix. Use a supported computer (Install).
Check. The installer's message names the unsupported architecture.
Installer exit code 3
Cause. DefenseClaw is installed, but a connector refused to start, usually because the agent updated. The installer says A connector needs attention before it is guarded again (see the gateway output above).
Fix. defenseclaw doctor, then the next step on the failing row.
Check. defenseclaw doctor shows the connector row as [PASS].
Installer exit code 4
Cause. DefenseClaw is installed, but the first-run quickstart failed.
Fix. Run the defenseclaw quickstart ... command the installer printed once the cause it named is fixed.
Check. The report says status=ready.
DefenseClaw blocked this tool call: DefenseClaw is being installed or upgraded for this account
Cause. An install or upgrade of your account holds its install lock. While it runs, agent calls that get no answer from the gateway are refused in every policy tier, and in the strict tier every call is.
Fix. Wait for the installer to print Installed DefenseClaw, then try again. If the installer window is gone or the installer was stopped, run the install command again to finish or undo the change.
Check. The agent call runs, and defenseclaw-gateway status shows the gateway running.
Another DefenseClaw install is running
Cause. An install or upgrade holds the lock (.install.lock in ~/.defenseclaw). A lock is stale only when the process that made it is gone, or when its process id now belongs to another process; the next install clears a stale lock. A lock whose process still runs is never cleared, however long it has run. defenseclaw doctor lists the lock, and defenseclaw doctor --fix removes a stale one.
Fix. Wait for it to finish, then run the command again.
Check. The command proceeds.
Another DefenseClaw install or doctor run is taking over the install lock
Cause. Another installer, or defenseclaw doctor --fix, is taking over the same stale lock. Only one of them may do it, and this one waited 10 seconds for the other to finish.
Fix. Let the other run finish, then run the command again.
Check. The command proceeds, or reports Another DefenseClaw install is running while the other install runs.
Previous hook calls did not finish within 30 seconds before stopping the gateway (Windows)
Cause. After it replaces the hook program, the installer waits for every agent call that started with the old one. One of them ran longer than 30 seconds, or its start time could not be read (Cannot prove that previous hook calls finished before stopping the gateway). Nothing was left half-done: the installer restores the previous install.
Fix. Close the agents, then run the install command again.
Check. The installer gets past the hook swap and prints Installed DefenseClaw.
Could not copy <file> (...) (Windows)
Cause. The installer could not copy a file from ~/.defenseclaw into its rollback folder. The message gives Windows' reason and lists any DefenseClaw program still running, for example DefenseClaw programs still running: defenseclaw-gateway (PID 4120) (stop them with Stop-Process -Id <PID>).
Fix. Stop the program the message names with Stop-Process -Id <PID>, or give your account read access to the file (icacls "<file>" shows who has it). Run the installer again.
Check. The installer gets past the copy.
DefenseClaw is in use by ... (Windows)
Cause. A program, such as the DefenseClaw TUI, has files in the install open. The installer waits up to a minute, then stops. Nothing was changed.
Fix. Close the programs the message lists and run the installer again.
Check. The installer proceeds.
Could not save the current install; nothing was changed (macOS and Linux)
Cause. The installer could not copy the current install and its data into the rollback folder. The usual reason is disk space: it then also prints Not enough free disk space next to ... for a rollback copy, with the size it needs and the largest item. The installer put the old gateway back and changed nothing.
Fix. Free the space it names (df -h ~/.defenseclaw shows what is left) or move the largest item elsewhere, then run the installer again. If the disk is fine, check that your account owns ~/.defenseclaw.
Check. The installer proceeds.
defenseclaw upgrade changes nothing over SSH (Windows)
Cause. The installer continues in a new window, and an SSH session has no desktop.
Fix. Run the powershell -File ... install.ps1 command the message prints, in the same terminal.
Check. The installer shows its result and sets the exit code.
The installer ended with exit code N before it opened its log (Windows)
Cause. defenseclaw upgrade and defenseclaw rollback start the installer in a new window and wait up to 450 seconds for it to open its log in ~/.defenseclaw/logs (an installer waits up to 300 seconds for the cleanup of an earlier defenseclaw uninstall, and one that fails keeps its window for up to 120 seconds, so the command can take that long to report). The installer ended first, with exit code N. Usually it refused to start (for example an earlier install or rollback left its lock or record) and changed nothing, but an installer that cannot write its log goes on without one, so the command cannot tell the two apart and the result is not known. The reason was shown in the installer's window, which closed.
Fix. Run defenseclaw --version and defenseclaw doctor. The command keeps a copy of the installer in a defenseclaw-recovery-<id> folder of its own (the installer deletes the folder it runs from), checks the copy against its SHA-256 and prints the powershell -File ... command that runs it in your terminal, where it shows the result and sets the exit code. If the copy is gone or no longer matches, it prints the defenseclaw upgrade or defenseclaw rollback command you ran, which starts again through the shim and the installer of the version you have (it never prints the release installer of an older version). The copy is kept when the installer opened its log, because an open log does not yet show the result. Or run the same command again, which first restores an install the installer was replacing. Fix the cause it names.
Check. The command prints The installer continues in a new window and install-<time>.log appears in ~/.defenseclaw/logs.
If the command prints is still running and has not opened its log after 450 seconds, so the start is not confirmed and exits 1, the installer had no log yet (it can wait on another install or hold an error in its window). Read its window, let it end before you start another install, then check defenseclaw --version.
Your configuration is from a newer DefenseClaw than X
Cause. You installed an older release over data from a newer one.
Fix. defenseclaw rollback, or install the newer release again.
Check. defenseclaw migrate --check exits 0.
defenseclaw_api_listener_foreign: command not found after going back to 1.0.2 (macOS and Linux)
Cause. You went from 1.0.4 straight to 1.0.2. 1.0.2 keeps the newer hook helper ~/.defenseclaw/hooks/_hardening.sh that 1.0.4 wrote, and that helper lacks a function the 1.0.2 hooks call. Each agent hook call then prints ~/.defenseclaw/hooks/<agent>-hook.sh: line <n>: defenseclaw_api_listener_foreign: command not found. The gateway still checks the call.
Fix. On 1.0.2, remove the helper and restart the gateway, which writes 1.0.2's own:
rm ~/.defenseclaw/hooks/_hardening.sh
defenseclaw-gateway restartOr go from 1.0.4 to 1.0.5 first, then back to 1.0.2: the 1.0.5 helper keeps that function.
Check. The next agent tool call prints no command not found line.
The running gateway did not stop
Cause. The old gateway ignored the stop. Nothing was changed.
Fix. defenseclaw-gateway stop, then run the upgrade again.
Check. The upgrade completes.
missing release-provenance.json; refusing before services are stopped
Cause. defenseclaw upgrade cannot upgrade 0.8.7 or older, or any 0.x on Windows.
Fix. Run the install command from Install. See Upgrading from 0.x to 1.0.
Check. defenseclaw --version shows the new version.
An upgrade failed
Cause. A step failed. The installer put the previous version back and kept the attempt in ~/.defenseclaw/.failed-<time>.
Fix. Read the newest log in ~/.defenseclaw/logs/, fix what it names, run defenseclaw upgrade again. A cut-off run restores the install it was replacing first.
Check. defenseclaw version shows OK All components in sync.
Renamed and removed connectors
Windsurf became Devin, and Gemini CLI, OpenHands and OmniGent were removed. The upgrade handles Windsurf for you, and removes what DefenseClaw wrote for OpenHands and OmniGent: DefenseClaw no longer guards them.
This applies if you used Windsurf, Gemini CLI, OpenHands or OmniGent before 1.0.5.
- Windsurf is now Devin. The upgrade moves your
windsurfsettings to thedevinconnector and replaces the old hooks. You do nothing. - Gemini CLI was removed. Use Antigravity. Remove DefenseClaw's hooks from Gemini CLI's settings once.
- OpenHands and OmniGent are no longer supported. 1.0.4 removed their setup, and 1.0.5 also removes what an older DefenseClaw wrote for them: DefenseClaw no longer guards either agent and never blocks it. The
config_version9 migration drops their entries fromconfig.yaml, including a telemetry destination whose every route selected only these connectors (defenseclaw migratesaves that), and records them inmigration-v9.json. On the first gateway start after the upgrade, duringdefenseclaw upgradeand the installers, and indefenseclaw uninstall, DefenseClaw removes only what it wrote, by identity: its hooks in OpenHands'hooks.json(~/.openhands/hooks.jsonor a workspace.openhands/hooks.json; every hook whose command runsopenhands-hook.sh, a copy or hard link of DefenseClaw's hook script, ordefenseclaw-hook --connector openhands),defenseclaw_omnigent_policyin OmniGent'spolicy_modulesand every policy that calls it (in~/.omnigent/config.yamlor the fileOMNIGENT_CONFIGorOMNIGENT_CONFIG_HOMEselects), its line indefenseclaw_omnigent.pth, its hook script or policy module in~/.defenseclaw/hooks(including the stub 1.0.4 wrote there), its tokens,.hookcfg.<connector>, its setup receipts in~/.defenseclaw/connector_backups/<connector>and its entry in the hook contract lock. Your own hooks, policies and import-path lines stay, and so does any other connector's file. None of these steps fails an upgrade, repair, ensure or uninstall. They print one line,OpenHands/OmniGent support was removed in 1.0.5; DefenseClaw no longer guards it., anddefenseclaw statusanddefenseclaw doctorshow it as one information row (never a failure) while something is left that DefenseClaw could not remove, such as ahooks.jsonit cannot parse or an edited policy module 1.0.4 saved inconnector_backups, each with the step to remove it by hand.defenseclaw uninstall --allmoves anything left inconnector_backups/<connector>to~/.defenseclaw-removed-connector-backups/<connector>before it removes the data folder. Restart OmniGent after the upgrade if it was running: a process that loaded the old policy module keeps it until then. A rollback to a release before 1.0.5 puts back the OpenHandshooks.jsonentries and OmniGent settings the teardown changed, as long as each file is still what the teardown left; the originals are kept inremoved_connectors_rollback.jsonin the data folder. Managed installs have no rollback and record nothing. Aconfig.yamlthat still lists either agent prints one note per command that names the file and says they are ignored. The upgrade accepts aconfig.yamlthat still lists them next to another connector. If OpenHands or OmniGent is the only connector it lists, the upgrade stops before it changes anything, because the new gateway would have no connector to start: with the DefenseClaw you have now, rundefenseclaw setup remove openhands --yes --force(oromnigent), or set up another connector, then upgrade again.