Upgrade DefenseClaw

Upgrade

defenseclaw upgrade

defenseclaw upgrade downloads the installer of the latest release (install.sh on macOS and Linux, install.ps1 on Windows), checks it against that release's checksums.txt, and runs it. Because the upgrade logic ships with the release you are installing, a fix to the upgrade process reaches you with the next release. On Windows the installer continues in a new PowerShell window so the running command can let go of its files.

The installer:

1. Downloads the release and checks every file against checksums.txt. When cosign 2.0 or later is installed, it also verifies the release's Sigstore signature and stops if that fails.
2. Builds the new version next to the running one and checks that it starts, and that your configuration can be migrated, before changing anything.
3. Stops the gateway, keeps the current install in ~/.defenseclaw/previous, swaps in the new version, and runs defenseclaw migrate.
4. Starts the gateway and waits for it to report healthy.

If any step fails, the installer puts the previous version back, restarts it, and keeps the failed attempt in ~/.defenseclaw/.failed-<time> for troubleshooting. Your configuration (config.yaml, .env, policies), audit and inventory databases, device key, and connector setup are kept. Every run writes a log to ~/.defenseclaw/logs/.

If the defenseclaw command itself 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 | bash

irm https://github.com/cisco-ai-defense/defenseclaw/releases/latest/download/install.ps1 | iex

Update notices

When a newer release exists, interactive CLI 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. Turn it off with DEFENSECLAW_NO_UPDATE_CHECK=1 or update_check: false in config.yaml; on Windows the DisableSelfUpdate enterprise policy also turns it off. Nothing is ever installed without you running defenseclaw upgrade.

Upgrading from 0.x to 1.0

1.0 replaces the 0.x upgrade system, so how you start depends on what you have installed. Every path keeps your configuration and data.

• 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 instead.
• The installer imports the 0.x install in place. Installs older than 0.8.5 get the schema-v8 observability conversion that 0.8.5 introduced, and an installed local observability bundle is refreshed.
• On Windows, the installer also removes a 0.8.x native Setup installation (its program folder, sign-in start entry, Add/Remove Programs entry, and PATH entry). The old program files are kept in ~/.defenseclaw/previous/legacy-setup.
• To go back to 0.8.x afterwards, run defenseclaw rollback. To return to 1.x from there, run the install command again.

Rollback

defenseclaw rollback swaps the live install with the one the last upgrade replaced: binaries, Python environment, and the configuration and data as they were at upgrade time. Anything written since then moves into ~/.defenseclaw/previous and comes back if you roll forward; if you upgrade again instead, it is kept in ~/.defenseclaw/backups/rolled-back-<version>-<time>. One previous install is kept, and rolling back needs no network. Reinstalling the same version does not replace the rollback copy.

If an upgrade or rollback is interrupted (the terminal closes or the machine loses power), run the same command again. The installer first restores the install the interrupted run was replacing, then continues.

Migrations

defenseclaw migrate brings configuration and data to the current schema. The installer runs it after every swap; running it again is safe.

Renamed and removed connectors

Two connectors changed in this release. One is migrated for you; the other needs a one-time manual cleanup.

Windsurf is now Devin

Windsurf was renamed Devin Desktop (Cognition). DefenseClaw now protects it with the devin connector, which covers Devin CLI and Devin Desktop's default Devin Local agent: both read the same hook config. The old windsurf connector no longer exists.

The move is automatic. It runs during defenseclaw upgrade (the installer runs defenseclaw migrate), on the next defenseclaw-gateway restart, or when you run defenseclaw setup devin:

• In ~/.defenseclaw/config.yaml, guardrail.connector, claw.mode, and the windsurf key of every per-connector block (guardrail.connectors, asset_policy.connectors, application_protection.connectors, observability.connectors and connector_hooks) become devin. The old block keeps its settings (mode, hook_fail_mode, enabled, and so on). If a devin block already exists, it wins and the windsurf block is dropped; the upgrade output names the dropped key. The same rename applies to the connector name lists (guardrail.judge.hook_connectors, application_protection.include_connectors and exclude_connectors), to the connector of asset_policy rules (for example a denied rule or a registry entry), and to observability route selector.connectors.
• The gateway removes only the hook entries DefenseClaw wrote into ~/.codeium/windsurf/hooks.json. Hooks from other tools in that file stay. It checks the gateway user's home and, when the data directory is <profile>/.defenseclaw, that profile too.
• It deletes ~/.defenseclaw/hooks/windsurf-hook.sh (and windsurf-hook.ps1 if present) and ~/.defenseclaw/connector_backups/windsurf/, and clears windsurf from hook_contract_lock.json and active_connector.json.
• It installs the Devin hooks in ~/.config/devin/config.json (Windows: %APPDATA%\devin\config.json).
• The gateway log records one line that starts with Windsurf is now Devin Desktop: and names the files it changed. It reads moved connector "windsurf" to "devin" in <settings> of <config path> (listing each setting that moved) when the gateway made the rename itself, and removed state left by the retired connector ID when defenseclaw upgrade had already rewritten config.yaml.

What is not protected: conversations in Devin Desktop's legacy Cascade agent. New Devin Desktop tabs start on Devin Local, which is protected; existing Cascade conversations keep running without DefenseClaw hooks.

To confirm, run defenseclaw doctor and check that the Devin hook row passes, then open a new Devin Desktop tab or Devin CLI session.

Gemini CLI was removed

DefenseClaw no longer ships a Gemini CLI connector. For Google's agent, use Antigravity instead.

What defenseclaw upgrade and the gateway do for you:

• If another connector is configured, the upgrade removes geminicli from guardrail.connectors and moves guardrail.connector and claw.mode to the first remaining connector. The upgrade output names the connector it removed. (The same step removes any other connector name this release does not ship. While plugin_dir holds a plugin the gateway could load, it removes none: a plugin registers under the name its code reports, which need not match its folder or manifest, so the upgrade's preflight asks the new gateway before it counts a name as unshipped.)
• If Gemini CLI was your only connector (or every connector you configured is one this release does not ship), the upgrade stops before it changes anything. Its preflight, defenseclaw migrate --check, fails, names the connector and prints commands your installed release accepts (on releases before 0.7.0, which have no setup remove: set up a supported connector or edit config.yaml), and the installer reports that your configuration cannot be migrated and that nothing was changed. Your current release keeps running. Do step 1 on it, then run the upgrade again.
• On its next start, the gateway drops geminicli from its lock and active-connector state and deletes ~/.defenseclaw/hooks/geminicli-hook.sh (and geminicli-hook.ps1) and ~/.defenseclaw/hooks/.otlp-geminicli.token. It never edits ~/.gemini.

Once that script is gone, Gemini CLI cannot run DefenseClaw's hook. Gemini CLI treats a hook that fails with any exit code other than 2 as a non-blocking warning, so Gemini CLI keeps working and prints hook errors until you remove the entries in step 2.

Do this once, before you set up Antigravity:

1. Only if Gemini CLI was your only connector, or you replaced the package without running defenseclaw upgrade: remove it from DefenseClaw's config. When the upgrade stopped, run this on the release you still have: it refuses to remove the last connector without --force.

   defenseclaw setup remove geminicli --yes --force

   DefenseClaw then enforces nothing until step 7. You can instead set up another connector first (defenseclaw setup <connector>) and then remove Gemini CLI, or delete geminicli from guardrail.connectors and guardrail.connector in ~/.defenseclaw/config.yaml. Then run the upgrade again.

2. Open ~/.gemini/settings.json (or $GEMINI_CLI_HOME/.gemini/settings.json; on Windows %USERPROFILE%\.gemini\settings.json). Under hooks, look at each of these events: SessionStart, SessionEnd, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification. Delete every group whose hooks list contains "name": "defenseclaw", then delete any event key left empty. A DefenseClaw group looks like this:

   {
     "matcher": "*",
     "hooks": [
       {
         "name": "defenseclaw",
         "type": "command",
         "command": "/home/you/.defenseclaw/hooks/geminicli-hook.sh",
         "timeout": 30000,
         "description": "DefenseClaw hook inspection"
       }
     ]
   }

3. If telemetry.otlpEndpoint in the same file contains /otlp/geminicli/, delete the telemetry object or put back your own values.

4. Do not touch ~/.gemini/config/. That directory belongs to Antigravity.

5. Delete ~/.defenseclaw/connector_backups/geminicli/. The gateway already deleted ~/.defenseclaw/hooks/geminicli-hook.sh and ~/.defenseclaw/hooks/.otlp-geminicli.token; delete them too if they are still there.

6. Restart the gateway. (setup remove already did this unless you passed --no-restart.)

   defenseclaw-gateway restart

7. Set up Antigravity, or any other connector you use:

   defenseclaw setup antigravity

If config.yaml still names geminicli, the gateway refuses to start and its error points to this section. Step 1 fixes that. If a plugin directory is configured and plugin discovery fails, the gateway keeps names it cannot resolve and retries their teardown later instead of dropping them.

Native Windows installs from pre-release builds

Native Windows Setup builds made after 0.8.10 and before this release could select Windsurf or Gemini CLI. This release's Setup and uninstaller still read an install state that selected Windsurf: repair and upgrade switch the selection to devin, and the gateway removes DefenseClaw's Cascade hook entries on its next start. To remove such an install, upgrade it first and then uninstall, so that cleanup runs.

Native Windows installs made from pre-release main builds that selected Gemini CLI must be uninstalled with their original build before installing this release; this release's Setup and uninstaller refuse that install state. Then clean up Gemini CLI entries with the steps above.

Telemetry schemas no longer accept geminicli as a connector value. Rows that an older release exported with that value do not validate against the current schemas if you re-export them.

Troubleshooting