Linux standalone deployment
Install the standalone DefenseClaw enterprise services on Linux from the deb or rpm package or the payload tarball, check the result, and remove them.
On Linux, DefenseClaw runs machine-wide in the standalone profile only. The lifecycle installs a fixed set of systemd units, and systemd (PID 1) owns the gateway's sockets, so no user process can take them over. Standard users cannot stop the services or change the config, and the hook guardian restores DefenseClaw's hooks if a user removes them. Terms are in Concepts.
Deploying with an MDM or configuration management?
This page installs on one computer from a root shell. For Intune, Ansible, Puppet, Chef, Salt or another tool, start with Install with an MDM. It uses the same packages and config.
Requirements
| Requirement | Detail |
|---|---|
| systemd | 239 or later, running as PID 1. Containers and WSL without systemd are refused |
| Not WSL | A new install inside a WSL distribution is refused (wsl_distribution). Govern WSL from Windows |
| Package | x86_64 (amd64) or arm64: .deb (Debian, Ubuntu), .rpm (RHEL and derivatives), or the payload tarball |
| SELinux | Supported. The lifecycle loads a small defenseclaw policy module where SELinux is enabled (details) |
| Privileges | root. Every enterprise linux action, status included, needs root |
| Other profiles | No Secure Client layout at /opt/cisco/secureclient/defenseclaw (profile_conflict) |
| Tetragon | Optional (Tetragon on a Linux fleet) |
SELinux, FIPS and secrets
| Topic | Detail |
|---|---|
| SELinux | Supported, for unconfined and confined users. Where SELinux is enabled the lifecycle loads a small defenseclaw policy module (semodule -l) that labels the hook socket defenseclaw_hook_sock_t and the gateway binary defenseclaw_gateway_exec_t, so the gateway runs in its own domain, defenseclaw_gateway_t. Every user domain may connect to that domain and to no other service; the gateway still authorizes each caller by uid. Uninstall removes the module. status and verify warn selinux_module_missing while confined users cannot reach the socket, and the lifecycle warns selinux_relabel or selinux_module if relabeling or loading fails |
| FIPS mode | RHEL 9 in FIPS mode is supported with the rpm |
| Application control | With fapolicyd, package-database trust covers the deb and rpm. For a tarball, trust the staged payload, run ensure --no-start, add /opt/defenseclaw/ trust on a fresh install or update its existing entry on an upgrade or rerun, then run ensure to start and verify (Application control) |
If a payload install reports that the staged gateway could not run, check
fapolicyd trust, SELinux policy, execute permission and noexec mount options.
The systemd version decides how the gateway reads secrets, and how much of the
units' sandboxing applies (systemd ignores directives it does not know; RHEL 8 runs
without ProtectHostname, ProtectKernelLogs, ProtectClock, ProtectProc and
ProcSubset; the Linux threat model
lists each):
| systemd | Secrets |
|---|---|
| 247 or later | /etc/defenseclaw/secrets is root:root 0700, each file 0600. The gateway receives them through LoadCredential= |
| 239 to 246 | /etc/defenseclaw/secrets is root:defenseclaw 0750, each file 0640 |
Layout
| Item | Path | Owner and mode |
|---|---|---|
| Binaries | /opt/defenseclaw/bin: defenseclaw-gateway, defenseclaw-hook, defenseclaw-sensor-helper, and defenseclaw-acp when present | root, 0755 |
| Managed OpenCode plugin | /opt/defenseclaw/share/opencode/index.js | root, 0644 |
| Config | /etc/defenseclaw/config.yaml | root:defenseclaw, 0640 |
| Policies | /etc/defenseclaw/policies | root:defenseclaw, 0750 |
| Secrets | /etc/defenseclaw/secrets | See above |
| Target manifest | /etc/defenseclaw/hook-guardian/targets.yaml (the enumerator writes it) | Directory root:defenseclaw, 0750 |
| Runtime descriptor | /etc/defenseclaw/managed-runtime.json | root, 0644 |
| Machine-policy summary | /etc/defenseclaw/machine-policy.json | Readable by users |
| Lifecycle state | /var/lib/defenseclaw-enterprise: lock, snapshots, deployment record, last-package-result.json, last-activation-failure.log, the last applied and a rejected config | root, 0700 |
| Sensor helper state | /var/lib/defenseclaw-sensor: the policy names loaded into Tetragon, their state and a pause record | root, 0700 |
| Gateway data | /var/lib/defenseclaw | defenseclaw, 0700 |
| Authorization ledger | /var/lib/defenseclaw-hook-guardian, with each user's latest AI Discovery scan in ai-discovery/ | root:defenseclaw, 0750 |
| Logs | /var/log/defenseclaw: empty unless a jsonl destination writes there. Services log to the journal (Logs and events) | defenseclaw, 0750 |
| Hook socket | /run/defenseclaw-hook/hook.sock | Directory defenseclaw, 0755. Socket 0666: every user may connect, and the gateway authorizes each caller by uid |
| Sandbox launcher | /usr/bin/defenseclaw, a link to defenseclaw-gateway that offers users only the commands in Managed command availability | root, 0755 |
| Sandbox state | /var/lib/defenseclaw/sandbox/, and /etc/defenseclaw/openshell/gateway.toml when enterprise.openshell is set | defenseclaw, 0600 files; root |
The gateway runs as the defenseclaw system account, created with
systemd-sysusers or useradd. An existing defenseclaw account with a login
shell is refused and reported, because whoever signs in as it could stop the
gateway. Remove it with userdel defenseclaw or give it /usr/sbin/nologin, then
run ensure again.
| Unit | Runs as | What it does |
|---|---|---|
defenseclaw-gateway.service | defenseclaw, no capabilities | Policy engine and hook API. Type=notify, 60 s watchdog, Restart=always. Config, binaries and ledger are read-only to it |
defenseclaw-gateway-api.socket | PID 1 | Listens on 127.0.0.1:18970 |
defenseclaw-gateway-hook.socket | PID 1 | Listens on /run/defenseclaw-hook/hook.sock |
defenseclaw-hook-guardian.service | root, bounded capabilities | Always running. Reconciles each user's hooks every minute through a worker that runs as that user, which also runs the user's AI Discovery scan. Every 5 seconds it checks the hook binary and Claude Code's 90-defenseclaw.json drop-in; if either is gone or changed it logs tamper: and starts defenseclaw-enterprise-apply.service, whose ensure puts them back |
defenseclaw-hook-guardian-reconcile.service | root | One immediate reconcile, on demand |
defenseclaw-hook-enumerator.service | root, homes read-only | Rewrites the target manifest every five minutes (in auto enrollment mode) |
defenseclaw-sensor-helper.service | root | Answers the gateway's fixed AI Discovery requests. Starts after tetragon.service and reads a running Tetragon |
defenseclaw-enterprise-apply.path | PID 1 | Runs ensure --reason path when the config, secrets or policies change |
defenseclaw-enterprise-verify.timer | PID 1 | Runs verify daily, with up to one hour of random delay |
defenseclaw-sandbox.socket, .service, defenseclaw-openshell-gateway.service | Each user (systemd user units) | The user's sandbox daemon and, in setup mode, OpenShell gateway (Sandboxes) |
The package installs units in /usr/lib/systemd/system; a tarball install writes
them to /etc/systemd/system. Put host-specific drop-ins in
/etc/systemd/system/<unit>.d/. The lifecycle writes its own drop-ins
(30-defenseclaw-tetragon.conf, 40-defenseclaw-agent-prefixes.conf,
50-defenseclaw-paths.conf, 60-defenseclaw-credentials.conf,
70-defenseclaw-network.conf) and verify does not report them as overrides.
Those five file names are DefenseClaw's; do not edit them. Every other name is
yours and the lifecycle never touches it. Use 00- to 29- or 80- to 99-
(for example 80-site-proxy.conf), and leave defenseclaw out of the name, so
a reader can tell your drop-ins from DefenseClaw's.
List view for small screens. Use the expand button to open the drawing.
TrustedZ0 · Admin and OS (root)
- systemdholds both sockets
- hands over socketsGatewayZ2
UntrustedZ4 · User session (the user)
- AI agentruns as the user
- runs per tool calldefenseclaw-hook
- defenseclaw-hookchecks the socket owner
- asks over hook.sockGatewayZ2
RestrictedZ2 · Gateway (defenseclaw)
- Gatewayallows or blocks
List view for small screens. Use the expand button to open the drawing.
PrivilegedZ1 · Services (root)
- Enumeratorlists the users
- writesTarget manifestZ3
- Guardianchecks every minute
- readsTarget manifestZ3
- starts, as the userPer-user workerZ4
ProtectedZ3 · Admin-owned files
- Target manifesttargets.yaml
UntrustedZ4 · User session (the user)
- Per-user workerruns as the user
- repairs hooksAgent config
- Agent configin the user's home
Install
Stage the config first, then install the package or the tarball.
1. Get and check the release
Download the package (defenseclaw-enterprise-<version>-linux-<arch>.deb or
.rpm), checksums.txt and checksums.txt.bundle from one GitHub release.
cosign verify-blob --bundle checksums.txt.bundle \
--certificate-identity "https://github.com/cisco-ai-defense/defenseclaw/.github/workflows/release.yaml@refs/heads/main" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
checksums.txt
sha256sum --ignore-missing -c checksums.txt2. Stage the config
Write the config as config_version: 9. ensure also takes a config_version: 8
file: it migrates it to 9, keeps config.yaml.v8.bak and migration-v9.json, and
warns config_version_8. It refuses any other version with config_invalid.
The lifecycle requires deployment_mode: managed_enterprise,
enterprise.profile: standalone and data_dir: /var/lib/defenseclaw. If you set
gateway.api_bind or gateway.api_port, they must be 127.0.0.1 and 18970.
config_version: 9
deployment_mode: managed_enterprise
data_dir: /var/lib/defenseclaw
policy_dir: /etc/defenseclaw/policies
enterprise:
profile: standalone
gateway:
api_bind: 127.0.0.1
api_port: 18970
guardrail:
enabled: true
mode: observe
connectors:
codex: {}
claudecode: {}
ai_discovery:
enabled: trueAI Discovery is off unless the config sets ai_discovery.enabled: true, as above. With no config the lifecycle uses a built-in default that protects nothing. For a
custom rule pack see Custom rule packs.
Put the file where the lifecycle reads it:
sudo install -d -o root -g root -m 0755 /etc/defenseclaw
sudo install -o root -g root -m 0640 config.yaml /etc/defenseclaw/config.yaml3a. Install the package
VERSION=1.0.4 # the release you deploy
ARCH=amd64 # or arm64
sudo apt install "./defenseclaw-enterprise-${VERSION}-linux-${ARCH}.deb"
# RHEL and derivatives:
# sudo dnf install "./defenseclaw-enterprise-${VERSION}-linux-${ARCH}.rpm"
sudo cat /var/lib/defenseclaw-enterprise/last-package-result.jsonThe post-install script runs enterprise linux ensure --from-package: it creates
the service account, validates the config, lays out the files, starts the units,
verifies, and rolls back on any failure. It never fails the package transaction,
so always check "ok": true in last-package-result.json. No package manager?
Use the tarball.
Exit codes: 0 success or nothing to do, 1 failed (rolled back), 2 invalid
arguments, 75 another run holds the lock.
3b. Or install from the tarball
Use the tarball on hosts without dpkg or rpm. The payload folder and its binaries must be owned by root and not writable by group or others:
VERSION=1.0.4 # the release you deploy
ARCH=amd64 # or arm64
PAYLOAD="/root/defenseclaw-enterprise-${VERSION}"
sudo install -d -o root -g root -m 0700 "$PAYLOAD"
sudo tar -xzf "defenseclaw-enterprise-${VERSION}-linux-${ARCH}.tar.gz" \
-C "$PAYLOAD" --no-same-owner --no-same-permissions
sudo chmod -R go-w "$PAYLOAD"On hosts with fapolicyd, add the staged payload folder to the trust file after its first extraction and before running the gateway:
sudo fapolicyd-cli --file add "$PAYLOAD/" --trust-file defenseclaw && sudo fapolicyd-cli --updateOn a rerun with the same untouched staged folder, reuse its trust entry. If you extract the tarball again into that folder or change its files, update the entry before running the gateway:
sudo fapolicyd-cli --file update "$PAYLOAD/" --trust-file defenseclaw && sudo fapolicyd-cli --updateFor a new payload path, use the add command above instead.
Without fapolicyd, run ensure once:
sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux ensure --payload "$PAYLOAD" --jsonWith fapolicyd, stage a fresh install without starting services, add the installed tree to the trust file, check it as the service user, then start and verify:
sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux ensure --payload "$PAYLOAD" --no-start --json
sudo fapolicyd-cli --file add /opt/defenseclaw/ --trust-file defenseclaw && sudo fapolicyd-cli --update
sudo -u defenseclaw /opt/defenseclaw/bin/defenseclaw-gateway --version-json
sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux ensure --payload "$PAYLOAD" --jsonFor an upgrade or rerun of a tarball installation, begin while the gateway
service is active. After the staged-payload trust step above, run this complete
two-stage flow. Update the existing installed-tree entry between the two
ensure calls; add would append entries rather than refresh matching paths:
sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux ensure --payload "$PAYLOAD" --no-start --json
sudo fapolicyd-cli --file update /opt/defenseclaw/ --trust-file defenseclaw && sudo fapolicyd-cli --update
sudo -u defenseclaw /opt/defenseclaw/bin/defenseclaw-gateway --version-json
sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux ensure --payload "$PAYLOAD" --jsonFapolicyd updates are asynchronous. If the service-user version check is
denied just after --update, retry it after fapolicyd finishes syncing. It
must succeed before the final ensure. Verify the result with
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify --json
and check that defenseclaw-gateway.service is active.
After deleting the payload folder, remove its staged trust entry:
sudo fapolicyd-cli --file delete "$PAYLOAD/" --trust-file defenseclaw && sudo fapolicyd-cli --updateensure installs when nothing is installed, applies a different payload,
re-applies a changed config, repairs a deployment that fails verification, and
otherwise does nothing. Add --config <absolute path> for a config elsewhere and
--no-start to stage with the services stopped. A host installed from the package
refuses a tarball upgrade (package_owned_binaries). A hand-built layout stops the
install with unmanaged_layout_present; --adopt-existing backs it up to
/var/lib/defenseclaw-enterprise and takes it over.
| Code | Meaning |
|---|---|
0 | Success, or nothing to do |
1 | Failure. A failed install, upgrade or repair is rolled back, and a refusal before any change leaves the computer as it was. For status and verify, the deployment is unhealthy |
2 | Invalid arguments |
75 | Another lifecycle run holds the lock. Retry later |
4. Add the AI Defense key
Optional. Without a key the local policy engine decides alone. Set
enterprise.inspection.ai_defense.enabled: true and
credential: ai-defense-api-key in the config, then store the key:
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise secret set \
--name ai-defense-api-key --from-file /root/ai-defense.key --json
sudo rm /root/ai-defense.keyRotation and removal: AI Defense key. Which accounts are protected: Enrollment.
Users who are enrolled
The enumerator finds accounts through NSS, so directory users (LDAP, SSSD, Active Directory) count as well as local ones. It skips:
- accounts below
UID_MINfrom/etc/login.defs(1000 when unset), and local accounts aboveUID_MAX(60000 when unset).enterprise.enrollment.uid_minchanges the minimum anduid_maxcaps local and directory accounts alike; - accounts with a nologin shell, unless in
include_users; - accounts whose home is outside
/homeand/var/home. Add roots withenterprise.enrollment.home_roots;include_usersdoes not override this; - accounts in
exclude_usersorexempt_users, and accounts the group filters leave out; root, uid 65534 andnobody, always.
See Enrollment.
Verify the install
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status --json
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify --jsonstatus reports the state. verify also checks every file, permission, service
and readiness check, and exits 1 when anything fails. A healthy status, trimmed:
{
"schema_version": 2,
"ok": true,
"action": "status",
"profile": "standalone",
"platform": "linux",
"installed": true,
"transaction_pending": false,
"readiness": { "gateway": true, "guardian": true, "enumerator": true, "sensor_helper": true },
"enrollment": { "targets": 16, "pending": 0, "failed": 0, "exempt": 0 },
"coverage_complete": true,
"security_complete": false,
"warnings": [
{ "code": "hook_process_fail_open", "message": "claudecode: a killed PreToolUse hook or PreToolUse timeout is non-blocking; ..." },
{ "code": "hook_process_fail_open", "message": "codex: a killed PreToolUse hook or PreToolUse timeout is non-blocking; ..." },
{ "code": "unprivileged_user_namespaces", "message": "standard users can create user namespaces (user.max_user_namespaces=...): ..." },
{ "code": "unprivileged_ptrace", "message": "standard users can trace their own processes (kernel.yama.ptrace_scope=0): ..." },
{ "code": "security_incomplete", "message": "security_complete is false because of: hook_process_fail_open, unprivileged_user_namespaces, unprivileged_ptrace; ..." }
],
"errors": []
}enrollment.targetscounts per-user targets. Machine-policy connectors have none, so0is normal when you enable only those.- With no agent enabled,
statuswarnsno_connectors_enabledandverifyfails. - A new user appears after the next enumerator cycle (up to five minutes). To
reconcile at once:
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux reconcile --json. - On most distributions
statusandverifywarnunprivileged_user_namespacesorunprivileged_ptraceand report incomplete security. See User namespaces. hook_process_fail_openappears once per enabled connector, with the connector name first, andsecurity_incompletelists the warnings that keepsecurity_completefalse.
Gateway sandbox
The gateway unit runs with an empty capability bounding set and a strict systemd
sandbox (NoNewPrivileges, ProtectSystem=strict, ProtectHome=true, private
devices and /tmp, ProtectProc=invisible, no SUID or namespace changes, and the
@system-service system-call set). Config, binaries and the ledger are
read-only to it. The guardian is bounded to CAP_CHOWN CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_KILL CAP_SETGID CAP_SETUID, and the enumerator to the
same without CAP_DAC_OVERRIDE. Do not edit the units; put host-specific
settings in a drop-in and never widen the gateway sandbox.
- A drop-in may set ordering, resource limits, restart and timeout tuning, and
host environment (a proxy, a CA bundle).
statusandverifylist such drop-ins as the warningunit_drop_in. - Any other setting in a drop-in DefenseClaw did not write (
User,ProtectHome,ExecStart,ReadWritePaths), anEnvironmentline that sets aDEFENSECLAW_*or loader variable, and an emptyEnvironment=line failstatusandverify. - The managed gateway reads
/etc/defenseclaw/config.yamland/var/lib/defenseclawonly, and ignoresDEFENSECLAW_CONFIGandDEFENSECLAW_HOME.
sudo systemctl show defenseclaw-gateway.service \
-p User -p NoNewPrivileges -p CapabilityBoundingSet \
-p ProtectSystem -p ProtectHome -p ReadOnlyPaths -p ReadWritePathsUser namespaces
On most distributions as shipped (Ubuntu 24.04 and RHEL 9 included), status
and verify warn unprivileged_user_namespaces, unprivileged_ptrace or both
and report security_complete: false. A standard
user who can create a private user and mount namespace, or trace their own
processes (for example with PRoot), can start an agent with its own view of the
machine-policy files, the runtime descriptor and /run/defenseclaw-hook. That
agent never calls the hook, so its tool calls are outside your enforcement
(Residual risks). At
start and whenever a vendor policy file or the runtime descriptor changes, the
gateway compares the content digest of exactly the policy files the vendor
reads (drop-ins it ignores excluded) with the digest pinned in the
administrator-owned runtime descriptor. The hook does no policy-view work on a
call. When the view is missing, changed or unreadable, managed hook calls are
still inspected under the managed policy, and the gateway raises a HIGH
runtime alert (enterprise_managed_policy_view_unverified, source
managed_hook) in the audit log: once when the view changes, and with each
call, rate limited. Only a hook with no trusted runtime descriptor refuses.
Linux also refuses a hook in a private user namespace, where it cannot verify
the gateway's listener, and a traced hook. A private mount view alone (for
example a pam_namespace login) is not refused. The gateway reads the host's
files, so it cannot see a private view inside one agent process, and an agent
that omitted its managed hook before launch makes no call to inspect.
After an administrator or MDM changes a vendor machine-policy file or adds a
drop-in, run sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux reconcile --json
(or ensure). It pins the new view once DefenseClaw verifies it and names the
connector in changes; until then, hooks keep enforcing and raise the alert.
Vendor policy paths are not watched by the apply unit; the daily verify timer
reports drift but does not repair it.
DefenseClaw never writes host-wide kernel or sysctl settings. An administrator may apply optional hardening with their own host management tools after testing the host's workloads. On a managed RHEL 9.8 host these settings disrupted other work:
| Setting | What stopped working |
|---|---|
user.max_user_namespaces=0 | Codex's workspace sandbox, RootlessKit and rootless containers, a standard user's unshare -Ur |
kernel.yama.ptrace_scope=2 | OpenShell Docker sandboxes, a standard user's gdb and strace |
status and verify report the observed live kernel values through
unprivileged_user_namespaces and unprivileged_ptrace warnings. They do
not treat old boot markers or a prior value as proof of current protection.
On Ubuntu 24.04 you can close only the namespace route with
kernel.apparmor_restrict_unprivileged_unconfined=1, which also restricts
bubblewrap-based command sandboxes. Neither setting stops a modified agent
client or loader and runtime preloads (LD_PRELOAD, LD_AUDIT,
NODE_OPTIONS=--require); use application control such as fapolicyd for
those.
Which setting the warning names
unprivileged_user_namespaces goes silent when any one of these holds:
user.max_user_namespaces=0kernel.unprivileged_userns_clone=0(Debian kernels)kernel.apparmor_restrict_unprivileged_userns=1andkernel.apparmor_restrict_unprivileged_unconfined=1together
If it cannot read user.max_user_namespaces, it says so and asks you to check
the kernel setting. Otherwise the text depends on the host:
| Host state | The warning names |
|---|---|
kernel.apparmor_restrict_unprivileged_userns=1, unconfined restriction 0 or absent (the Ubuntu 24.04 default) | kernel.apparmor_restrict_unprivileged_unconfined=1 or user.max_user_namespaces=0, and says an unconfined process can still switch profile with aa-exec |
| Any other host | user.max_user_namespaces=0, or restricting unprivileged user namespaces with SELinux or AppArmor |
unprivileged_ptrace goes silent when kernel.yama.ptrace_scope is 2 or 3.
Otherwise it asks for kernel.yama.ptrace_scope=2, because a tracer such as
PRoot can rewrite the paths an agent opens. Both warnings end with the same
advice: ask the host administrator to apply optional kernel hardening with
their own tools. With either warning, security_complete is false.
detect.sh --require-healthy still reports a stock host healthy and prints the
warnings on standard error; --require-security-complete reports it unhealthy.
What a private-namespace refusal looks like
An agent started inside a private user namespace (for example with unshare or
a sandbox tool) is refused, not allowed. Its hook call is blocked with:
this agent runs in a private user namespace (for example one started with unshare or a sandbox tool), where DefenseClaw cannot check it or reach its hook socketThe user sees "Start the agent from your normal login session; if this
continues, contact your administrator." The gateway records the refusal as an
auth-failure audit row with reason enterprise_managed_user_namespace, and
writes this line to its journal:
[sidecar-api] hook socket refused uid=1001 connector="codex" route=<route> reason=enterprise_managed_user_namespace: the agent process context is unsafe or unverifiedA traced hook is refused the same way ("this agent's hook is being traced, so
another process may change the policy paths it reads"). To find these, search
the gateway journal for hook socket refused.
AI Discovery Plane C (Tetragon)
AI Discovery runtime detection has three planes: A watches inference compute, B
attributes network traffic and C records agent actions from kernel events
(Runtime planes). Plane C
runs in the root sensor helper. It is opt-in: set ai_discovery.runtime.enabled
and ai_discovery.runtime.enable_host_plane to true. If the computer runs
Tetragon, the helper uses it as a better source (consume),
reports the events of your own Tetragon policies that hit an AI agent, and can load
a small fixed set of kernel controls through it (observe, then enforce).
DefenseClaw does not install or configure Tetragon, never writes to
/etc/tetragon and never changes a policy of yours. The fleet task flow, hardening
settings, enterprise linux tetragon verify, approval, pause and removal are in
Tetragon on a Linux fleet; how this fits with hooks,
sandboxes and the egress proxy is in Agent segmentation.
Claude Cowork
Claude Desktop for Linux is a beta, and Cowork on Linux is not certified. In the 1.0.8 tests the managed drop-in and per-user setup were verified on Linux, but Cowork itself was not run. The Claude Code drop-in (/etc/claude-code/managed-settings.d/90-defenseclaw.json) is meant to cover Cowork where it runs. There is nothing to configure for Cowork itself.
| Item | Linux |
|---|---|
| Engine folder | claude-code/<version>/ in ~/.config/Claude, or in ~/.config/Claude-3p for third-party inference. These follow the vendor's convention; no Linux engine build has been measured. A relocated XDG_CONFIG_HOME is not followed |
| Engine identity | Linux builds carry no vendor signature. A build counts only when its version folder holds an executable claude. It is reported as unsigned, and as unidentified while it runs, so verify fails while Cowork or the Code tab runs |
See Claude Cowork for the tools, managed_hooks_only and the limits.
Sandboxes
A Linux standalone install can run coding agents in OpenShell sandboxes under the
sandbox policy of each person's directory group. They are off until
openshell.enabled is on. The rpm and deb package the defenseclaw launcher and
the user units; you provide OpenShell (install: prerequisite) or let each
person's daemon download it (install: setup). The Docker driver needs Docker
Engine 28 or newer with BuildKit, Landlock ABI 3 or newer (sandbox doctor
reports the running kernel's ABI) and the person in the docker group. The
optional MicroVM driver also needs /dev/kvm, the kvm group and e2fsprogs, and
falls back to Docker where KVM does not work. ensure and verify print a row
for each piece.
Membership in docker is root-equivalent: a member can read and change what root
can, including /etc/defenseclaw/config.yaml, the protected credentials and the
services' environment. The only mitigation is to add only the accounts that run
sandboxes; ensure, status and verify count the enrolled accounts in the
group (docker_group_members). A member can also run an agent in a plain
container outside DefenseClaw, bypassing sandbox.required_for, so
administrators who need required_for to hold against deliberate users must not
give them Docker access. There is no root-owned image and lifecycle service to
close this limit. Keys, recipes and what people see are in
Sandboxes on managed computers.
Per-user installs
On a computer with /etc/defenseclaw/managed-runtime.json the per-user product
refuses to run: install.sh refuses and changes nothing, defenseclaw upgrade
refuses, and the per-user gateway refuses to start. Installers from 0.8.x predate
the managed marker and do not check for it, so a user can still install one after
you deploy; the managed gateway keeps enforcing and the per-user copy cannot start
its own gateway. If such an installer says "existing installation detected" and
points to the upgrade resolver, that text is not meant for managed computers.
Nothing migrates a per-user install. Before you deploy, have each user run
defenseclaw uninstall --binaries --yes (add --all to delete ~/.defenseclaw;
Uninstall). If a user set up Claude Cowork, they also remove the DefenseClaw plugin in Claude Desktop (Customize > Plugins, then the ... menu on DefenseClaw, Remove); until then Cowork tool calls are blocked.
A config.yaml a per-user install left in ~/.defenseclaw is not the policy the
device enforces. An older per-user CLI on the user's PATH refuses per-user
commands and exits 3. The packaged managed defenseclaw launcher shows the
account's own connectors with status, and offers sandbox and guardrail profile
views; the full list is in Managed command availability. It refuses doctor, alerts, tui and per-user configuration commands
with exit 2, naming the installed administrator status, verify and audit
export commands.
A per-user gateway still running holds the managed port 127.0.0.1:18970 unless
its user moved it. The install then stops before it changes anything with
api_port_held, naming the process and the kill command. The package install
completes, with the error in last-package-result.json. Stop that gateway or move
it, then run /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux ensure --from-package. A
per-user gateway on another port keeps running; the install, status and verify
name each such account with per_user_gateway_running.
Scan skills, MCP servers and plugins
The package installs the skill, MCP and plugin scanners. An administrator scans with the gateway's scanners, policy and judge:
sudo /opt/defenseclaw/bin/defenseclaw-gateway scan skill /opt/defenseclaw-scan/my-skill
sudo /opt/defenseclaw/bin/defenseclaw-gateway scan plugin /opt/defenseclaw-scan/my-plugin
sudo /opt/defenseclaw/bin/defenseclaw-gateway scan mcp https://mcp.example.com/mcpThe scan runs through the managed gateway, and only an administrator can read its token, so run
it with sudo. The gateway service cannot read home folders, /root, /tmp, /var/tmp or /run/user. Copy the folder to one that every account can read, such as
/opt/defenseclaw-scan, and scan the copy. A refused scan exits 3 and says Nothing was scanned. A deployment installed from the payload archive has no scanner runtime: install the
package to scan.
Remove
Run these as root from /opt/defenseclaw/bin.
| Goal | Command |
|---|---|
Stop and remove the deployment, its config, secrets and logs, most of its data and lifecycle state, and the defenseclaw account. Each user keeps ~/.defenseclaw, and your policies in /etc/defenseclaw/policies stay. When an account keeps sandboxes, /var/lib/defenseclaw/sandbox and /var/lib/defenseclaw/redaction-correlation.key stay with the root-only records /var/lib/defenseclaw-enterprise/openshell-state.kept.json and /var/lib/defenseclaw-enterprise/retained-state.json and the marker /var/lib/defenseclaw/.defenseclaw-retained. They are root-owned while the service account is gone; the next ensure adopts them | /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --json |
Also remove each enrolled user's ~/.defenseclaw and per-user binaries | /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --purge --json |
| Keep the config, secrets, data and logs (and the account) for a reinstall | /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --keep-state --json |
Keep only the defenseclaw account | Add --keep-service-account |
Uninstall removes each user's DefenseClaw hook registrations and DefenseClaw's own
machine-policy entries first; administrator entries stay. If the sensor helper
loaded policies into Tetragon, it deletes those defenseclaw-* policies before
removing any file (Remove the policies, or downgrade).
The result's kept: line names accounts that still have ~/.defenseclaw or
per-user binaries. With --purge it also stops each enrolled user's per-user
gateway and removes ~/.defenseclaw, the empty agent folders DefenseClaw created,
the per-user binaries in ~/.local/bin and DefenseClaw's wheels in ~/.cache/uv. If an enrolled account had its own DefenseClaw install before the enrollment (its ~/.defenseclaw holds config.yaml, .env, audit.db, previous/, or the program the per-user installer puts there, .venv/ or installer/, also when the account never ran defenseclaw init), --purge leaves that folder and the install's binaries exactly as they are and names the account in the result (kept the DefenseClaw per-user data of user <name> ... and a per_user_state_remaining warning). A machine uninstall never deletes or moves an account's own data. The purge first moves the backups an earlier release saved for a connector it removed (connector_backups/openhands and connector_backups/omnigent) to ~/.defenseclaw-removed-connector-backups, and stops without deleting anything if it cannot. Accounts the deployment never enrolled keep their DefenseClaw files (an earlier per-user install, or hooks a former enrollment left). The purge result lists each such account on a kept: warning; delete those files with the account's owner. An account the machine policy covered without a per-user enrollment (not named in the enrollment manifest) is purged the same way when its ~/.defenseclaw holds only what DefenseClaw wrote there (hook scripts, hook tokens and settings, connector backups, also those an earlier failed install left); when it holds the account's own install, the account is named as above. The managed deployment shares ~/.defenseclaw with such an own install. The uninstall, with or without --purge, puts back what the enrollment changed there: the install's hook scripts and hook settings, connector backups, hook contract lock and session cache, byte for byte, and each agent config those backups name when the uninstall left that file as it was before the own install. An agent config that changed while the computer was managed stays as it is and is named in a per_user_state_remaining warning; that user runs defenseclaw setup again if its hooks are missing. Use --purge instead of a plain uninstall to
delete user data: the plain uninstall removes the enrollment record a later
--purge needs, and a purge after it warns per_user_state_remaining. To clean up
afterward, run ensure --from-package --config <file> and then uninstall --purge,
or delete the files by hand. If uninstall reports an error, it keeps the deployment
record, config and state so you can fix the cause and rerun. The plain uninstall
keeps /etc/defenseclaw/policies (root-owned, mode 0751) and removes the vendor
policies in /opt/defenseclaw/share/policies; --purge removes your policies too.
To turn the deployment on again, run ensure --from-package --config <file> on a
package host. On a tarball host without fapolicyd, stage the payload and run
"$PAYLOAD/defenseclaw-gateway" enterprise linux ensure --payload "$PAYLOAD" --config <file>.
With fapolicyd, follow the staged-payload trust and two-stage
tarball install, passing --config <file>
to both ensure calls. Add installed-tree trust if there is no prior entry;
update an existing entry after staging. After an uninstall or reinstall, ask
users to restart their agents (agent_sessions_restart_required).
On a package host uninstall leaves the package's binaries and units, so dpkg or
rpm still lists defenseclaw-enterprise. Removing the package runs uninstall:
| Package command | Effect |
|---|---|
apt remove defenseclaw-enterprise | Runs plain uninstall, then removes the package files and /opt/defenseclaw/share/policies. The config, most state and the defenseclaw account go, also after a failed package install that rolled back; /etc/defenseclaw/policies stays. If an account keeps sandboxes, /var/lib/defenseclaw/sandbox and redaction-correlation.key stay; each user keeps ~/.defenseclaw. Use lifecycle --purge to remove enrolled user data |
apt purge defenseclaw-enterprise | Runs the same plain lifecycle uninstall, then deletes what it left of /etc/defenseclaw, /var/lib/defenseclaw (including sandbox and redaction-correlation.key), /var/lib/defenseclaw-hook-guardian and /var/log/defenseclaw, plus lifecycle state except the root-owned lifecycle.lock. It does not purge each enrolled account's home; run lifecycle --purge first. The sandboxes accounts kept in their homes are no longer known to a later install, because their registrations are gone: run defenseclaw sandbox pull NAME --apply (or --branch or --patch-out FILE) and confirm the work was saved first |
dnf remove defenseclaw-enterprise | Runs plain uninstall, then removes the package files and /opt/defenseclaw/share/policies. Same results as apt remove, including the sandbox store and key that an account's kept sandboxes leave behind; delete /etc/defenseclaw/policies by hand when you no longer need it |
If uninstall refuses before any change (uninstall_precheck_refused) or stops
before removing the binaries (uninstall_incomplete), apt or dnf fails and keeps
the package files. Its result stays in last-package-result.json. Fix the cause it
names, then run the removal again.
To remove the deployment and enrolled user data from a package host, purge with the lifecycle first, while the binary still exists:
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux uninstall --purge --json
sudo apt purge defenseclaw-enterprise
# RHEL and derivatives:
# sudo dnf remove defenseclaw-enterpriseOn a tarball host, uninstall --purge removes the deployment, including
/opt/defenseclaw. DefenseClaw no longer creates sysctl files or reboot
markers under /etc/sysctl.d, and removing the deployment does not change the
running kernel. Administrators of a host that received an earlier 1.0.4
prerelease opt-in should review its existing /etc/sysctl.d files with their
own host management tools.
Upgrades and changes
- Upgrade. Install the newer package with apt or dnf. On a tarball host
without fapolicyd, run
ensurewith the newer payload. With fapolicyd, use the staged-payload trust and two-stage flow. The lifecycle refuses an older release unless you pass--allow-downgrade, and the package refuses an older package unless/var/lib/defenseclaw-enterprise/allow-downgradeexists (Upgrade, Roll back). The firstensureof a new release migrates an olderconfig_versionand keepsconfig.yaml.v8.bakandmigration-v9.json. - A package older than the config. The package refuses to install, before it
replaces any file, when
config.yamlhas aconfig_versionnewer than the release reads. Install a release that reads it, or push a config with the older version first. - Change the config. Replace
/etc/defenseclaw/config.yaml. The apply path unit runsensure, which validates and applies it or rolls back (Change the config). In bundle mode the edit is reverted; deliver a new signed bundle. - Tetragon. Read Remove the policies, or downgrade before you downgrade below the first release that supports Tetragon, and Upgrades when a release changes a kernel control.
- Failures. See Lifecycle error codes.
Windows standalone deployment
Install the standalone DefenseClaw enterprise services on Windows x64 with the Setup program, check the result, and remove them.
Tetragon on a Linux fleet
Roll DefenseClaw out to Linux computers that already run Tetragon - harden Tetragon, turn on Plane C, see your own policies' events from AI agents, observe, approve and enforce ring by ring, check the fleet, and troubleshoot - with tested Ansible and shell examples.