Setup commands

DefenseClaw setup and configuration surfaces in one place — from the central guardrail wizard to keys, webhooks, registries, observability, OpenShell sandboxes, and per-connector hooks, plus the options, exit codes and startup behavior of install.sh and install.ps1.

Hook setup aliases (setup codex, setup claude-code and the rest) add or reconfigure one connector. With another hook connector already active, choose Add to join the roster or Replace to return to one connector. Proxy connectors (openclaw, zeptoclaw) own the traffic plane and do not join the hook-connector roster.

The central command

CommandUse it for
defenseclaw setup guardrailThe central setup command. See setup guardrail.

Connector setup aliases

CommandUse it for
defenseclaw setup claude-codeHook setup alias for Claude Code. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side.
defenseclaw setup codexHook setup alias for Codex. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side.
defenseclaw setup cursorUser-hook alias for Cursor. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). --mode action uses event-native deny. Both modes set failClosed: true for hook-process failure outside Secure Client. Native human approval is not enabled.
defenseclaw setup devinNative Devin CLI hook alias. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). --mode action can block only on the four documented block-capable events.
defenseclaw setup copilotHook setup alias for GitHub Copilot CLI. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side. If an earlier managed install left defenseclaw@defenseclaw enabled in Copilot's machine managed-settings file, setup copilot and setup remove copilot print a warning that names the file and asks an administrator to delete the entry; a standard user cannot remove it.
defenseclaw setup hermesHook setup alias for Hermes. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side.
defenseclaw setup antigravityHook setup alias for Antigravity (agy). Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side. Native ask and deny are documented only for PreToolUse; no permission-bypass override is claimed.
defenseclaw setup opencodeHook setup alias for OpenCode; writes the auto-loaded bridge plugin. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side.
defenseclaw setup acpFind ACP agents an editor is launching unguarded and route them through defenseclaw-acp. Reuses the per-pair acp setup transaction and points the operator's existing entry at the guard, so no unmediated duplicate is left behind. Defaults to observe; --activate selects action. Alias of defenseclaw acp adopt.
defenseclaw setup kiroNative hook alias for Kiro IDE and Kiro CLI. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action to block hook-side. The .kiro/hooks surface (Kiro IDE and kiro-cli --v3) vetoes PreToolUse, and UserPromptSubmit in Kiro IDE (kiro-cli 2.24.1 --v3 still sends a blocked prompt to the model); the CLI 2.x agent config vetoes PreToolUse only. ACP is optional and configured separately with defenseclaw acp setup --agent kiro.
defenseclaw setup ampDirect-to-upstream system-policy setup for Amp; writes the TypeScript plugin. Defaults to observe on first setup; a re-run without --mode keeps the current mode (on a terminal it asks first; --yes skips the questions). Pass --mode action for synchronous tool.call execution gating and model-bound tool.result output gating. Native confirmation is available only in the active foreground thread; background confirmation falls back to safe rejection or withholding.
defenseclaw setup cowork [--yes|--non-interactive] [--open-claude|--no-open-claude] [--wait|--no-wait] [--timeout SECONDS]Per-user Claude Cowork route. Builds the DefenseClaw plugin zip for your Claude account, shows the upload steps and waits for the first Cowork event. Sets up the Claude Code connector first if it is off. Cowork is not a connector. Exits 3 on a managed computer. See Claude Cowork.

Proxy connectors

CommandUse it for
defenseclaw setup openclawFull guardrail alias for OpenClaw (proxy connector); unsupported in the native Windows release.
defenseclaw setup zeptoclawFull guardrail alias for ZeptoClaw (proxy connector); unsupported in the native Windows release.

Auxiliary configuration commands

CommandUse it for
defenseclaw setup remove CONNECTOR [--force] [--yes]Remove one connector from the active roster; the gateway restart tears down its hooks. If the connector is already absent, the command removes DefenseClaw hook entries it left in the agent settings. Removing the last configured connector needs --force. To take DefenseClaw off the machine, use defenseclaw uninstall. setup remove claudecode does not remove the Cowork plugin from your Claude account; see Remove the Cowork plugin. With --no-restart, a running gateway removes the connector's hooks when it reloads the config (within seconds) and a stopped one removes them when it next starts; if the removed connector was the primary one, its hooks stay until the gateway restarts.
defenseclaw setup gateway [--api-port N] [--host H] [--port N] [--remote] [--non-interactive]Set the sidecar REST API port (--api-port) and the upstream agent gateway connection: host, WebSocket port, and auth token (--remote; the token can come from AWS SSM Parameter Store). Runs connectivity checks afterward unless --no-verify. Port values take 1-65535; anything else is refused when the command parses.
defenseclaw setup rotate-token [--yes]Rotate the gateway token and every connector-scoped hook credential in one transaction, then refresh the hooks and verify the restarted gateway. A failure after the gateway stops restores the previous credentials. Rotation is always global; --connector does not narrow it.
defenseclaw setup skill-scanner / setup mcp-scannerConfigure the skill and MCP scanners: analyzers, the LLM judge, optional VirusTotal, AI Defense and OSV lookups, and the scan policy. They write scanners.skill_scanner.* or scanners.mcp_scanner.* (and the shared llm: block) in config.yaml, then restart a running gateway, as most setup subcommands do. --non-interactive takes every choice from flags; the flags are below. See Scanners.
defenseclaw setup registryInteractive wizard that registers a skill or MCP catalog; the same as defenseclaw registry wizard. See Registries.
defenseclaw setup migrate-llm [--dry-run] [--no-backup]Rewrite a config.yaml that still carries pre-v5 inspect_llm, default_llm_* or guardrail LLM fields into the unified llm: block, writing config.yaml.bak first unless --no-backup. On a current config it prints Config already in v5 shape — nothing to migrate.
defenseclaw setup routing --enable|--disable|--statusConfigure or inspect semantic model routing for proxy-mode OpenAI Chat Completions traffic. Managed mode requires Docker; all config changes activate on gateway restart. See Semantic routing.
defenseclaw setup llm [--show] [--non-interactive] [--provider P] [--model M] [--api-key-env NAME]Write the unified or role-scoped LLM block (--role unified|agent|judge) in config.yaml; the key itself goes to ~/.defenseclaw/.env. --show prints the resolved values and changes nothing. Supports SaaS providers and regional Bedrock / Vertex AI / Azure OpenAI via dedicated --bedrock-*, --vertex-*, --azure-* flags, plus --instance-name to bind a custom provider from llm_providers (use --provider custom) and --inherit-from to seed from a sibling component. --ping / --no-ping sends (or skips) a one-shot reachability probe after saving. See LLM providers.
defenseclaw setup decision-model [--show] [--enable|--disable] [--base-url URL] [--model M] [--connectors LIST] [--api-key-env NAME] [--ping] [--non-interactive]Write the decision_model: block: the optional fast model for tool calls, in front of the LLM judge or, for the --connectors list (names or *; "" clears it), on its own where the judge does not run. Also used for the advisory skill-scan score. Naming --base-url or --model turns it on. --show prints the cascade of each active connector. --timeout, --allow-threshold, --block-threshold and --on-confident-block escalate|decide tune it. The token goes in ~/.defenseclaw/.env with defenseclaw keys set DEFENSECLAW_DECISION_MODEL_KEY. The running gateway applies it without a restart. See Decision model.
defenseclaw setup provider add|list|show|removeManage llm_providers.custom entries that route LLM traffic through internal or self-hosted endpoints. custom-providers.json is derived from them; never edit it. add writes the entry and asks a running gateway to reload its provider registry (--no-reload skips); omit --name for the wizard. list prints the live registry. add flags are below.
defenseclaw setup local-observability up|down|status|logs|url|env|resetBring up the bundled Prom/Loki/Tempo/Grafana stack, tear it down, show its readiness, tail its logs (--service, --follow), print the Grafana and backend URLs or the environment that points a gateway at it, or reset it (stop it and delete its stored metrics, logs, and traces). up --password requires the managed Grafana credential; up --no-password explicitly selects anonymous read-only (Viewer) access on managed loopback; anonymous access is never Admin. New stacks default to password and previously used anonymous stacks keep anonymous access, read-only. down keeps the data volumes; down --disable-config also turns off the local-observability destination.
defenseclaw setup galileo [status|test|enable|disable|remove]Configure and verify Galileo Cloud or self-hosted OTLP traces.
defenseclaw setup splunkConfigure local Splunk in Docker, Splunk Enterprise HEC, or Splunk Observability Cloud.
defenseclaw setup webhook add|list|show|enable|disable|remove|testConfigure Slack, PagerDuty, Webex, or generic notifier webhooks (chat and incident routing). add <type> creates or updates one (--non-interactive with --url, --secret-env, --min-severity, --events; --dry-run previews); test NAME sends a synthetic event. Secrets are referenced by environment name and never printed.
defenseclaw setup splunk dashboards plan|apply|destroyCreate, update, or remove the DefenseClaw dashboards (and, with --with-detectors, detectors) in Splunk Observability Cloud through Terraform. plan shows the changes first.
defenseclaw setup notifications [on|off|status]Turn desktop notifications for blocks and pending approvals on or off. Bare, it asks once. setup notifications-set <category> <value> toggles one category or source. Notifications are informational; they never approve or deny anything.
defenseclaw setup observability add|list|enable|disable|remove|testManage config-v8 destinations across OTLP, Galileo, Splunk HEC, JSONL, HTTP JSONL, console, and Prometheus capabilities. Omitted destination policy means all supported signals/buckets, unredacted. Distinct from setup webhook, which manages notifier webhooks.
defenseclaw setup redaction [status|remove-all|apply|defaults|bucket|profile|destination|route]Configure v8 redaction interactively or with scriptable subcommands. Bare invocation offers a simple baseline choice followed by Show advanced settings? for all buckets, profiles, destination policy, and ordered routes. Mutations preview the canonical effective diff; changed non-dry-run writes create a timestamped backup and verify the installed plan. In the TUI: TUI → 0 Setup → Guardrail & scanning → Redaction. In the macOS app: Logs → Redaction policy….
defenseclaw observability planPrint the masked effective v8 graph: generated local SQLite policy, collection, destination capabilities, routes, profiles, retention, and warnings.
defenseclaw observability destination test NAME [--write-probe] [--timeout S]Test one destination's DNS, connection, TLS, and protocol without ordinary collection or fan-out. --write-probe also sends one marked, content-free probe where the destination supports it. A local or pull destination (jsonl, sqlite, console, prometheus) has nothing to reach: the test says SKIPPED and exits 0, as does defenseclaw setup observability test NAME.

For observability destinations, name is the stable identity: a new name adds, and an existing name updates only that destination. Run list --json for the complete target/kind/signal inventory and add ... --dry-run for a safe preview. The TUI mirrors the runtime-loaded inventory in Overview → Observability Destinations and exposes the wizard at 0 Setup → Observability / Galileo.

Remove every configurable redaction override:

defenseclaw setup redaction remove-all --dry-run
defenseclaw setup redaction remove-all --yes

Profile none permits governed content without redaction

remove-all selects profile none for configurable log and trace projections. It can expose governed content to configured destinations; confirm each has an approved trust boundary before using --yes. It never weakens the release-owned managed enterprise destination. See Redaction.

CommandUse it for
defenseclaw setup trusted-paths list|add|removeManage the directories trusted for connector-binary version probing (action-mode setups refuse binaries outside this allow-list). list shows built-in defaults (the folders setup admits, with discovery default marking any that only passive discovery uses) plus operator additions, with source and status; add validates the directory (world-writable / relative paths refused unless --force) and writes it to ai_discovery.trusted_binary_prefixes in ~/.defenseclaw/config.yaml; remove only touches operator-added entries (in config.yaml, or an older entry in ~/.defenseclaw/.env). All verbs accept --json.

Safety gates are intentional

Commands that fetch remote content fail closed when the trust boundary is unclear. Connector version probes enforce trusted path prefixes when ai_discovery.require_trusted_binary_paths: true; that gate defaults to false for on-demand discovery. Registry and scanner fetches reject loopback, link-local, cloud-metadata, and private-network targets unless explicitly allowed; defenseclaw upgrade verifies release artifacts before stopping the running gateway.

setup provider add flags

add accepts --name, --base-url and --domain (repeatable; optional with --base-url, but without a domain that covers the base_url host the gateway cannot match inbound URLs back to the entry, and defenseclaw doctor warns), --base-provider-type, --env-key, --allowed-request, --available-model, --request-path-override, --profile-id, --ollama-port, the TLS options --ca-cert-file and --insecure-skip-verify, and --no-reload (save without asking the running gateway to reload its registry). remove --name NAME takes --no-reload too. Provider-specific flags are rejected when they don't match --base-provider-type:

ProviderFlags
Bedrock--bedrock-region, --bedrock-auth-mode, --bedrock-access-key-env, --bedrock-secret-key-env, --bedrock-session-token-env, --bedrock-profile-name, --bedrock-inference-profile, --bedrock-deployment alias=model-id (repeatable)
Vertex AI--vertex-project-id, --vertex-region, --vertex-auth-mode, --vertex-service-account-json-env
Azure OpenAI--azure-endpoint, --azure-api-version, --azure-auth-mode, --azure-deployment-alias model=deployment (repeatable)
defenseclaw setup provider add --name acme-llm --base-url https://llm.acme.example.com:8443 \
  --domain llm.acme.example.com --env-key ACME_LLM_KEY --base-provider-type openai
  ✓ provider 'acme-llm' written to config.yaml llm_providers (derived /home/alice/.defenseclaw/custom-providers.json)
  domains: llm.acme.example.com
  env_keys: ACME_LLM_KEY
  base_provider_type: openai
  base_url: https://llm.acme.example.com:8443
  ✓ sidecar reloaded provider registry; disk and live state match.

setup skill-scanner and setup mcp-scanner flags

Both commands prompt for each choice unless you pass --non-interactive. Every on/off option is a --x / --no-x pair; --verify / --no-verify runs (or skips) connectivity checks after saving and defaults to on.

CommandFlagsWrites
setup skill-scanner--use-llm, --use-behavioral, --enable-meta, --use-trigger, --use-virustotal, --use-aidefense, --use-osv (each with a --no- form)scanners.skill_scanner.use_* and enable_meta; VirusTotal, AI Defense and OSV also need their keys (defenseclaw keys set)
--llm-provider P, --llm-model M, --llm-base-url URL, --llm-consensus-runs NThe judge in the shared top-level llm: block, and scanners.skill_scanner.llm_consensus_runs. --llm-base-url applies to openai-compatible and vllm judges
--policy strict|balanced|permissive|low-noise|quietscanners.skill_scanner.policy. quiet is the recommended preset
--fail-on-severity and --review-queue-min, each info|low|medium|high|criticalThe scanner gate: findings at or above the first block, findings from the second up to the gate go to review. Recommended: HIGH and MEDIUM
--lenient / --no-lenientTolerate malformed skills, or fail them
setup mcp-scanner--analyzers yara,api,llm,behavioral,readinessscanners.mcp_scanner.analyzers. auto stores an empty list, and the scanner then picks YARA plus a ready LLM
--llm-provider P, --llm-model MThe judge in the shared llm: block
--api-endpoint URL, --api-key-env NAME, --api-timeout-ms Ncisco_ai_defense.endpoint, .api_key_env and .timeout_ms for the api analyzer
--scan-prompts, --scan-resources, --scan-instructions (each with a --no- form)What else the scan covers: MCP prompts, resources and server instructions
defenseclaw setup skill-scanner --non-interactive --policy quiet \
  --fail-on-severity high --review-queue-min medium --no-verify
defenseclaw setup mcp-scanner --non-interactive --analyzers yara --scan-prompts --no-verify
  Saved to ~/.defenseclaw/config.yaml

    scanners.skill_scanner.policy:           quiet
    scanners.skill_scanner.fail_on_severity: HIGH
    scanners.skill_scanner.review_queue_min: MEDIUM
    scanners.skill_scanner.lenient:          true

--llm-provider accepts any provider setup llm does, plus openai-compatible. For what the analyzers, policies and the gate mean, see Skill scanner and MCP scanner.

OpenShell sandbox

Linux, and Apple-silicon Macs, where sandboxes are OpenShell MicroVMs that work on a copy (see macOS); Windows and WSL2 are not supported, and every sandbox command exits 3 there. The sandbox commands run coding agents in NVIDIA OpenShell 0.1 sandboxes. defenseclaw sandbox checks the command line, then hands it unchanged to defenseclaw-gateway sandbox. Every command and flag, with an example, is on Sandbox CLI; see also Sandbox.

Change one setting without a wizard

These commands edit one thing in config.yaml, check the result before they write, and print the new config generation. The gateway applies the change itself, except for the restart-required keys.

To changeRun
Any keydefenseclaw config set KEY VALUE; config unset KEY returns it to the default.
What blocks and what alertsdefenseclaw guardrail block-at LEVEL and alert-at LEVEL, with --connector X for one connector (Thresholds).
The rule pack, one rule, a suppressiondefenseclaw guardrail use-pack, guardrail rule enable|disable|severity and guardrail suppress add|remove (Rules).
A skill, MCP server, plugin or tool block or allow listdefenseclaw skill|mcp|plugin|tool block|allow|unblock NAME (Admission).
A custom LLM endpointdefenseclaw setup provider add, which writes llm_providers. custom-providers.json is derived from it.
The LLM that judges and scansdefenseclaw setup llm.
Scanner analyzers and policydefenseclaw setup skill-scanner and setup mcp-scanner.
A version 8 file to version 9defenseclaw migrate or defenseclaw config migrate (Migrate to version 9).

On a managed standalone device these are refused with exit 3; see Managed devices.

Interactive vs non-interactive

CommandInteractiveScriptedNotes
initOn a TTY--non-interactive --yes plus option flags--fail-mode, --observe-all and --action-connectors cover what it asks.
quickstartNoAlwaysZero-prompt by design; use init for the wizard.
setup guardrailDefault--non-interactive plus flagsMissing flags fall back to wizard defaults. Hook fail mode and judge fallback models have no flag here.
setup <connector>YesFlags plus --yesWith other connectors configured the default, also under --yes, is to add; --replace switches. With --mode, a TTY run does not ask for the mode again.
setup routingNo--enable, --disable, --statusNeeds Docker. Proxy-mode OpenAI Chat Completions traffic only.
keys setHidden prompt without a value--value-stdin (or --value, visible in ps)See Keys.
keys fill-missingYes--yes skips the opening confirmationPrompts for every required key that is unset.
keys list, keys checkNoAlwayskeys check exits non-zero when a required key is missing.
keys removeAsks to confirm--yes
setup webhook add <type>Default--non-interactive plus flagsThe type is positional; URL and secret env are prompt-or-flag.
setup webhook test <name>NoAlways--dry-run formats without delivering.
registry add <id>Default--non-interactive plus flagsregistry wizard is the first-run add-and-sync flow.
registry sync, entries, approve, rejectNoFlags onlyFor cron and scripts.
setup splunkWhen no mode flag is given--non-interactive with --logs, --enterprise or --o11yThe HEC token comes from --hec-token or DEFENSECLAW_SETUP_SPLUNK_HEC_TOKEN; the variable keeps it out of ps.
setup local-observabilityNoSubcommandsup is the default; down keeps data; reset deletes it.
setup redactionBare commandSubcommands plus flagsThe simple flow leads into Show advanced settings? for buckets, profiles, destinations and routes.
setup skill-scanner, setup mcp-scannerYes--non-interactive plus flags
config set, config unsetNoAlways--json for list and object values; --expect-sha256 refuses a change when config.yaml moved.
skill|mcp|plugin|tool block, allow, unblockNoAlwaysWrite asset_policy; no gateway call needed.
migrate, config migrateNoAlways--check or --dry-run previews; config migrate --ack marks the record as read.
sandbox setupDefault--non-interactive, or --yes for every defaultOne-time OpenShell setup on Linux or an Apple-silicon Mac.
doctorOnly with --fix--fix --yesA plain run is read-only and never prompts.
alertsNo--limit, --connector, --show <n>, --json; acknowledge and dismissA snapshot, not a live tail.
tuiFull-screenNoneInteractive only.
defenseclaw-gatewayNo--host, --portBare, it runs the foreground daemon; start, stop and restart manage the background one. Most setup commands restart a running gateway (setup guardrail takes --restart and --no-restart).

What gets written where

The install tree and the programs are listed under What the install creates. For what setup writes and where, see On-disk layout and Configuration.

Installer

install.sh (macOS and Linux) and install.ps1 (Windows) install, upgrade, repair and roll back DefenseClaw for one account. The one-line commands are on Install.

The installer downloads the release's gateway, CLI wheel and a hash-pinned list of the CLI's Python dependencies, and checks each file against checksums.txt. With cosign 2.0 or later it also verifies the Sigstore signature on checksums.txt. It installs uv if you do not have it. Either check failing stops the install before it changes anything.

Options

install.shinstall.ps1What it does
--yes, -y-YesDo not prompt.
--version X.Y.Z-Version X.Y.ZInstall a specific release (runs that release's installer).
--local DIR-Local DIRTake every release file from a directory instead of GitHub. An empty value is a usage error (exit 2).
--rollback-RollbackRestore the install the last upgrade replaced.
--connector NAME-Connector NAMEFirst install only: the agent to guard. none configures no agent.
--no-openclaw-NoOpenclawFirst install only: same as connector none.
--quickstart-QuickstartRun defenseclaw quickstart afterwards when nothing is configured yet.
--quickstart-mode MODE-QuickstartMode MODEobserve or action for that quickstart (implies quickstart).
-NoPersistPathDo not change the user PATH in the registry.
-CosignPath FILEThe cosign to check the release signature with.
-AcceptCurrentInstallWhen an earlier run's restore is not proven back only because you changed config.yaml or the connectors since, keep the install as it is now. The binaries, the bin folder and the gateway are still checked. When another installer (an older release's) replaced the programs the run recorded, install this release over them; they are not started for recovery. If the earlier record named no binaries, the later added gateway is stopped and the record stays until the checked replacement is installed and proven. A failed replacement keeps the record and requires the same recovery command again. The error says when this applies and gives the full command.
--help, -h-HelpShow the installer's help.

Options that take a value also accept --name=value. defenseclaw quickstart --help lists the connector names.

Environment

VariableWhat it does
DEFENSECLAW_HOMEData directory. Default ~/.defenseclaw. Use the same value for every command, including defenseclaw upgrade.
DEFENSECLAW_REPOA mirror base URL for a first install (see Mirror). Deprecated alias of update.source.
DEFENSECLAW_GATEWAY_AUTOSTART=0Set in an agent's environment: its hooks do not start a stopped gateway.

Mirror

curl -LsSf https://github.com/cisco-ai-defense/defenseclaw/releases/latest/download/install.sh | DEFENSECLAW_REPO=https://mirror.example.com/defenseclaw bash

A first install has no config.yaml, so the variable is the only way to name a mirror. Afterwards, update.source does the same for defenseclaw upgrade (Upgrade). A mirror changes only where files come from. The installer still checks the release signature against the official identity, so a mirror needs cosign 2.0 or later.

Exit codes

install.ps1 reports these when run as a file; irm | iex reports a failure as an error.

CodeMeaning
0DefenseClaw is installed.
1Not installed. An upgrade puts the previous install back.
2Nothing changed: an unknown option or value, such as a misspelled flag or a connector not on the list.
3Installed, but a connector needs attention before it is guarded again. Run defenseclaw doctor.
4Installed, but the first-run quickstart failed. The installer prints the defenseclaw quickstart ... command to run again.

Platforms

macOS on Apple silicon (arm64), Linux on x86_64 and arm64, Windows on x64 (PowerShell 5.1 or 7, Windows 10 or newer and Server 2019 or newer). Intel Macs are unsupported: the installer stops before changing anything, and Rosetta does not change that. Windows on ARM64 is not certified. Installing as root works but is discouraged, because DefenseClaw is per-user by design.

Startup behavior

On Linux and macOS the gateway runs as a background process of your account. It starts with defenseclaw quickstart, defenseclaw setup or defenseclaw-gateway start. The install adds no systemd unit, LaunchAgent or login item. When the gateway is not running (after a reboot, for example), the next hook call of an agent starts it in the background and sends its request again. This applies to the shell hooks of Claude Code, Codex, Cursor, GitHub Copilot, Devin, Hermes, Kiro and Antigravity. The OpenCode and Amp plugins do not start it. On Windows a hook starts a stopped gateway too.

A hook call that meets a gateway restart is retried for up to about 3 seconds. A longer outage ends the call with gateway restarting or not running: a fail-closed hook (a per-user strict policy, a managed host by default) blocks it; a per-user default or permissive policy lets it run with a warning. On Windows a per-user hook for a tool call waits at most about 3.5 seconds for the decision (about 4 seconds when the gateway is checking with Cisco AI Defense or the LLM judge), then applies its fail mode.

A hook does not start the gateway:

  • after defenseclaw-gateway stop, until you run defenseclaw-gateway start or restart;
  • while an install or upgrade runs;
  • for 60 seconds after a hook start failed (see ~/.defenseclaw/gateway.log);
  • when DEFENSECLAW_GATEWAY_AUTOSTART=0 is set.

While the gateway is down, a per-user install in the default or permissive policy lets agent calls run with one warning (start the gateway; defenseclaw doctor if it does not start, per-user only: Managed command availability) and a hook-failures.jsonl record; the strict policy and a managed host by default block them, in observe mode too. During an install or upgrade every hook blocks (Fail modes). When gateway.watchdog.enabled is set and the gateway process stops on its own, the watchdog starts it again after gateway.watchdog.debounce failed health checks. A gateway that runs but does not answer is not restarted by a hook or the watchdog: check defenseclaw-gateway status, or run defenseclaw-gateway restart.

Verify a download

The one-line installers verify what they download. For a file you download yourself, such as the macOS app .dmg or an enterprise package, fetch checksums.txt and checksums.txt.bundle from the same release, then in the download folder:

FILE=name-of-the-downloaded-file
REPO=https://github.com/cisco-ai-defense/defenseclaw
cosign verify-blob --bundle checksums.txt.bundle \
  --certificate-identity "$REPO/.github/workflows/release.yaml@refs/heads/main" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt
grep "  $FILE\$" checksums.txt | sha256sum -c -

On macOS use shasum -a 256 -c - in place of sha256sum -c -. The signing identity is built into the installer and the CLI, not read from a setting. On Windows, compare the file's hash with its line in checksums.txt:

$File = 'DefenseClawSetup-Enterprise-Standalone-x64.exe'
(Get-FileHash ".\$File" -Algorithm SHA256).Hash.ToLower()
Select-String -Path .\checksums.txt -Pattern ('  ' + [regex]::Escape($File) + '$')

Windows release executables are not Authenticode-signed; their integrity comes from the signed checksum set.

Enterprise release files

<version> is the release number without the v. Guides: Windows, macOS, Linux. Start with Deploy to a fleet.

Enterprise release files
# Windows x64: the Setup program and its payload manifest
DefenseClawSetup-Enterprise-Standalone-x64.exe
DefenseClawSetup-Enterprise-Standalone-x64.payload-manifest.json

# macOS (Apple silicon)
defenseclaw-enterprise-<version>-darwin-arm64.pkg
defenseclaw-enterprise-<version>-darwin-arm64.tar.gz

# Linux: RPM, DEB (preview) or archive, for amd64 or arm64
defenseclaw-enterprise-<version>-linux-amd64.rpm
defenseclaw-enterprise-<version>-linux-arm64.rpm
defenseclaw-enterprise-<version>-linux-amd64.deb
defenseclaw-enterprise-<version>-linux-arm64.deb
defenseclaw-enterprise-<version>-linux-amd64.tar.gz
defenseclaw-enterprise-<version>-linux-arm64.tar.gz