Install
Install DefenseClaw on macOS, Linux, or Windows with one command, or build the current checkout from source.
Install
Before a first install or upgrade, quit OpenCode and Amp completely. Their DefenseClaw plugins load only at process start, so an already running agent would not gain the new protection. The installer refuses to continue while either agent is running for your account. Start a new agent process after the installer reports the gateway healthy.
Pick your system. The site detects it and remembers your choice.
Requires a Mac with Apple silicon (arm64). Intel Macs are unsupported, and the installer stops before it changes anything.
curl -LsSf https://github.com/ cisco-ai-defense/ defenseclaw/ releases/ latest/ download/ install.sh | bashTo install, guard one agent and run first-time setup in one step:
curl -LsSf https://github.com/ cisco-ai-defense/ defenseclaw/ releases/ latest/ download/ install.sh | bash -s -- --connector claudecode --quickstartThe optional menu-bar app is a separate download, DefenseClawMac-<version>-macos-arm64.dmg, from the latest release. See macOS app.
Requires Linux on x86_64 or arm64.
curl -LsSf https://github.com/ cisco-ai-defense/ defenseclaw/ releases/ latest/ download/ install.sh | bashTo install, guard one agent and run first-time setup in one step:
curl -LsSf https://github.com/ cisco-ai-defense/ defenseclaw/ releases/ latest/ download/ install.sh | bash -s -- --connector claudecode --quickstartIf the installer says ~/.local/bin is not on your PATH, run the line it prints, then open a new shell.
Requires Windows on x64 with Windows PowerShell 5.1 or PowerShell 7. Windows on ARM64 is not certified, so the installer stops there. Run it as the user who uses DefenseClaw, not as an administrator.
irm https://github.com/ cisco-ai-defense/ defenseclaw/ releases/ latest/ download/ install.ps1 | iexTo install, guard one agent and run first-time setup in one step:
& ([scriptblock]::Create((irm https://github.com/ cisco-ai-defense/ defenseclaw/ releases/ latest/ download/ install.ps1))) -Connector claudecode -QuickstartOpen a new terminal if the installer says so. See Windows.
On a first install the installer asks which agent to guard (a number or a name). If you ran the plain command, run the command it prints next, defenseclaw init --connector <agent>. Plain defenseclaw init sets up every agent it finds. Rerunning the installer upgrades or repairs an install and keeps your configuration.
On a computer your organization manages, the per-user installer and defenseclaw upgrade refuse to run. The organization installs DefenseClaw through its MDM. See Enterprise.
Prerequisites for source builds
Source builds are for developing DefenseClaw, not for upgrading a release install. To upgrade a release install, use defenseclaw upgrade, and never point pip, uv or an editable install at its Python environment.
| Requirement | Version |
|---|---|
| Python | 3.11-3.13 |
| Go | 1.26.4 or newer |
| Git | To clone and identify the checkout |
| GNU Make and a POSIX shell | The documented workflow |
uv | Used by make all (the pycli target) |
| Node.js and npm | Only when the build selects the OpenClaw plugin |
| Docker | Optional, for local observability and Splunk bundles |
The shell inspect hooks need jq or python3. If neither is installed, they block every checked call. Agent-specific dependencies are on the connector pages.
What's bundled (LLM backends)
| Backend | Status |
|---|---|
| OpenAI, Anthropic, generic OpenAI-compatible | Bundled. LiteLLM is a base dependency. |
| AWS Bedrock | Bundled. boto3 ships in the base dependencies, so SigV4, IAM credential modes and Anthropic-on-Bedrock bearer tokens work. |
| Google Vertex AI | The gateway routes Vertex through its bundled Bifrost backend. The Python CLI scanner and judge paths need the [vertex] extra (about 286 MB of dependencies); in a source checkout, uv sync --extra vertex. Never modify a release-managed runtime. |
| Azure OpenAI | Bundled, through LiteLLM's azure_openai adapter. |
| Self-hosted or internal endpoints | Bundled. Add with defenseclaw setup provider add (LLM providers). |
Install from source
git clone https://github.com/cisco-ai-defense/defenseclaw.git
cd defenseclaw
make all CONNECTOR=none
defenseclaw init| Goal | Command |
|---|---|
| Normal same-checkout development | make all |
| Build artifacts without installing | make build |
| Developer workflow help | make help |
Release-shaped files for testing the installer with --local dist (unsigned) | make dist |
make all installs the editable Python CLI, builds and installs the Go gateway, updates your PATH and normally runs quickstart. CONNECTOR=none skips that first-run setup. The OpenClaw plugin is installed when CONNECTOR=openclaw.
A source build reports the checked-in source version; do not present it as a published artifact. Running make all again in the same checkout reinstalls over your earlier build. It refuses to replace an install from a different checkout, a newer source build or a release install. make install and scripts/install-dev.sh install only into a fresh or separate development home.
Build from source on Windows
Run the same workflow in Git Bash (Git for Windows) with GNU Make, Go, uv and Python 3.11-3.13 from python.org.
- Clone with
git -c core.autocrlf=false clone ...so shell scripts keep LF line endings. make alluses the first ofpython3,pythonandpy -3that runs, which skips the Microsoft Storepython3alias. When none runs, the build stops with "no working Python 3 interpreter".- Files go to
%USERPROFILE%\.defenseclawand%USERPROFILE%\.local\bin, the same places as a release install.make allrefuses an account that already has a release install and prints how to remove its binaries first (defenseclaw.cmd uninstall --binaries --yes, which keeps your config and audit log). You can also build in a separate Windows account.
Check it worked
defenseclaw version DefenseClaw versions
COMPONENT VERSION STATUS ORIGIN
--------- ------- ------- ----------------------------------------
cli X.Y.Z ok defenseclaw (python)
gateway X.Y.Z ok ~/.local/bin/defenseclaw-gateway
…
OK All components in sync.In a terminal the rows use check marks (✓ All components in sync., and doctor rows start with ✓, ⚠, ✗ or -); piped to another command, as above, they use text (OK All components in sync., [PASS], [WARN], [FAIL], [SKIP]).
If you ran the plain install command, run defenseclaw init --connector <agent> before defenseclaw doctor. Before init, doctor shows one row and exits 1:
[FAIL] Config file — ~/.defenseclaw/config.yaml not found; DefenseClaw is not initialized, so no other check can runAfter init, run defenseclaw doctor. Each row is [PASS], [WARN], [FAIL] or [SKIP]; the sidecar and hook rows are [FAIL] until you set up an agent and start the gateway. A trimmed example (your rows and counts differ):
DefenseClaw Doctor
==================
[PASS] Audit database - ~/.defenseclaw/audit.db; SQLite quick_check=ok; required schema present
[PASS] Device identity - Ed25519 key custody and HMAC-bound provenance are valid
[PASS] Private files - only this account can read .env, device.key, audit.db and the data directory
…
-- Summary --
Health: … passed, … failed, … warnings, … skippedRead doctor explains the rows. If a command is not found, see Troubleshooting.
Uninstall
defenseclaw uninstall removes DefenseClaw for your account. It works the same on macOS, Linux and Windows.
Close your agent sessions first. A session that stays open goes on without DefenseClaw: its hooks fail and nothing checks its tool calls. The plan says so before it asks to proceed.
If you set up an editor with defenseclaw acp setup or defenseclaw setup acp, uninstall also removes the guarded ACP entries it wrote in the editor's settings, with their contract locks in ~/.defenseclaw/acp. Every other entry in that file stays. The plan lists them under ACP editor entries. Releases before 1.0.6 left these entries behind: an agent set up in observe mode still started but ran unchecked, an agent set up with --activate refused every message, and after --binaries or --all the editor could not start that agent. defenseclaw acp detect lists the guarded entries, and defenseclaw acp remove --client <client> --agent <agent> removes one without uninstalling. On a managed computer the enrollment owns the entry; see ACP guard.
-
See what would be removed. Nothing changes.
defenseclaw uninstall --dry-run------------------------ Plan ------------------------ * active connector: claudecode * connector teardown: claudecode - an agent session that is open now goes on without DefenseClaw (its hooks fail and nothing checks its tool calls): close it first, or restart it once DefenseClaw is back * sandbox teardown: no (no OpenShell sandbox state) * stop sidecar: yes * wipe ~/.defenseclaw: no * remove binaries: no (dry-run - nothing modified) -
Remove the connector hooks and stop the gateway. This keeps
~/.defenseclawand the programs, so a laterdefenseclaw setup guardrailpicks up where you left off.defenseclaw uninstall -
To remove everything, add
--all(deletes~/.defenseclaw: audit log, config, secrets) and--binaries(removes the CLI, gateway and helper programs).defenseclaw uninstall --all --binaries --yesIf you already ran
defenseclaw sandbox teardown, add--stop-sandboxesto this command. For copy-mode work, usedefenseclaw sandbox pull NAME --apply(or--branchor--patch-out FILE) and confirm the project, branch or patch file contains it. Review mounted work withdefenseclaw sandbox review NAME. Then use--stop-sandboxes, which stops and deletes running sandboxes.
An agent config file you have not changed since setup is restored from its checked backup. If you edited it, only DefenseClaw's entries are removed.
If you set up Claude Cowork with defenseclaw setup cowork, uninstall cannot remove the plugin from your Claude account, and defenseclaw reset cannot either. In Claude Desktop, open Customize > Plugins, then the ... menu on DefenseClaw, and choose Remove. Until you remove the plugin, Cowork tool calls are blocked. --dry-run lists this step. See Remove the Cowork plugin.
--all deletes the audit log. Export what you need first with defenseclaw-gateway audit export.
Sandboxes
If you set up sandboxes, uninstall also removes DefenseClaw's OpenShell sandboxes and images. A running sandbox stops the uninstall before any change. For copy mode, use defenseclaw sandbox pull NAME --apply (or --branch or --patch-out FILE) and confirm the project, branch or patch file contains the work. For mount mode, use defenseclaw sandbox review NAME. Then stop the sandbox and retry. --stop-sandboxes stops and deletes running sandboxes; copy-mode work not yet pulled back is lost. If teardown fails, rerun without --all and --binaries and add --skip-sandbox-teardown, then run defenseclaw-gateway sandbox teardown once Docker and OpenShell work.
Windows
On Windows the programs are in %USERPROFILE%\.local\bin and the data in %USERPROFILE%\.defenseclaw. The commands are the same, and --binaries removes the programs. There are no sandboxes to tear down.
Other ways to remove
- A source build:
defenseclaw.cmd uninstall --binaries --yeson Windows before building again; see Install from source. - Turn the guardrail off without removing anything: Turn off the guardrail.
- Managed computers: removal is an administrator task (Enterprise lifecycle).
Every flag is in the CLI reference.