Install
Install the latest DefenseClaw release on macOS or Linux, use native Windows Setup, or build the current checkout from source.
Install the latest release on macOS or Linux
curl -LsSf https://github.com/cisco-ai-defense/defenseclaw/releases/latest/download/install.sh | bashThe release-owned installer resolves and authenticates the latest published
release automatically. When it finishes, run
defenseclaw init to configure DefenseClaw.
DefenseClaw ships pre-built release binaries for macOS and Linux, plus an
authenticated native x64 Windows Setup in the current 0.8.10 release. The macOS/Linux installer drops the
defenseclaw CLI and defenseclaw-gateway sidecar into ~/.local/bin/, creates
~/.defenseclaw/, and sets up a virtualenv under ~/.defenseclaw/.venv/.
Supported macOS architecture
DefenseClaw supports Apple Silicon (arm64) macOS only. Intel (x86_64 /
amd64) Macs are unsupported; the release installer, upgrade resolver, rescue
bootstrap, source installer, and managed package all stop before changing the
host. Rosetta does not make an Intel Mac a supported target.
Windows release history
Releases 0.8.5 and 0.8.6 published no native Windows Setup artifact.
Release 0.8.7 was the first release to publish
DefenseClawSetup-x64.exe. Do not copy POSIX artifacts onto Windows, and do
not treat a release without a Windows Setup artifact as a Windows baseline.
Current native Windows Setup (introduced in 0.8.7)
DefenseClawSetup-x64.exe provides a graphical wizard and a quiet,
wizard-suppressed mode for the CLI/TUI, native gateway, no-console hook
launcher, and an embedded managed Python runtime. Application files live under
%LOCALAPPDATA%\Programs\DefenseClaw; user state remains under
%USERPROFILE%\.defenseclaw.
The 0.8.10 Setup is authenticated by the release's Sigstore-signed checksum
set and provenance, but the executable itself is explicitly
not Authenticode-signed. Verify the published checksum/provenance; do not
expect a Windows Digital Signatures publisher entry.
POSIX install scripts are for fresh hosts only
The macOS/Linux release scripts stop without changing the host when they detect an existing DefenseClaw CLI, gateway, or managed virtual environment. Use the release-owned upgrade path for an existing POSIX installation; it enforces the signed manifest, any required bridge release, rollback preparation, migrations, and post-upgrade health checks. Native Windows Setup separately supports repair and same-version servicing.
Installing as root is supported but discouraged — DefenseClaw is per-user by design so each operator's audit DB and connector state stays isolated.
Prerequisites
| Requirement | Version |
|---|---|
| Python | 3.10-3.13 for source builds |
| Go | 1.26.4+ (only for source builds) |
| Git | Required to clone and identify a source checkout |
| GNU Make and a POSIX shell | Required by the documented source workflow |
uv | Required by make all / the pycli target |
| Node.js and npm | Required only when a source build selects the OpenClaw plugin; use the runtime version required by that OpenClaw release |
| Docker | Optional, for local observability and Splunk bundles |
Cosign is not a macOS/Linux prerequisite for the 0.8.4+ release installer.
If no compatible cosign exists on PATH, the installer downloads pinned
Cosign 2.6.3 into its owner-only staging directory, validates a hard-coded
platform SHA-256 before executing it, verifies the DefenseClaw release, and
retires the temporary verifier. Nothing is installed globally.
The current native Windows Setup bundles its managed runtime. A packaged Windows
install does not require Python, uv, Go, Node.js, Git, or a PowerShell
installation command after the authenticated Setup artifact is downloaded. This does
not remove an upstream agent prerequisite such as Claude Code's Git for Windows
requirement.
What's bundled (LLM backends)
The base install ships everything DefenseClaw needs to talk to the major LLM backends out of the box:
| Backend | Status | Notes |
|---|---|---|
| OpenAI / Anthropic / generic OpenAI-compatible | bundled | LiteLLM, the default LLM transport, is a base dependency. |
| AWS Bedrock | bundled | boto3 ships in [project].dependencies so SigV4, IAM credential modes, and Anthropic-on-Bedrock bearer tokens work without a follow-up pip install. |
| Google Vertex AI | Gateway bundled; Python SDK opt-in | The Go gateway routes Vertex through its bundled Bifrost backend. Python CLI scanner/judge paths use LiteLLM and require the [vertex] extra for the Google SDK and supported Vertex authentication; the SDK pulls ~286 MB of transitive dependencies. Source contributors can add it to their isolated checkout with uv sync --extra vertex; never modify a release-managed runtime. There is no documented SDK-less Python fallback. |
| Azure OpenAI | bundled | Routed via LiteLLM's azure_openai adapter. |
| Self-hosted / internal endpoints | bundled | Configure via defenseclaw setup provider add → see Unified LLM key → Custom providers. |
Windows or source install
0.8.10 release artifact
Download DefenseClawSetup-x64.exe from the 0.8.10 GitHub release. Release
0.8.5 had no Windows Setup artifact and remains outside the Windows
upgrade-baseline matrix; source builds are developer tooling, not a substitute
for a release upgrade or rollback contract.
.\DefenseClawSetup-x64.exeStarting with release 0.8.7, double-click the authenticated artifact for the
graphical setup wizard. It installs the CLI/TUI, gateway,
hook launcher, and managed runtime for the current Windows user. The finish
screen will point to defenseclaw init and defenseclaw tui; Setup does not
install a separate native DefenseClaw GUI application.
For a quiet install in the signed-in, non-elevated user's interactive desktop session, pass properties directly:
.\DefenseClawSetup-x64.exe /quiet /norestart INSTALLSCOPE=user CONNECTOR=codex MODE=observe STARTGATEWAY=1Use CONNECTOR=claudecode for Claude Code or CONNECTOR=none to configure
later. The setup executable contains the offline payload required for install;
after download it does not require Python, uv, Go, Node.js, Git, or a
PowerShell installation command.
Quiet mode does not authorize service, SYSTEM, session-zero, elevated, or
background/batch installation. A configured Codex or Claude Code connector
requires gateway startup; only CONNECTOR=none STARTGATEWAY=0 is a supported
stopped CLI-only install.
Native Windows uses agent hooks rather than the OpenClaw/ZeptoClaw proxy path. See Native Windows for the connector matrix, repair, servicing, uninstall, file locations, and troubleshooting.
Release version versus source metadata
The published artifacts on this page are release 0.8.10. The checked-in
source metadata on this commit remains 0.8.6; the protected release workflow
stamps an isolated build checkout with the release version before producing
artifacts. A source build therefore reports the checked-in source version and
must not be represented as the published 0.8.10 artifact.
| Goal | Command |
|---|---|
| Normal same-checkout development | make all |
| Build artifacts without installing | make build |
| Show developer workflow help | make help |
| Upgrade a packaged release | defenseclaw upgrade |
git clone https://github.com/cisco-ai-defense/defenseclaw.git
cd defenseclaw
make all CONNECTOR=none
defenseclaw initmake all installs the editable Python CLI, builds and installs the Go gateway,
updates your PATH, and normally runs quickstart. The example sets
CONNECTOR=none to skip that automatic first-run configuration, then invokes
defenseclaw init explicitly. Omit CONNECTOR=none when you want make all
to run quickstart itself. The OpenClaw plugin is installed when
CONNECTOR=openclaw is selected.
Source builds are development tooling, not a packaged upgrade path. make all
is the explicit developer reinstall workflow: it may reclaim markerless or
older source state only when the installed CLI belongs to this exact checkout.
It validates marker ownership, rejects foreign and newer source identities,
and records the current strict marker after a successful rebuild. Direct
make install, scripts/install-dev.sh, and release-managed hosts remain
fail-closed. Release installations must use defenseclaw upgrade; do not aim a
raw pip, uv, or editable install at a release-managed virtual environment.
The lower-level install targets are for fresh or isolated development homes,
not the normal repeated-development path.
Local dist output is not release input
make dist creates unauthenticated local developer artifacts. Do not pass
those files to the release installer or present them as published binaries.
The authenticated installer path requires the published checksum set verified
against its Sigstore certificate and protected release-workflow identity; a
local hash, generic certificate, or locally generated archive is not equivalent
release provenance.
What the install creates
Release 0.8.5 has no release-managed Windows tree. Developer/source installs
use %USERPROFILE%\.defenseclaw\ for config, audit state, hooks, and the
virtualenv, and %USERPROFILE%\.local\bin\ for defenseclaw.cmd and
defenseclaw-gateway.exe.
With native Setup (introduced in 0.8.7), application files live
under %LOCALAPPDATA%\Programs\DefenseClaw: bin\defenseclaw.exe launches the
embedded Python CLI/TUI, bin\defenseclaw-gateway.exe is the native gateway,
bin\defenseclaw-hook.exe is the no-console hook launcher, and
runtime\python\ contains the managed Python runtime. User configuration,
audit state, hooks, and backups remain under %USERPROFILE%\.defenseclaw\.
Verify
defenseclaw --version
defenseclaw doctorDoctor verifies:
| Check | What it verifies |
|---|---|
| Configuration | The canonical config exists, loads, and validates. |
| Audit and identity state | File custody, SQLite integrity and required schema, storage capacity, device-key custody, and HMAC-bound provenance. |
| Components and connectors | CLI/gateway/plugin alignment and active connector versions against registered compatibility contracts. |
| Gateway | Managed process and listener identity, public health, and authenticated /status using the locally resolved token. |
| Guardrail, scanners, and credentials | Enabled service reachability, required scanner binaries, and configured credential availability without printing secret values. |
| Observability | Effective destination routes, queue/delivery health, and each destination/signal circuit while mandatory local SQLite remains available. |
Useful modes:
# Avoid billable, content-submitting, and synthetic probes
defenseclaw doctor --passive
# Machine-readable schema v2
defenseclaw doctor --json-output
# Preview eligible repairs without mutation
defenseclaw doctor --fix --dry-run
# Apply eligible safe and disruptive repairs
defenseclaw doctor --fix --yes
# Select one repair and its declared dependencies
defenseclaw doctor --fix --fix-id doctor.state.audit-db.initialize
# Identity recovery is always attended; do not add --yes
defenseclaw doctor --fix --fix-id doctor.identity.device-key.initialize--fix applies selected repairs before the health pass, so its summary
describes post-repair state. A failed health check or failed or blocked repair
exits 1. See the Doctor CLI reference for the
machine contract and Reporting and diagnosis
for token, recovery, compatibility, and approval boundaries.
Uninstall
defenseclaw uninstall # reversible — keeps ~/.defenseclaw/ and binaries
defenseclaw uninstall --all # also delete ~/.defenseclaw/ (audit log, config, secrets)
defenseclaw uninstall --binaries # also remove ~/.local/bin/defenseclaw{,-gateway}
defenseclaw uninstall --all --binaries --yes # full nuke, no confirm promptThe default tears down connector integrations and leaves
~/.defenseclaw/ and the installed binaries on disk so a subsequent
defenseclaw setup guardrail can pick up where you left off. An unchanged
managed connector file is restored byte-for-byte from its hash-checked
snapshot; after user edits, connector-specific cleanup removes only
DefenseClaw-owned entries and preserves unrelated changes. Use --all and/or
--binaries to make the removal total. --dry-run previews the plan.
With the current native package, use the setup executable for product uninstall:
.\DefenseClawSetup-x64.exe /uninstall /quiet
.\DefenseClawSetup-x64.exe /uninstall /quiet DELETEUSERDATA=1The first command preserves %USERPROFILE%\.defenseclaw; the second requests
user-data removal after connector cleanup succeeds. If teardown or recovery is
unresolved, Setup retains the data root and retry evidence. See
Install and maintain.
Next
Native Windows
Authenticated Setup wizard, silent install, native hook connectors, verification, and troubleshooting.
Quickstart
Zero-prompt setup that gets you a guardrail in two minutes.
Upgrade safely
Verified artifacts, automatic migrations, backups, health checks, and observability schema compatibility.
Setup Guardrail
The full configuration surface for the central command.