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

RequirementDetail
systemd239 or later, running as PID 1. Containers and WSL without systemd are refused
Not WSLA new install inside a WSL distribution is refused (wsl_distribution). Govern WSL from Windows
Packagex86_64 (amd64) or arm64: .deb (Debian, Ubuntu), .rpm (RHEL and derivatives), or the payload tarball
SELinuxSupported. The lifecycle loads a small defenseclaw policy module where SELinux is enabled (details)
Privilegesroot. Every enterprise linux action, status included, needs root
Other profilesNo Secure Client layout at /opt/cisco/secureclient/defenseclaw (profile_conflict)
TetragonOptional (Tetragon on a Linux fleet)

SELinux, FIPS and secrets

TopicDetail
SELinuxSupported, 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 modeRHEL 9 in FIPS mode is supported with the rpm
Application controlWith 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):

systemdSecrets
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

ItemPathOwner and mode
Binaries/opt/defenseclaw/bin: defenseclaw-gateway, defenseclaw-hook, defenseclaw-sensor-helper, and defenseclaw-acp when presentroot, 0755
Managed OpenCode plugin/opt/defenseclaw/share/opencode/index.jsroot, 0644
Config/etc/defenseclaw/config.yamlroot:defenseclaw, 0640
Policies/etc/defenseclaw/policiesroot:defenseclaw, 0750
Secrets/etc/defenseclaw/secretsSee above
Target manifest/etc/defenseclaw/hook-guardian/targets.yaml (the enumerator writes it)Directory root:defenseclaw, 0750
Runtime descriptor/etc/defenseclaw/managed-runtime.jsonroot, 0644
Machine-policy summary/etc/defenseclaw/machine-policy.jsonReadable 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 configroot, 0700
Sensor helper state/var/lib/defenseclaw-sensor: the policy names loaded into Tetragon, their state and a pause recordroot, 0700
Gateway data/var/lib/defenseclawdefenseclaw, 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.sockDirectory 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 availabilityroot, 0755
Sandbox state/var/lib/defenseclaw/sandbox/, and /etc/defenseclaw/openshell/gateway.toml when enterprise.openshell is setdefenseclaw, 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.

UnitRuns asWhat it does
defenseclaw-gateway.servicedefenseclaw, no capabilitiesPolicy engine and hook API. Type=notify, 60 s watchdog, Restart=always. Config, binaries and ledger are read-only to it
defenseclaw-gateway-api.socketPID 1Listens on 127.0.0.1:18970
defenseclaw-gateway-hook.socketPID 1Listens on /run/defenseclaw-hook/hook.sock
defenseclaw-hook-guardian.serviceroot, bounded capabilitiesAlways 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.servicerootOne immediate reconcile, on demand
defenseclaw-hook-enumerator.serviceroot, homes read-onlyRewrites the target manifest every five minutes (in auto enrollment mode)
defenseclaw-sensor-helper.servicerootAnswers the gateway's fixed AI Discovery requests. Starts after tetragon.service and reads a running Tetragon
defenseclaw-enterprise-apply.pathPID 1Runs ensure --reason path when the config, secrets or policies change
defenseclaw-enterprise-verify.timerPID 1Runs verify daily, with up to one hour of random delay
defenseclaw-sandbox.socket, .service, defenseclaw-openshell-gateway.serviceEach 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.

hands over sockets
runs per tool call
asks over hook.sock
TrustedZ0 · Admin and OS (root)
UntrustedZ4 · User session (the user)
RestrictedZ2 · Gateway (defenseclaw)
systemdholds both sockets
AI agentruns as the user
defenseclaw-hookchecks the socket owner
Gatewayallows or blocks

List view for small screens. Use the expand button to open the drawing.

TrustedZ0 · Admin and OS (root)

  1. systemdholds both sockets
    • hands over socketsGatewayZ2

UntrustedZ4 · User session (the user)

  1. AI agentruns as the user
    • runs per tool calldefenseclaw-hook
  2. defenseclaw-hookchecks the socket owner
    • asks over hook.sockGatewayZ2

RestrictedZ2 · Gateway (defenseclaw)

  1. Gatewayallows or blocks
Linux. systemd opens 127.0.0.1:18970 and /run/defenseclaw-hook/hook.sock at boot and keeps them open while the gateway restarts, so a hook that connects mid-restart waits for the real gateway. The hook sends nothing until it has checked that root or defenseclaw owns the socket, and the gateway learns the caller's uid from the kernel.
writes
reads
starts, as the user
repairs hooks
PrivilegedZ1 · Services (root)
ProtectedZ3 · Admin-owned files
UntrustedZ4 · User session (the user)
Enumeratorlists the users
Guardianchecks every minute
Target manifesttargets.yaml
Per-user workerruns as the user
Agent configin the user's home

List view for small screens. Use the expand button to open the drawing.

PrivilegedZ1 · Services (root)

  1. Enumeratorlists the users
    • writesTarget manifestZ3
  2. Guardianchecks every minute
    • readsTarget manifestZ3
    • starts, as the userPer-user workerZ4

ProtectedZ3 · Admin-owned files

  1. Target manifesttargets.yaml

UntrustedZ4 · User session (the user)

  1. Per-user workerruns as the user
    • repairs hooksAgent config
  2. Agent configin the user's home
Linux. The enumerator lists the users to protect in /etc/defenseclaw/hook-guardian/targets.yaml. Every minute the guardian, which runs as root, starts a short-lived worker as each listed user, and the worker puts back DefenseClaw's hooks in that user's agent config. Root never writes a user's files with its own rights.

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

2. 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.yaml
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: true

AI 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.yaml

3a. 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.json

The 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 --update

On 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 --update

For a new payload path, use the add command above instead.

Without fapolicyd, run ensure once:

sudo "$PAYLOAD/defenseclaw-gateway" enterprise linux ensure --payload "$PAYLOAD" --json

With 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" --json

For 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" --json

Fapolicyd 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 --update

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

CodeMeaning
0Success, or nothing to do
1Failure. 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
2Invalid arguments
75Another 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.key

Rotation 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_MIN from /etc/login.defs (1000 when unset), and local accounts above UID_MAX (60000 when unset). enterprise.enrollment.uid_min changes the minimum and uid_max caps local and directory accounts alike;
  • accounts with a nologin shell, unless in include_users;
  • accounts whose home is outside /home and /var/home. Add roots with enterprise.enrollment.home_roots; include_users does not override this;
  • accounts in exclude_users or exempt_users, and accounts the group filters leave out;
  • root, uid 65534 and nobody, 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 --json

status reports the state. verify also checks every file, permission, service and readiness check, and exits 1 when anything fails. A healthy status, trimmed:

enterprise linux status --json (healthy, 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.targets counts per-user targets. Machine-policy connectors have none, so 0 is normal when you enable only those.
  • With no agent enabled, status warns no_connectors_enabled and verify fails.
  • 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 status and verify warn unprivileged_user_namespaces or unprivileged_ptrace and report incomplete security. See User namespaces.
  • hook_process_fail_open appears once per enabled connector, with the connector name first, and security_incomplete lists the warnings that keep security_complete false.

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). status and verify list such drop-ins as the warning unit_drop_in.
  • Any other setting in a drop-in DefenseClaw did not write (User, ProtectHome, ExecStart, ReadWritePaths), an Environment line that sets a DEFENSECLAW_* or loader variable, and an empty Environment= line fail status and verify.
  • The managed gateway reads /etc/defenseclaw/config.yaml and /var/lib/defenseclaw only, and ignores DEFENSECLAW_CONFIG and DEFENSECLAW_HOME.
sudo systemctl show defenseclaw-gateway.service \
  -p User -p NoNewPrivileges -p CapabilityBoundingSet \
  -p ProtectSystem -p ProtectHome -p ReadOnlyPaths -p ReadWritePaths

User 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:

SettingWhat stopped working
user.max_user_namespaces=0Codex's workspace sandbox, RootlessKit and rootless containers, a standard user's unshare -Ur
kernel.yama.ptrace_scope=2OpenShell 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=0
  • kernel.unprivileged_userns_clone=0 (Debian kernels)
  • kernel.apparmor_restrict_unprivileged_userns=1 and kernel.apparmor_restrict_unprivileged_unconfined=1 together

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 stateThe 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 hostuser.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 socket

The 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 unverified

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

ItemLinux
Engine folderclaude-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 identityLinux 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/mcp

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

GoalCommand
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 accountAdd --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 commandEffect
apt remove defenseclaw-enterpriseRuns 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-enterpriseRuns 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-enterpriseRuns 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-enterprise

On 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 ensure with 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-downgrade exists (Upgrade, Roll back). The first ensure of a new release migrates an older config_version and keeps config.yaml.v8.bak and migration-v9.json.
  • A package older than the config. The package refuses to install, before it replaces any file, when config.yaml has a config_version newer 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 runs ensure, 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.