Setup health

Setup health answers one question: is this workstation producing live runtime evidence for the AgentKeeper environment you are viewing?

Use this before escalating a customer install issue. The important distinction is local install versus runtime delivery. A script can install correctly while Claude Code or Cowork has not loaded the hook yet.

Health ladder

Level	What it proves	Healthy signal	If it fails
1. Origin	The install points at the right AgentKeeper app	Install command uses `https://www.agentkeeper.dev` or the customer-provided origin	Re-run setup from the correct dashboard
2. Credential	The hook can authenticate	API key or approved device credential exists locally	Reconnect the device or rotate the fleet key
3. Local files	The installer wrote the expected files	Settings file, hook file, gateway binary, logs, and state markers exist	Re-run the installer or MDM remediation
4. Self-test	A synthetic hook event reaches AgentKeeper	Status helper reports a 2xx self-test evaluate request	Inspect local state markers and outbound HTTPS
5. Live event	The real agent loaded the hook	A real tool action updates live hook and evaluate markers	Fully restart the agent and start a new session
6. Dashboard evidence	AgentKeeper stored the event	Activity shows the expected source and workstation	Check source filters, org membership, and audit logging
7. Outcome check	Policy Profile can Monitor, Warn, or Block runtime behavior	A known blocked action appears as Block	Check Base Policy, Policy Profiles, and path/tool matchers

Self-test is necessary, but not sufficient. Live protection starts only after the target agent loads the hook and sends a real runtime event.

Runtime protection states

Workstations and Setup show the latest endpoint runtime heartbeat separately from scans and Activity rows.

State	Meaning
Full Integrity	A command preflight path is installed and has reported a live pre-execution event. This is the local path AgentKeeper can block before an action runs.
Basic Coverage	HTTP evaluate/runtime coverage is live, but local command preflight is not active. AgentKeeper can still record and evaluate supported events, but this is not full local pre-execution protection.
Mixed	The endpoint reports both command preflight and HTTP runtime paths, or mixed coverage across selected surfaces. Review the detail page for which path is live.
Standby	Runtime is installed, authenticated, and reporting with healthy expected hooks, but no AI-agent activity has been observed in the last 24 hours. This is a neutral waiting state, not verified live protection.
Degraded	Runtime has an explicit credential, policy, service, hook, or repair failure that needs attention. Missing or old Activity and `restart_required` alone do not qualify.
Missing	The endpoint explicitly reports that the Runtime is absent or not reporting.
Unknown	Runtime evidence is missing, stale, or insufficient. Host online status alone does not prove that Runtime is installed.

Self-test timestamps stay visible in the detail page, but they do not upgrade a workstation to Full Integrity. Full Integrity requires live pre-execution evidence. In the Workstations table, hover, focus, or click the Protection status for its explanation. Standby does not add risk or enter Action needed; its raw backend state remains available under Advanced diagnostics.

Managed macOS Claude Code installs can exchange an MDM enrollment token for a per-device credential and then post signed runtime health. Native Windows runtime installs can do the same with agentkeeper.exe enroll-mdm and signed agentkeeper.exe heartbeat; the native package can also emit an IntuneWin source ZIP for customer packaging. Native Linux RPM installs use a scoped Enterprise Installer token over standard input, then report as provider Native Linux RPM without exposing that token to the service or target user. Validate signed package delivery before broad assignment.

Claude Code

macOS

Run these as the logged-in developer:

plutil -convert json -o /dev/null ~/.claude/settings.json && echo "settings.json: OK"
grep -n "agentkeeper" ~/.claude/settings.json
/usr/local/bin/agentkeeper-mcp-gateway version
/usr/local/bin/agentkeeper-mcp-gateway scan-inventory --dry-run < /dev/null

Then open Claude Code, run /hooks, start a new session, and run a benign tool action. Activity should show source claude_code.

Windows

Run this from the folder containing the downloaded Intune templates:

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

If you are running outside the Intune package folder, or the package folder does not include agentkeeper-windows-config.json, pass the developer explicitly with -TargetUser "DOMAIN\developer" or -TargetUserUpn "developer@example.com".

Healthy output includes:

[ok] gateway binary: C:\Program Files\AgentKeeper\agentkeeper-mcp-gateway.exe
[ok] config: C:\ProgramData\AgentKeeper\config.json
[ok] runtime hook forwarder: C:\ProgramData\AgentKeeper\agentkeeper-claude-hook.ps1
[ok] state directory: C:\ProgramData\AgentKeeper\State
[ok] UserPromptSubmit hook installed
[ok] PreToolUse hook installed
[ok] PostToolUse hook installed
[ok] SessionStart hook installed
[ok] self-test evaluate request reached AgentKeeper

If self-test is healthy but Activity is still empty, open Claude Code, run /hooks, start a new session, and run a real tool. The last check-in, last runtime hook, and last evaluate request markers update only after live activity.

Linux RPM

Run these on the enrolled RHEL or Rocky Linux workstation:

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 setup-health --json
journalctl -u agentkeeper-runtime.service -u agentkeeper-reconcile.service --since -30min

Healthy output identifies operating_system=linux, provider Native Linux RPM, package NEVRA, source SHA, catalog version, target user, and per-surface coverage. Then open Claude Code as that target user and run one harmless action plus one controlled PreToolUse denial. A successful reconcile or preseeded row proves configuration only; active requires a real vendor event.

Claude Desktop Chat

Claude Chat health is Gateway health plus Claude Desktop MCP wiring.

macOS or standalone Linux

agentkeeper-mcp-gateway version
agentkeeper-mcp-gateway auth status
agentkeeper-mcp-gateway configure-ide --ide=claude-desktop --dry-run
agentkeeper-mcp-gateway configure-ide --ide=claude-desktop
agentkeeper-mcp-gateway list --health

configure-ide writes agentkeeper-mcp-gateway server into Claude Desktop MCP config. Fully quit Claude Desktop, reopen it, and ask Chat to use a configured MCP tool. Activity should show the Claude Chat or Gateway MCP source for the workstation. On an RPM-managed Linux host, use sudo agentkeeper status --json and reconciliation from the Linux MCP Gateway guide; do not add a standalone API key.

Windows

Confirm the native Gateway install:

& 'C:\Program Files\AgentKeeper\agentkeeper-mcp-gateway.exe' version

Run the Claude Desktop configure command from the signed-in developer profile:

& 'C:\Program Files\AgentKeeper\agentkeeper-mcp-gateway.exe' configure-ide --ide=claude-desktop --dry-run
& 'C:\Program Files\AgentKeeper\agentkeeper-mcp-gateway.exe' configure-ide --ide=claude-desktop
& 'C:\Program Files\AgentKeeper\agentkeeper-mcp-gateway.exe' list --health

If the installer ran as SYSTEM, do not trust that it wrote the developer's Claude Desktop config. The configure step must run as the user who launches Claude Desktop.

Claude Desktop Cowork

Cowork validation has two phases.

macOS and vendor-supported Linux self-test

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

Healthy self-test output includes:

[ok] server check-in: workstation registered/updated
[ok] self-test evaluate request: ... http_status=200
[ok] workspace ...: marketplace manifest hooks installed
[ok] workspace ...: cache manifest hooks installed
[ok] workspace ...: Cowork plugin enabled

The Cowork shell helper applies only where Claude Desktop/Cowork meets Anthropic's current Linux requirements. On RHEL and Rocky Linux, the Universal RPM reports Cowork as discovery_only with an unsupported-distribution limitation. Do not run this helper or claim Cowork enforcement on those systems.

Windows self-test

$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)}

Healthy Windows output includes the target profile, API key file, Cowork session directory, Windows PowerShell hook command, and self-test evaluate request reached AgentKeeper.

Live test

Quit Claude Desktop fully. On macOS use Cmd-Q; on Windows use Quit from the tray or Task Manager if needed.
Relaunch Claude Desktop.
Start a new Cowork chat.
Run a real tool action.
Rerun the platform status command without the self-test flag.

Healthy live output includes updated live hook invocation and live evaluate request markers. Activity should show source cowork.

For standard Claude Cowork Team or Enterprise, the local installer can be healthy while live Cowork still does not load the plugin. If that happens, upload the AgentKeeper Cowork plugin ZIP through Claude Desktop's Upload local plugin flow or have a Claude organization owner install it from organization plugin settings.

MCP Gateway

Gateway health is separate from Claude Code and Cowork hook health.

agentkeeper-mcp-gateway version
agentkeeper-mcp-gateway scan-inventory --dry-run < /dev/null
agentkeeper-mcp-gateway auth status
agentkeeper-mcp-gateway configure-ide --dry-run
agentkeeper-mcp-gateway list --health

Gateway-routed MCP traffic appears as gateway evidence. Claude Chat is the Claude Desktop Gateway-routed surface. Claude Code or Cowork MCP activity can also be observed through runtime hooks without proxying through the gateway.

Gateway state ladder

State	Healthy signal	If it fails
Discovered	`list --health` or `/gateway/servers` shows the server from a supported local MCP client config	Verify the config location is supported, then rerun `configure-ide --dry-run`.
Migrated/routed	`/gateway/servers` shows `Routed, no calls` or better, with at least one Gateway reporting routed config	Apply `agentkeeper-mcp-gateway configure-ide` as the developer profile, then restart the MCP client.
Active/protected	`/gateway/activity` shows a real decision for the server and tool	Make a real harmless MCP tool call after restart, then rerun `list --health`.

If a server is Seen only, do not ask the customer to manually add every server. Use this order:

Run agentkeeper-mcp-gateway configure-ide --dry-run.
Verify the server came from a supported config path.
Apply agentkeeper-mcp-gateway configure-ide.
Fully restart the MCP client.
Make a real tool call.
Run agentkeeper-mcp-gateway list --health.
Check /gateway/servers and /gateway/activity.

Manual agentkeeper-mcp-gateway add is fallback/admin setup for unsupported config sources or gateway-native servers.

Control integrity

Control integrity proves the local control path is still intact after install, MDM repair, or a blocked action.

Healthy output means:

Hook settings still reference AgentKeeper.
AgentKeeper local state and API credentials exist.
The status helper can complete self-test.
A live event and known BLOCK still appear after the agent restarts.
No recent Activity event maps to control_tampering, agentkeeper_control_tamper, agentkeeper_control_config_write, agentkeeper_bypass_request, or script_tamper.

If a model suggests disabling AgentKeeper, do not follow that option. Keep the block event, decide whether the work needs a scoped security-testing exception, and repair the hook through MDM if local config drifted. See Control integrity.

What to capture for support

Capture this before opening a support issue:

AgentKeeper origin used in the install command.
User email and organization.
Hostname.
Operating system and agent surface being tested.
Exact install command, with secrets redacted.
Status helper output.
Last five Activity rows for the host.
Whether local files, self-test, live event, PASS, and BLOCK each passed.
Whether control integrity checks passed or any bypass/tamper event fired.
Whether the agent was fully restarted after install.

Passing criteria

A customer setup is healthy when it has:

A recent self-test event.
A recent live runtime event from the expected source.
A recent PASS event when full audit logging is enabled.
A recent BLOCK event from a known policy test.
The expected workstation and person mapping.

Was this page helpful?