Install and maintain

The supported package is DefenseClawSetup-x64.exe, a self-contained native installer for the signed-in Windows user. It installs the product, embedded runtime, and maintenance copy as one transaction.

System requirements

The optional Docker-backed local observability and Local Splunk bundles have a narrower requirement: Windows x64 Pro, Enterprise, or Education; Hyper-V; machine-installed Docker Desktop; Linux containers; a reachable daemon; Compose v2; and a real native docker.exe. Windows Home, per-user Docker Desktop, WSL2 engines, Windows containers, and command-wrapper shims are not in that optional feature's certified path. Core DefenseClaw does not require Docker.

Fresh install

Get-AuthenticodeSignature -LiteralPath ".\DefenseClawSetup-x64.exe" |
  Select-Object Status, StatusMessage, SignerCertificate
Get-FileHash -Algorithm SHA256 -LiteralPath ".\DefenseClawSetup-x64.exe"
& ".\DefenseClawSetup-x64.exe" /verify

Quiet install

Quiet mode suppresses the wizard while still running from the signed-in user's interactive desktop session. It is not a service, SYSTEM, elevated Intune/SCCM agent, scheduled task, background/batch, or session-zero installer surface.

& ".\DefenseClawSetup-x64.exe" /quiet /norestart INSTALLSCOPE=user CONNECTOR=codex MODE=observe STARTGATEWAY=1

DefenseClawSetup-x64.exe /quiet /norestart INSTALLSCOPE=user CONNECTOR=codex MODE=observe STARTGATEWAY=1

Use CONNECTOR=claudecode for Claude Code or CONNECTOR=amp for Amp. To install without configuring an agent or starting the gateway, use CONNECTOR=none STARTGATEWAY=0. STARTGATEWAY=0 cannot leave a Codex, Claude Code, or Amp installation stopped: those connectors require gateway startup and current-user logon integration.

Public Setup properties are:

Do not use internal handoff properties shown in diagnostic process listings as operator controls.

Configure after installation

For guided configuration:

defenseclaw init

For explicit supported connectors:

defenseclaw setup codex --mode observe
defenseclaw setup claude-code --mode observe
defenseclaw setup amp --mode observe

One local gateway can host any or all three. Add connectors without removing an existing one:

defenseclaw setup `
  --connector codex `
  --connector claudecode `
  --connector amp `
  --mode observe `
  --restart `
  --yes

Setup records validated CODEX_HOME and CLAUDE_CONFIG_DIR values when they are used. Repair and upgrade preserve those recorded homes instead of following later environment drift. Amp has no connector-home override: its system plugin uses %USERPROFILE%\.config\amp\plugins\defenseclaw.ts. The packaged data root itself is fixed to the current Windows profile; see Path and override rules.

Fully restart Codex or Claude Code after setup changes. Fully exit and relaunch Amp; for headless execute mode, use --plugin-ready-timeout 30 so the policy plugin is ready before the turn begins. An authenticated live Amp turn requires AMP_API_KEY, but that optional smoke is not the deterministic native Windows certification gate.

Startup behavior

With a configured connector, Setup owns one current-user HKCU Run value named DefenseClawGateway. It launches the product's no-console startup helper, which starts the adjacent gateway with the installed data root. This is not a Windows service or Scheduled Task.

The optional watchdog is a separate config-enabled background process. It is not the logon registration. A hook can also make one bounded cold-start attempt after an exact connection-refused result, using the protected installed gateway identity. These recovery paths never make a remote or proxy connector supported.

Repair

Use Settings > Apps > Installed apps > DefenseClaw > Modify, or call the trusted maintenance copy:

& "$env:LOCALAPPDATA\DefenseClaw\InstallerCache\DefenseClawSetup-x64.exe" /repair /quiet /norestart INSTALLSCOPE=user

"%LOCALAPPDATA%\DefenseClaw\InstallerCache\DefenseClawSetup-x64.exe" /repair /quiet /norestart INSTALLSCOPE=user

Repair republishes the packaged files and reconciles connector wiring while preserving user configuration, audit history, the connector roster and modes, recorded connector homes, and the prior gateway/watchdog running state.

Do not replace files in the install tree by hand. If a foreground DefenseClaw client has a runtime file locked, Setup leaves committed state unchanged and asks you to close the client and retry; it does not kill arbitrary foreground processes.

Upgrade and release eligibility

Releases 0.8.5 and 0.8.6 published no native Windows Setup. Release 0.8.7 was the first to publish one. Every published upgrade manifest from 0.8.5 through 0.8.10 declares an empty Windows tested-source list, so no currently published target authorizes an automatic cross-release native Windows upgrade. The documented current lifecycle is fresh install, repair, same-version servicing, and uninstall.

A future release can authorize an automatic native Windows upgrade only when its authenticated manifest lists the exact installed source as a tested Windows baseline. Only then would this command be eligible:

defenseclaw upgrade --yes

The command authenticates the signed checksum set, manifest, provenance, payload digest, and matching observed Authenticode state before stopping the gateway. Signed releases require the recorded publisher; an explicitly unsigned release must instead match authenticated unsigned provenance. It creates a private managed-state backup, starts the cached Setup, then exits so its embedded runtime can be replaced. The Setup payload itself is self-contained, but this CLI command needs network access to retrieve release metadata and the target EXE.

If the authenticated manifest does not authorize the installed source, the command must refuse before mutation. Do not copy release files over the installation, use the unsafe verification-bypass option, or treat a downgrade as rollback. Downgrade is rejected and there is no public manual rollback command. See the cross-platform upgrade contract.

Transaction recovery

Setup stages and validates a complete target before live replacement. It records a durable transaction, stops only the owned gateway/watchdog, publishes the new tree atomically, verifies the exact installed executable inventory, applies required migrations, and restores only the services that should run.

• A pre-commit failure restores the owned application, cache, connector, PATH, startup, and service state it changed.
• An ambiguous durable-write boundary is reported as recovery required; it is not reported as success.
• After configuration activation commits, recovery converges the matching target runtime rather than pairing new configuration with an old binary.
• Re-running the authenticated Setup resumes a valid interrupted journal.
• A foreign process, registry value, directory, reparse point, or changed installer state is refused rather than claimed as DefenseClaw-owned.

This is automatic transaction recovery, not permission to delete journals, restore arbitrary backup files, or force a downgrade manually.

Offline and packaged operation

After an authenticated DefenseClawSetup-x64.exe reaches the target host, its fresh install, repair, and eligible Setup-driven servicing do not download Python or product components. For a fully authenticated offline bootstrap, stage the complete release bundle—Setup, provenance, signed checksums and certificate/bundle, upgrade manifest, and the pinned Windows Cosign executable—then use the release's install.ps1 -Local flow. A partial local bundle fails closed.

Scanning, TUI, policy, local audit, and supported hook enforcement can run without an outbound observability destination. Connector agents may still need network access for their own normal operation. CodeGuard asset installation, remote registries, provider APIs, and remote observability destinations are optional network operations, not offline guarantees.

Uninstall and preserved state

Normal uninstall removes product-owned application files, the maintenance cache, Installed Apps registration, the owned user PATH entry, the owned Run value, and supported connector wiring. It preserves %USERPROFILE%\.defenseclaw by default, including configuration, local audit, and recovery evidence.

& "$env:LOCALAPPDATA\DefenseClaw\InstallerCache\DefenseClawSetup-x64.exe" /uninstall /quiet

"%LOCALAPPDATA%\DefenseClaw\InstallerCache\DefenseClawSetup-x64.exe" /uninstall /quiet

The uninstaller removes only state whose exact ownership it can prove. A foreign or operator-modified PATH entry, Run value, process, connector file, or install tree is preserved and reported for manual review.