macOS standalone deployment

Install the standalone DefenseClaw enterprise LaunchDaemons on Apple silicon Macs from the pkg or the payload tarball, check the result, and remove them.

The standalone macOS profile installs DefenseClaw machine-wide under /opt/cisco/defenseclaw, with LaunchDaemons labeled com.cisco.defenseclaw.* and a hidden service account, _defenseclaw. It is separate from the Cisco Secure Client module and refuses to install beside it. Standard users cannot stop the daemons 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?

This page installs on one Mac from an administrator shell. For Jamf Pro, Iru, Intune, Workspace ONE or another MDM, start with Install with an MDM. It uses the same pkg and config.

Requirements

RequirementDetail
macOS13.0 or later. The pkg refuses older versions
HardwareApple silicon only. Releases build no Intel macOS binaries
Privilegesroot, through sudo or an MDM agent. Every enterprise macos action, status included, needs root
Other profilesNo Secure Client DefenseClaw module. The pkg's pre-install script refuses when /opt/cisco/secureclient/defenseclaw or a com.cisco.secureclient.defenseclaw* LaunchDaemon exists
GatekeeperReleases currently ship the pkg unsigned, pinned by checksums.txt (details)

Gatekeeper

Only the pkg can be Developer ID-signed and notarized, and it is signed only when the release pipeline has Apple signing credentials. Releases currently ship it unsigned, pinned by checksums.txt. The tarball's binaries are never Developer ID-signed. On Macs that require notarized software, check the pkg first with spctl --assess --type install --verbose=2 <pkg>. Releases currently ship the pkg unsigned, so pkgutil --check-signature reports "no signature"; its SHA-256 in checksums.txt, whose cosign signature you check, protects it.

Layout

Paths are under /opt/cisco/defenseclaw unless shown in full.

ItemPathOwner and mode
Binariesbin: defenseclaw-gateway, defenseclaw-hook, defenseclaw-sensor-helper, and defenseclaw-acp when presentroot, 0755
Managed OpenCode pluginshare/opencode/index.jsroot, 0644
Configetc/config.yamlroot:_defenseclaw, 0640
Policiesetc/policiesroot:_defenseclaw, 0750
Secretsetc/secretsDirectory root:_defenseclaw 0750, files 0640
Target manifestetc/hook-guardian/targets.yaml (the enumerator writes it)Directory root:_defenseclaw, 0750
Runtime descriptoretc/managed-runtime.jsonroot, 0644
Machine-policy summaryetc/machine-policy.jsonReadable by users
Lifecycle statelifecycle: last-package-result.json, last-activation-failure.log, the last applied and a rejected configroot, 0700
Gateway dataruntime_defenseclaw, 0700
Authorization ledgerhook-guardian-state, with each user's latest AI Discovery scan in ai-discovery/root:_defenseclaw, 0750
Hook socketrun/hook.sockDirectory _defenseclaw, 0755
Logs/Library/Logs/Cisco/DefenseClaw, gateway logs in gateway/root, 0755; gateway/ is _defenseclaw, 0750
LaunchDaemons/Library/LaunchDaemons/com.cisco.defenseclaw.*.plistroot, 0644
Sandbox launcher/usr/local/bin/defenseclaw, a link to defenseclaw-gateway that offers users only the commands in Managed command availabilityroot, 0755
Sandbox LaunchAgents/Library/LaunchAgents/com.cisco.defenseclaw.sandbox.<tag>.plist and com.cisco.defenseclaw.openshell-gateway.<tag>.plist, run as each signed-in user. <tag> is the first 12 digits of the gateway binary's SHA-256, so each upgrade installs both agents under new labels and removes the plists of the earlier labels; releases before 1.0.4 used the labels without a tag (Sandboxes)root, 0644
Sandbox stateruntime/sandbox/, and etc/openshell/gateway.toml when enterprise.openshell is set_defenseclaw, 0600 files; root

The gateway runs as _defenseclaw, a hidden account and group the lifecycle creates with dscl (the highest free id from 300 to 499, shell /usr/bin/false, home /var/empty). Everything else runs as root.

LabelRuns asWhat it does
com.cisco.defenseclaw.gateway_defenseclawPolicy engine and hook API. Serves 127.0.0.1:18970, which launchd holds for it, and binds run/hook.sock
com.cisco.defenseclaw.hook-guardianrootAlways 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 com.cisco.defenseclaw.apply, whose ensure puts them back
com.cisco.defenseclaw.hook-enumeratorrootRewrites the target manifest every five minutes (in auto enrollment mode)
com.cisco.defenseclaw.sensor-helperrootAnswers the gateway's fixed AI Discovery requests
com.cisco.defenseclaw.applyrootRuns ensure --reason path when etc/config.yaml, etc/secrets or etc/policies changes
com.cisco.defenseclaw.verifyrootRuns verify daily at 03:17 local time
starts as _defenseclaw
runs per tool call
asks over hook.sock
TrustedZ0 · Admin and OS (root)
UntrustedZ4 · User session (the user)
RestrictedZ2 · Gateway (_defenseclaw)
launchdstarts the daemons
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. launchdstarts the daemons
    • starts as _defenseclawGatewayZ2

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
macOS. launchd opens 127.0.0.1:18970 when it loads the gateway and keeps it open while the gateway restarts, so a client or agent exporter that connects mid-restart waits for the real gateway. launchd starts the gateway as _defenseclaw, and the gateway opens run/hook.sock itself. Only _defenseclaw can write the run directory, inside the root-owned install tree, so a user cannot create a look-alike socket. 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.

Unlike systemd on Linux, launchd does not hold the sockets for the gateway: launchd hands sockets over only through launch_activate_socket(3), which needs cgo, and release builds are built without cgo. The protected socket directory and the hook's owner check do the same job.

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
macOS. The enumerator lists the users to protect in etc/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 pkg or the tarball.

1. Get and check the release

Download defenseclaw-enterprise-<version>-darwin-arm64.pkg (or the .tar.gz), checksums.txt and checksums.txt.bundle from one GitHub release. Check the signature on checksums.txt with cosign, then the file against it:

VERSION=1.0.4  # the release you deploy
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
grep " defenseclaw-enterprise-${VERSION}-darwin-arm64.pkg\$" checksums.txt | shasum -a 256 -c

Pin that SHA-256 in your MDM. pkgutil --check-signature reports "no signature" on the unsigned pkg; the checks above are what protect it.

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: /opt/cisco/defenseclaw/runtime. 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: /opt/cisco/defenseclaw/runtime
policy_dir: /opt/cisco/defenseclaw/etc/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. Each key under guardrail.connectors turns on one agent (choose the agents). Without a config the pkg installs a default that protects nothing.

sudo install -d -o root -g wheel -m 0755 /opt/cisco/defenseclaw/etc
sudo install -o root -g wheel -m 0640 config.yaml /opt/cisco/defenseclaw/etc/config.yaml

3a. Install the pkg

sudo installer -pkg "defenseclaw-enterprise-${VERSION}-darwin-arm64.pkg" -target /
sudo cat /opt/cisco/defenseclaw/lifecycle/last-package-result.json

The post-install script runs enterprise macos ensure --from-package: it creates _defenseclaw, validates the config, writes and starts the LaunchDaemons, verifies, and rolls back on any failure. A failed apply fails the pkg install, and /var/log/install.log names the first error. No pkg? Use the tarball. Exit codes of the lifecycle: 0 success or nothing to do, 1 failed (rolled back), 2 invalid arguments, 75 another run holds the lock.

How the pkg install works

The pkg installs the binaries and its post-install script runs enterprise macos ensure --from-package --reason package --json: it creates _defenseclaw, validates the config, lays out the files, writes the LaunchDaemons, starts them in order, verifies, and rolls back on any failure. A failed apply fails the pkg install, so installer and your MDM report it. The result is in last-package-result.json, and /var/log/install.log names its first error. Fix it, then install the pkg again. The pkg receipt is com.cisco.defenseclaw.enterprise; a failed install records none, and ensure --from-package records none either, so receipt-based inventory reports the Mac as not installed until the pkg installs successfully.

If you did not stage a config, the pkg installs the default, which protects nothing. Copy your config to /opt/cisco/defenseclaw/etc/config.yaml and the apply daemon runs ensure, or run it yourself:

sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos ensure \
  --from-package --config "$PWD/config.yaml" --json

3b. Or install from the tarball

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
PAYLOAD="/var/root/defenseclaw-enterprise-${VERSION}"
sudo install -d -o root -g wheel -m 0700 "$PAYLOAD"
sudo tar -xzf "defenseclaw-enterprise-${VERSION}-darwin-arm64.tar.gz" \
  -C "$PAYLOAD" --no-same-owner --no-same-permissions
sudo chmod -R go-w "$PAYLOAD"
sudo "$PAYLOAD/defenseclaw-gateway" enterprise macos ensure --payload "$PAYLOAD" --json

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 daemons stopped. A hand-built layout stops the install with unmanaged_layout_present; --adopt-existing backs it up 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. Set enterprise.inspection.ai_defense.enabled: true and credential: ai-defense-api-key in the config, then store the key:

sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise secret set \
  --name ai-defense-api-key --from-file /var/root/ai-defense.key --json
sudo rm /var/root/ai-defense.key

Rotation: AI Defense key.

Verify the install

sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status --json
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos verify --json
pkgutil --pkg-info com.cisco.defenseclaw.enterprise   # pkg installs only

status reports the state. verify also checks every file, permission (including macOS ACL entries), LaunchDaemon and readiness check, and exits 1 when anything fails. repair removes only the ACL entries that are wrong: one that lets another account change a DefenseClaw file or reach a private one, or that keeps the _defenseclaw service account from reading etc/policies and the packs in it. Other entries stay. The JSON has the same shape as the Linux sample.

FieldHealthy value
ok, errorstrue, empty
installed_versionThe version you deployed
readinessgateway, guardian, enumerator and sensor_helper all true
coverage_completetrue when the enabled hooks are installed
security_completefalse with Codex, Claude Code, Copilot, Devin, Hermes, Kiro or Antigravity enabled; hook_process_fail_open warns that a stopped, killed or timed-out hook can let a tool run
policyapplied is true (digest)
enrollment.targetsPer-user targets. 0 is normal when you enable only machine-policy connectors

With no agent enabled, status warns no_connectors_enabled and verify fails. The enumerator enrolls accounts with uid 501 or higher by default (Enrollment). To reconcile at once: sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos reconcile --json. The gateway log is /Library/Logs/Cisco/DefenseClaw/gateway/gateway.err.log.

Status details

When the config enables no agent while there are users to enroll, status warns no_connectors_enabled, verify fails and security_complete is false. Neither field checks that the expected users are enrolled, so check enrollment too. The enumerator enrolls accounts with a uid of 501 or higher by default (Enrollment). To reconcile at once: sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos reconcile --json.

agent_settings_not_restored warns when the guardian puts back a missing Hermes config.yaml or Devin config.json from a last good copy or recreates it with hooks only; it does not make security_complete false or fail verify, the exit code or MDM detection (see Warnings). A guardrail.profile_assignments group this Mac does not know selects nobody, so its members get the default profile; status and verify warn profile_assignment_unmatched, with the same list enterprise macos profile-explain --user <account> --connector <connector> shows. The gateway log is /Library/Logs/Cisco/DefenseClaw/gateway/gateway.err.log. The managed launcher offers only defenseclaw guardrail profile explain (Managed command availability). Monitoring is in Status and verify.

Claude Cowork

Claude Cowork runs its agent loop on the Mac, as the user, with the Claude Code engine that Claude Desktop bundles. The Claude Code drop-in (/Library/Application Support/ClaudeCode/managed-settings.d/90-defenseclaw.json) is meant to cover it. There is nothing to configure for Cowork itself.

ItemmacOS
MeasuredTest hooks in managed settings and in a managed-settings.d drop-in ran in Cowork turns on Claude Desktop 4.4212.0, and a deny held. In the 1.0.8 tests on a managed Mac with Claude Desktop 4.16336.0 (engine 2.1.317) using third-party inference through Amazon Bedrock, Cowork's hook calls reached the gateway with surface cowork, and an administrator deny rule blocked mcp__workspace__bash. A read of a .env file was not blocked: its contents reached the model, which chose not to repeat the key (DefenseClaw did not withhold it), and DefenseClaw recorded the secret after the read; to prevent such a read, deny the path at PreToolUse (Secrets in tool results). With managed_hooks_only: enforce an organization plugin's hooks did not run, with preserve they did, and DefenseClaw's hooks ran under both. With the gateway service stopped, Cowork prompts were blocked with enterprise_managed_gateway_not_running
Organization pluginsClaude Desktop 4.16336.0 installs a plugin in /Library/Application Support/Claude/org-plugins/ only when its .claude-plugin/plugin.json sets "installationPreference": "required"; otherwise it is only listed as available
Engine folder~/Library/Application Support/Claude/claude-code/<version>/, or Claude-3p instead of Claude for third-party inference. DefenseClaw trusts it by Anthropic's Developer ID signature, checked as the user with codesign, and by an Info.plist version equal to the folder
ShellRuns in the Cowork Linux VM on the Mac

See Claude Cowork for the tools, managed_hooks_only and the limits.

Sandboxes

A macOS standalone install can run coding agents in OpenShell MicroVM sandboxes on Apple silicon, under the sandbox policy of each person's directory group. They are off until openshell.enabled is on. The pkg packages the defenseclaw launcher and the LaunchAgents, which stay in place while sandboxes are off and leave with uninstall; you provide OpenShell or let each person's daemon download it (install: setup). The pkg supplies a MicroVM e2fsprogs fallback; set the root-owned enterprise.openshell.e2fsprogs_dir to use your own tools. Docker Desktop must run for the person, because the agent images are built there. An Intel Mac is refused with os_unsupported. Write directory groups in the spelling macOS reports (DOMAIN\group) and check them with profile-explain. Keys and recipes are in Sandboxes on managed computers.

Per-user installs

On a Mac with /opt/cisco/defenseclaw/etc/managed-runtime.json the per-user product refuses to run: the current install.sh (the one-line installer) refuses and changes nothing, even when the managed launcher is on the user's PATH; defenseclaw upgrade refuses (Managed command availability); 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 run one after you deploy. It installs a per-user copy, but the managed gateway keeps enforcing: the per-user copy cannot start its own gateway, because the managed gateway holds the port. Ask the user to run defenseclaw uninstall --binaries --yes.

A 0.8.x installer can also stop with "existing installation detected" and tell the user to run defenseclaw-upgrade.sh. That text is not meant for managed Macs; do not follow it. On a managed Mac, upgrades come from your deployment, not from the upgrade resolver.

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. The installed 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 separate per-user CLI, if present, exits 3 for per-user commands and its doctor reports the device as managed.

A per-user gateway still running holds the managed port 127.0.0.1:18970 unless its user moved it. The pkg install then stages the package files, but the postinstall refuses the managed deployment before applying it, with api_port_held. installer -pkg prints a generic postinstall failure and records no package receipt, so detection reports the computer as not installed. The process and kill command appear in /var/log/install.log, the error is in last-package-result.json, and enterprise macos status --json also reports the holder. Stop that gateway or move it, then run installer -pkg again (or /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos ensure --from-package, which records no receipt). 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/cisco/defenseclaw/bin/defenseclaw-gateway scan skill /opt/defenseclaw-scan/my-skill
sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway scan plugin /opt/defenseclaw-scan/my-plugin
sudo /opt/cisco/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 user folders (/Users, /var/root); a folder in /tmp is scanned. 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/cisco/defenseclaw/bin.

GoalCommand
Stop and remove the deployment, its binaries, config, secrets and logs, most of its data and lifecycle state, and the _defenseclaw account. Each user keeps ~/.defenseclaw. When an account keeps sandboxes, /opt/cisco/defenseclaw/runtime/sandbox and /opt/cisco/defenseclaw/runtime/redaction-correlation.key stay with the root-only records /opt/cisco/defenseclaw/lifecycle/openshell-state.kept.json and /opt/cisco/defenseclaw/lifecycle/retained-state.json and the marker /opt/cisco/defenseclaw/runtime/.defenseclaw-retained. They are root-owned while the service account is gone; the next ensure adopts them/opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos uninstall --json
Also remove each enrolled user's ~/.defenseclaw and per-user binaries/opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos uninstall --purge --json
Keep the config, secrets, data and logs (and the account) for a reinstall/opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos 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. Use --purge for a clean image. 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. The result's kept: line names accounts that keep data. Pass --purge in the same run as the uninstall: uninstall deletes the list of enrolled accounts, so a later --purge is a no-op (not_installed). To clean up afterward, delete ~/.defenseclaw by hand, or install again and run uninstall --purge. macOS lets only a process with Full Disk Access delete the _defenseclaw account. Run from an ssh session or an MDM agent without it, the delete is refused (eDSPermissionError) and the uninstall still completes with a service_account warning carrying the two dscl commands; run them from a Terminal or MDM script that has Full Disk Access (or grant it with a PPPC profile).

A pkg has no uninstaller, so the lifecycle removes the binaries itself. The root-owned lifecycle/lifecycle.lock remains so waiting runs share one lock. For a pkg install it also runs pkgutil --forget com.cisco.defenseclaw.enterprise. Uninstall also removes the shared folders the deployment created, such as /opt, /opt/cisco, /usr/local/bin and /Library/Logs/Cisco, once they are empty. A folder that existed before the install stays, empty or not. A deployment installed before 1.0.9 did not record /opt, /opt/cisco, /usr/local and /usr/local/bin, so those stay until you remove them. launchd keeps a record for each removed label, so launchctl print system lists the labels as enabled while no job stays loaded. macOS also keeps any privacy (TCC) decision about the gateway binary, such as Full Disk Access; remove it in System Settings > Privacy & Security > Full Disk Access, or remove the MDM PPPC profile that granted it.

Upgrades and changes

  • Upgrade. Install the newer pkg, or run ensure with the newer tarball. An older pkg is refused unless the root-owned marker /opt/cisco/defenseclaw/lifecycle/allow-downgrade exists; the lifecycle refuses an older tarball unless you pass --allow-downgrade (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.
  • Change the config. Replace /opt/cisco/defenseclaw/etc/config.yaml. The apply daemon 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.
  • Failures. See Lifecycle error codes.

Privacy prompts

The packaging ships no PPPC (Privacy Preferences Policy Control) profile. The guardian works only in hidden dot-directories inside each user's home (~/.claude, ~/.codex, ~/.config), which macOS privacy controls (TCC) do not protect.

The per-user AI Discovery scan also walks the home for package manifests and model files, and its inventory includes CLI binaries in /usr/local/bin, /opt/homebrew/bin, /opt/local/bin, /opt/dc-agents/bin, ~/.local/bin and ~/bin (it checks executability without running them). Without Full Disk Access it never opens the folders that make macOS ask the employee for permission: Desktop, Documents, Downloads, Movies, Music, Pictures, iCloud Drive, other apps' data in ~/Library/Containers and ~/Library/Group Containers, and Contacts. No employee sees a prompt attributed to defenseclaw-gateway. The scan summary is partial: detector_errors.macos_privacy reports "protected folders were not scanned". Other TCC-protected folders answer "operation not permitted" and are skipped the same way.

If your organization moves agent configuration into a TCC-protected folder, deploy a PPPC profile that grants Full Disk Access (SystemPolicyAllFiles) to /opt/cisco/defenseclaw/bin/defenseclaw-gateway, the one binary that runs the gateway, the guardian and the enumerator. Identify it by its Developer ID code requirement, which needs a signed build. With the grant the scan also reads those folders; the gateway checks the grant every ten minutes.

AI Discovery Plane C (Endpoint Security)

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 (ai_discovery.runtime.enable_host_plane: true with c in ai_discovery.runtime.planes) reads process and file events through Apple's eslogger, which the root sensor helper (/opt/cisco/defenseclaw/bin/defenseclaw-sensor-helper) runs. launchd starts the helper directly, so macOS treats it as the responsible process and it is the binary that needs Full Disk Access. Without it, Endpoint Security refuses the client (ES_NEW_CLIENT_RESULT_ERR_NOT_PERMITTED), Plane C reports running: false with that reason, and the snapshot stays degraded; Planes A and B keep working. A detached child of a terminal-launched agent can stay unattributed after it is reparented to PID 1.

Grant the access with a PPPC payload (com.apple.TCC.configuration-profile-policy):

<key>Services</key>
<dict>
  <key>SystemPolicyAllFiles</key>
  <array>
    <dict>
      <key>Identifier</key>
      <string>/opt/cisco/defenseclaw/bin/defenseclaw-sensor-helper</string>
      <key>IdentifierType</key>
      <string>path</string>
      <key>CodeRequirement</key>
      <string>(the designated requirement printed by codesign -dr - on that path)</string>
      <key>Allowed</key>
      <true/>
    </dict>
  </array>
</dict>

The code requirement needs a signed build. On an unsigned test build, grant Full Disk Access to that path by hand in System Settings, then restart the helper with sudo launchctl kickstart -k system/com.cisco.defenseclaw.sensor-helper. A config that carries enterprise.tetragon is accepted and ignored on macOS; enterprise macos status --json and enterprise macos verify report tetragon_not_applicable; plain status does not print it.

Machine policy

For Codex, Claude Code, Cursor, GitHub Copilot and OpenCode, DefenseClaw adds its hooks to the vendor's machine policy files under /etc and /Library/Application Support (files). An MDM configuration profile for com.openai.codex or com.anthropic.claudecode outranks those files; export DefenseClaw's entries in plist form and add them to your profile (Higher-precedence sources, Inspect, export and verify). After changing a vendor policy file or MDM preference, run sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos reconcile --json (or ensure). Until the new policy view is verified and pinned, managed hooks keep sending every call for inspection under the managed policy and the gateway raises a HIGH runtime alert, enterprise_managed_policy_view_unverified. This includes a per-user managed preference that appears when an account signs in. An MDM agent that delivers the same preference bytes again changes nothing: pins compare content only.

On a managed 1.0.2 macOS 15.8 test host, a standard user started Claude Code inside a sandbox-exec profile that hid its machine policy directory. Claude ran a Bash tool call, while the gateway recorded no matching call and administrator status and verify still reported complete security. A hook cannot refuse an agent that never loads it. Until agent launch and policy registration are enforced outside that process-local view, a healthy result does not prove that all Claude tool calls are inspected (M-34).