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 | bash

To 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 --quickstart

The optional menu-bar app is a separate download, DefenseClawMac-<version>-macos-arm64.dmg, from the latest release. See macOS app.

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.

RequirementVersion
Python3.11-3.13
Go1.26.4 or newer
GitTo clone and identify the checkout
GNU Make and a POSIX shellThe documented workflow
uvUsed by make all (the pycli target)
Node.js and npmOnly when the build selects the OpenClaw plugin
DockerOptional, 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)

BackendStatus
OpenAI, Anthropic, generic OpenAI-compatibleBundled. LiteLLM is a base dependency.
AWS BedrockBundled. boto3 ships in the base dependencies, so SigV4, IAM credential modes and Anthropic-on-Bedrock bearer tokens work.
Google Vertex AIThe 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 OpenAIBundled, through LiteLLM's azure_openai adapter.
Self-hosted or internal endpointsBundled. 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
GoalCommand
Normal same-checkout developmentmake all
Build artifacts without installingmake build
Developer workflow helpmake 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 all uses the first of python3, python and py -3 that runs, which skips the Microsoft Store python3 alias. When none runs, the build stops with "no working Python 3 interpreter".
  • Files go to %USERPROFILE%\.defenseclaw and %USERPROFILE%\.local\bin, the same places as a release install. make all refuses 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 run

After 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, … skipped

Read 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.

  1. 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)
  2. Remove the connector hooks and stop the gateway. This keeps ~/.defenseclaw and the programs, so a later defenseclaw setup guardrail picks up where you left off.

    defenseclaw uninstall
  3. To remove everything, add --all (deletes ~/.defenseclaw: audit log, config, secrets) and --binaries (removes the CLI, gateway and helper programs).

    defenseclaw uninstall --all --binaries --yes

    If you already ran defenseclaw sandbox teardown, add --stop-sandboxes to this command. For copy-mode work, use defenseclaw sandbox pull NAME --apply (or --branch or --patch-out FILE) and confirm the project, branch or patch file contains it. Review mounted work with defenseclaw 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

Every flag is in the CLI reference.

Next