Validate deployment
Use this page after Windows, macOS, or Linux package deployment. Package-manager success is only the first checkpoint. AgentKeeper success requires fresh runtime health plus live evidence from the...
Use this page after Windows, macOS, or Linux package deployment. Package-manager success is only the first checkpoint. AgentKeeper success requires fresh runtime health plus live evidence from the selected AI agent.
Use the deployment test checklist when you need a repeatable validation report for your change record.
Health ladder
| Step | Required proof | Notes |
|---|---|---|
| Package | Runtime package installed at the expected version | MDM detection can start here. |
| Service | AgentKeeperRuntime, com.agentkeeper.runtime, or agentkeeper-runtime.service is running | Windows service, macOS LaunchDaemon, or Linux systemd health is necessary but not sufficient. |
| Install provenance | Non-secret package/provider evidence matches the pinned release | Windows and macOS write last-install.json; Linux reports package NEVRA, source SHA, install source, and deployment provider from root-owned state. |
| Enrollment | Per-device credential is valid | Enrollment token exchange must produce a device credential. |
| Policy | Last policy fetch succeeded | Cached policy can keep local flow fail-open while degradation remains visible. |
| Gateway | MCP gateway binary is present when Full Integrity depends on gateway routing | Check the packaged Windows, macOS, or Linux path. Presence is not enforcement proof; a real client call must be routed through Gateway. |
| Hooks | Expected surface appears in hook matrix | Missing or waiting-for-user hooks are not Full Integrity. |
| Self-test | Synthetic event reaches AgentKeeper | Self-test proves delivery, not live protection. |
| Live event | Real agent event appears from the selected surface | Restart the selected agent before testing. |
| Dashboard evidence | Workstations/Setup show fresh health | Check state, timestamps, runtime mode, and restart-required. |
| Known BLOCK | A supported pre-execution path blocks a controlled policy test | Only pre-execution hook or gateway paths can block. |
Linux commands
rpm -q agentkeeper-runtime
sudo rpm -V agentkeeper-runtime
systemctl is-active agentkeeper-runtime.service
systemctl is-active agentkeeper-reconcile.timer
sudo agentkeeper status --json
sudo agentkeeper doctor --json
sudo agentkeeper reconcile --source validation --json
journalctl -u agentkeeper-runtime.service -u agentkeeper-reconcile.service --since -30min
The package verification command prints nothing when all packaged files match.
Confirm operating_system=linux, the expected distribution/version,
architecture=amd64, source SHA, package NEVRA, Gateway version, and catalog
version. Workstations and AI Discovery must
agree on provider Native Linux RPM, workstation, target user,
service/package state, and each surface limitation.
Claude Code certification requires a real allowed action and a real PreToolUse denial from the target VDI. A filesystem self-test or a preseeded row is not active enforcement evidence.
Windows commands
Run these from an elevated PowerShell session. support-bundle reads service logs and protected runtime state, so non-admin developer shells can fail even when the runtime is healthy.
Get-Service AgentKeeperRuntime
& "C:\Program Files\AgentKeeper\agentkeeper.exe" status --json
& "C:\Program Files\AgentKeeper\agentkeeper.exe" doctor
& "C:\Program Files\AgentKeeper\agentkeeper.exe" heartbeat --json
Test-Path "C:\Program Files\AgentKeeper\agentkeeper-mcp-gateway.exe"
& "C:\Program Files\AgentKeeper\agentkeeper.exe" support-bundle --redact
macOS commands
sudo launchctl print system/com.agentkeeper.runtime
sudo "/Library/Application Support/AgentKeeper/bin/agentkeeper" status --program-data "/Library/Application Support/AgentKeeper" --install-dir "/Library/Application Support/AgentKeeper" --json
sudo "/Library/Application Support/AgentKeeper/bin/agentkeeper" doctor --program-data "/Library/Application Support/AgentKeeper" --install-dir "/Library/Application Support/AgentKeeper"
sudo "/Library/Application Support/AgentKeeper/bin/agentkeeper" heartbeat --program-data "/Library/Application Support/AgentKeeper" --install-dir "/Library/Application Support/AgentKeeper" --json
sudo "/Library/Application Support/AgentKeeper/bin/agentkeeper" support-bundle --program-data "/Library/Application Support/AgentKeeper" --install-dir "/Library/Application Support/AgentKeeper" --redact
For a healthy universal macOS enrollment, status must show:
enrollment_state="enrolled"managed_profile_state="ready"hook_matrix.config_json=truecredential_state="valid"- the expected provider, deployment, and selected-surface coverage
targeting_mode="active_console_user"
enrollment_state="managed_token_missing" means the non-secret metadata
profile is ready but the provider's After-install token-staging script has not
completed. hook_matrix.runtime_hook=true by itself means only that the
packaged runtime hook exists. It does not prove that an AI agent points to it. A
fresh live Activity event after a full app restart is the final attribution
check.
The universal macOS enrollment is device-scoped and needs no username in the
MDM profile. It can issue the per-device credential before first login. With no
regular user signed in, active_console_user can be empty and
maintenance_state="waiting_for_user"; this does not invalidate machine
enrollment. After sign-in or a user switch, the runtime resolves the active
console account through macOS Directory Services and reconciles that account on
its next one-minute maintenance tick. It never scans /Users or guesses a user
from a home-directory name.
Console checks
In Workstations, AI Discovery, and Activity, inspect:
- Protection state: Full Integrity, Basic Coverage, Mixed, Standby, Degraded, Missing, or Unknown. Standby is expected when Runtime is installed and reporting but no AI-agent activity exists in the last 24 hours.
- Runtime mode and install source.
- Package/runtime version.
- Hook matrix.
- Credential state.
- Policy fetch health.
- Last command preflight.
- Last HTTP evaluate.
- Last self-test.
- Last live event.
- Last repair result.
- Restart-required state.
Package detection versus runtime health
Use package and service detection to decide whether the software is installed
and the local runtime is alive. Do not fail package detection only because
credential_state is not yet valid; enrollment exchange and the first
heartbeat can follow package installation. Use credential, policy, hook matrix,
self-test, live event, and known BLOCK as separate gates before expanding the
deployment.
Enforcement boundary
Self-test proves that the local runtime can send a synthetic event to AgentKeeper. It does not prove the target AI agent loaded the hook. Live protection starts only after the agent sends a real runtime event on a supported pre-execution path. After-only, audit-only, or telemetry-only surfaces can record and investigate activity, but they cannot retroactively block the completed action.
Expansion checklist
Before broad assignment, each validation device group should show:
- Package and service installed on every scoped device.
- Root/admin-only install provenance with version/provider/install-source evidence and no enrollment token.
- No enrollment token in package metadata, managed preferences, service command line, LaunchDaemon plist, or world-readable file. The root-only staged token is absent after a successful exchange.
- No per-device username mapping in the universal macOS MDM profile.
- Fresh per-device credential status.
- Healthy policy fetch.
- MCP gateway binary present when the selected surface needs gateway routing for Full Integrity.
- Hook matrix for the selected surface after a regular user signs in.
- One self-test event.
- One real live event after app restart.
- One controlled BLOCK on a supported pre-execution path.
- Clean rollback or uninstall on one test workstation.