Deployment overview

Use this page to choose the right rollout path before you touch Jamf, Iru/Kandji, Intune, Linux software distribution, Claude Code, or Claude Desktop Cowork. For managed endpoint runtime installs, start with Enterprise install, then choose Windows, macOS, or Linux RPM. Provider pages contain current upload and validation details for each MDM; the Linux guide covers DNF, direct RPM, offline, Ansible, and AWS VDI deployment.

AgentKeeper has one control plane and multiple delivery paths. The control plane is the dashboard, policies, API keys, Activity, investigations, and workstation inventory. Delivery is OS-specific and agent-specific because Claude Code, Claude Desktop Cowork, and managed-device tools load hooks in different places.

Choose a path

AgentKeeper uses one control plane and endpoint identity, but delivery is modular because each vendor loads hooks differently. On macOS, the universal PKG safely reconciles only AgentKeeper-owned entries for supported local IDE/CLI surfaces and preserves customer hooks. Multi-IDE enterprise packages can cover IDE targets such as Copilot, Codex, Cursor, Windsurf, Gemini CLI, and Antigravity from one assignment. The Linux Universal RPM uses the same nine-surface catalog, explicit target users, structural safe merge, login and 15-minute reconciliation, AI Discovery reporting, and AgentKeeper-owned cleanup. Cowork and MCP Gateway remain separate deployments.

Claude Code on macOS uses MDM safe merge by default: MDM installs AgentKeeper credentials, scripts, gateway config, and only AgentKeeper-owned inner hook handlers while preserving existing non-AgentKeeper hooks. The safe merge also removes older AgentKeeper native type: "http" hooks for /api/v1/claude-code/evaluate, /audit, and /checkin before writing current command hooks. On Windows, the Intune Win32 installer structurally merges AgentKeeper into the machine-managed base file C:\Program Files\ClaudeCode\managed-settings.json; it does not use C:\ProgramData\ClaudeCode or managed-settings.d. The installer considers %USERPROFILE%\.claude\settings.json only for legacy AgentKeeper cleanup after the managed repair verifies successfully. If an existing configuration file is malformed, AgentKeeper leaves it unchanged and reports the blocked repair instead of replacing it. Customers that want Claude organization plugin governance can optionally deploy the AgentKeeper Claude Code plugin instead. Claude Desktop Cowork is a Desktop plugin surface and loads a Cowork plugin from Claude Desktop's local agent session directories. MCP Gateway is a separate gateway path for MCP routing and inventory. See Claude Code's configuration reference for the vendor's Windows managed-settings location.

MDM guides: Jamf, Iru/Kandji, and Microsoft Intune.

Surface matrix

Success criteria

A deployment is complete only when all five checks pass for the target surface:

1. Local files exist. The AgentKeeper credential files, gateway config, and selected Claude Code delivery path exist on disk.
2. Self-test reaches AgentKeeper. The status helper posts a synthetic hook event and receives a 2xx response.
3. Live hook reaches AgentKeeper. A real Claude Code or Cowork tool action updates the latest live marker.
4. Dashboard shows evidence. Activity shows rows for the expected source and workstation.
5. Policy can enforce. A known blocked read, write, command, or tool action produces a BLOCK event.

Do not call an install healthy because the management tool says "success." Package-manager or MDM success means delivery ran. AgentKeeper success means the runtime produced live evidence.

Workstations and Setup also show a Runtime protection state: Full Integrity, Basic Coverage, Mixed, Standby, Degraded, Missing, or Unknown. Standby means AgentKeeper is installed and reporting but has had no AI-agent activity in the last 24 hours; it is not an error or proof of live protection. Full Integrity means a live command preflight path has reported, while Basic Coverage means only HTTP evaluate/runtime coverage is live. Explicit credential, policy, service, hook, or repair failures remain Degraded. Self-test can prove credentials and reachability, but it is not live protection.

Rollout sequence

Managed deployment rules

• For macOS, deploy the non-secret com.agentkeeper.runtime metadata profile, then the universal PKG and root After-install token-staging script.
• Keep enrollment tokens in the MDM script's restricted secret context and pipe them over standard input. Never put a token in managed preferences, public repos, process arguments, logs, user homes, or golden images.
• Pin Windows gateway releases for enterprise rollouts. latest is acceptable for internal validation, but broad customer rollouts need explicit release control.
• Use MDM inventory or a thin package-matched status helper for daily macOS checks. Do not rerun a legacy installer script as monitoring. Linux RPM reconciles after enrollment, upgrade, and login, then every 15 minutes.
• Keep Claude Code and Cowork as separate assignments if not every developer uses both.

Policy timing

Hook-based runtime policy changes apply on the next supported agent evaluation. Developers should not wait minutes for Claude Code or Cowork policy changes after saving Base Policy or policy packs.

Gateway-managed MCP policy can still sync on the gateway heartbeat. That path is separate from Claude Code and Cowork runtime hooks.

Validation commands

Use the platform-specific pages for full copy-paste commands. These are the checks every runbook should end with.

macOS Claude Code

pkgutil --pkg-info dev.agentkeeper.runtime
sudo launchctl print system/com.agentkeeper.runtime
sudo "/Library/Application Support/AgentKeeper/helpers/agentkeeper-macos-status.sh"

Require enrollment_state=enrolled, hook_matrix.config_json=true, and a valid credential. Then open Claude Code, run /hooks to confirm AgentKeeper and pre-existing customer hooks are loaded, start a new session, and run one benign action plus one controlled blocked action.

macOS Cowork

AGENTKEEPER_API_URL=https://www.agentkeeper.dev \
  bash <(curl -fsSL https://www.agentkeeper.dev/cowork-status.sh) --self-test

Self-test proves delivery from the local hook script. Live protection is confirmed only after Claude Desktop fully quits, relaunches, starts a new Cowork chat, and runs a real tool action.

Windows Claude Code

%SystemRoot%\Sysnative\WindowsPowerShell\v1.0\powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\agentkeeper-windows-status-current.ps1 -SelfTest

Expected healthy output includes a runtime hook forwarder, a state directory, installed UserPromptSubmit, PreToolUse, PostToolUse, and SessionStart hooks, plus self-test evaluate request reached AgentKeeper.

Claude Code status validates C:\Program Files\ClaudeCode\managed-settings.json and does not require a target developer profile. Pass -TargetUser "DOMAIN\developer" or -TargetUserUpn "developer@example.com" only when the selected Windows recipe also needs Antigravity profile validation or legacy user-settings cleanup.

Linux Universal RPM

rpm -q agentkeeper-runtime
sudo rpm -V agentkeeper-runtime
systemctl status agentkeeper-runtime.service agentkeeper-reconcile.timer
sudo agentkeeper status --json
sudo agentkeeper doctor --json
sudo agentkeeper reconcile --source team-validation --json

Confirm Workstations and AI Discovery agree on provider Native Linux RPM, target user, package NEVRA, catalog version, and all nine surface states. For Claude Code, run one real allowed action and one controlled PreToolUse denial. For MCP Gateway, route one real MCP call. preseeded, binary presence, and self-test are not active evidence.

Windows Cowork

$ErrorActionPreference='Stop'; $scriptPath=Join-Path $env:TEMP 'cowork-windows-status.ps1'; $scriptUri='https://www.agentkeeper.dev/cowork-windows-status.ps1'; for($i=1;$i -le 5;$i++){try{Invoke-WebRequest -UseBasicParsing $scriptUri -OutFile $scriptPath -TimeoutSec 60; break}catch{if($i -eq 5){throw}; Start-Sleep -Seconds ([Math]::Min(($i * 2),10))}}; $nativePowerShell=if($env:PROCESSOR_ARCHITEW6432){Join-Path $env:WINDIR 'Sysnative\WindowsPowerShell\v1.0\powershell.exe'}else{Join-Path $env:WINDIR 'System32\WindowsPowerShell\v1.0\powershell.exe'}; if(-not (Test-Path $nativePowerShell)){$nativePowerShell='powershell.exe'}; & $nativePowerShell -NoProfile -ExecutionPolicy Bypass -File $scriptPath -AgentKeeperApiUrl 'https://www.agentkeeper.dev' -TargetUserUpn 'developer@example.com' -SelfTest; if($LASTEXITCODE -ne 0){throw ('AgentKeeper Cowork helper exited with code ' + $LASTEXITCODE)}

Self-test proves the PowerShell hook can reach AgentKeeper. Live protection is confirmed only after Claude Desktop fully quits, relaunches, starts a new Cowork chat, and runs a real tool action.

Uninstall commands

Use Uninstall AgentKeeper for the full runbook. For a clean reinstall of the unified Windows package, run its bundled uninstall.ps1 from the same IntuneWin release and, if Cowork was installed, run the Windows Cowork uninstaller:

%SystemRoot%\Sysnative\WindowsPowerShell\v1.0\powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\uninstall.ps1
$scriptPath=Join-Path $env:TEMP 'cowork-windows-uninstall.ps1'; Invoke-WebRequest -UseBasicParsing 'https://www.agentkeeper.dev/cowork-windows-uninstall.ps1' -OutFile $scriptPath; & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $scriptPath -TargetUserUpn 'developer@example.com'; if($LASTEXITCODE -ne 0){throw ('AgentKeeper Cowork uninstaller exited with code ' + $LASTEXITCODE)}

The unified uninstaller removes AgentKeeper from Claude Code's machine-managed base file before any eligible legacy %USERPROFILE%\.claude\settings.json cleanup. For elevated or system-context cleanup, add -TargetUser "DOMAIN\developer" or -TargetUserUpn "developer@example.com" only for Antigravity, Cowork, or an explicit legacy user-profile cleanup when the trusted install marker is unavailable.

For macOS developer-installer cleanup:

curl -fsSL https://www.agentkeeper.dev/uninstall.sh | bash

For RPM-managed Linux, use the package lifecycle. Normal removal preserves local enrollment state for rollback; purge first only when the operator explicitly intends to erase local identity, credentials, owned integrations, reconciliation links, and AgentKeeper-created safety backups:

# Optional destructive local-state removal:
sudo agentkeeper purge --local
sudo dnf remove agentkeeper-runtime

Use the enterprise uninstall and rollback guide when retiring an endpoint, removing repository bootstrap files, or verifying that no active AgentKeeper integration remains.

Troubleshooting entry points

Use these guides by symptom:

• Setup health: prove a workstation is connected and producing live runtime events.
• Missing activity events: self-test works but Activity is empty, PASS is missing, or the wrong source is being viewed.
• PASS and BLOCK events: understand full audit logging, blocked-only visibility, and policy verdicts.
• Workstations: understand host ownership, check-in, online/offline state, and inventory.

What data leaves the machine

Hook calls send the native agent payload needed for policy evaluation. Depending on the surface, that can include prompt text, command strings, file paths, MCP/tool names, edit/write payload fields, hostname, session metadata, and shell output in post-tool audit payloads. AgentKeeper stores bounded and redacted audit context for investigations.

For privacy and retention details, see Data handling and What AgentKeeper sees.