Enterprise install troubleshooting

Start with the symptom. Avoid rerunning broad installer logic until you know whether the failure is package, service, enrollment, policy, hook, live-event, or dashboard freshness.

Symptom	What it usually means	First check	Repair
No macOS PKG download is shown	The universal PKG feed is unavailable or failed closed	Download artifacts and `version.json`	Do not build a customer package from the source ZIP or substitute a legacy script. Contact AgentKeeper support for release status.
macOS PKG installed but no workstation appears	MDM installed the package, but profile delivery, token staging, or enrollment did not complete	`enrollment_state`, `managed_profile_state`, `hook_matrix.config_json`, and `credential_state`; then `/Library/Logs/AgentKeeper/install.log`	Fix missing or invalid metadata in the computer-level `com.agentkeeper.runtime` profile. If `enrollment_state=managed_token_missing`, rerun the provider's After-install token-staging script. Then run the installed remediation helper. The service checks changes each minute; network failures retry with backoff.
macOS status reports `enrollment_state=managed_profile_incomplete`	A required key is absent or empty in the computer-level `com.agentkeeper.runtime` profile. Editing a `<key>` name instead of the `<string>` value below it removes that setting	`managed_profile_state="incomplete"` and the status note `The macOS runtime is installed but its managed profile is incomplete.`; `maintenance_error_code=managed_profile_incomplete`	Restore the missing key, keeping `<key>` names exactly as documented and replacing only the `<string>` value. Redeploy the profile, then run the installed remediation helper.
macOS profile is complete and the token was staged, but the Mac never enrolls	The profile's `mdm_deployment_id` does not equal the deployment ID signed into the Enterprise Installer token, so the server rejects the enrollment as a scope mismatch. A left-in placeholder value produces this, not a missing-key error	`maintenance_state="retry_scheduled"` with `maintenance_error_code="enrollment_rejected"`; then compare the profile's `mdm_deployment_id` with the deployment ID on the token	Correct `mdm_deployment_id` in the profile, or create a token whose deployment ID matches it, and redeploy the profile. A rejected attempt discards that Mac's staged token, so rerun the provider's After-install token-staging script, then run the installed remediation helper.
macOS remediation says hooks were repaired, but status is not enrolled	Hook reconciliation ran without a valid per-device credential	Require `enrollment_state=enrolled`, `hook_matrix.config_json=true`, and `credential_state=valid` before treating `result=repaired`, `configured=true`, or `coverage_state=preseeded` as healthy	Deliver the metadata profile and After-install token script, then rerun the current package's remediation helper. `enrollment.json` is retry state, not `config.json`; never copy or rename it.
Service not running	Windows service, macOS LaunchDaemon, or Linux systemd unit failed to start	`Get-Service AgentKeeperRuntime`, `launchctl print system/com.agentkeeper.runtime`, or `systemctl status agentkeeper-runtime.service`	Start the service, inspect platform logs, and redeploy the pinned package if binary or service metadata is missing.
Credential state is invalid	Enrollment token exchange failed or per-device credential storage failed	`credential_state`, `maintenance_error_code`, and `maintenance_next_retry_at` in status	Correct or rotate the Enterprise Installer token. On macOS, rerun the provider's After-install token-staging script, then the enrollment-aware remediation helper; do not put the token in the profile or run a generic hook repair first.
Policy fetch stale or failing	Runtime is installed but cannot fetch policy	`last_policy_fetch` and HTTP status in status/doctor	Check app origin, proxy, DNS, TLS inspection, and org policy availability.
Gateway binary missing	The platform package is incomplete, or a standalone Windows/macOS Gateway download was blocked or mismatched	Check `gateway_binary` in status and the packaged path: `C:\Program Files\AgentKeeper\agentkeeper-mcp-gateway.exe`, `/usr/local/bin/agentkeeper-mcp-gateway`, or `/usr/bin/agentkeeper-mcp-gateway`	Redeploy the same verified package. For standalone Windows/macOS, verify the approved archive and checksum. Linux RPM repair is offline and must not download from GitHub. Do not expand to Full Integrity until present and real routing is proven.
Hooks missing after valid enrollment	Runtime has not applied the selected surface	Confirm `enrollment_state=enrolled` and `credential_state=valid`, then inspect the hook matrix	Run the package-matched reconcile/remediation helper, verify selected surfaces, and restart the target app. Never repair hooks first on an unenrolled Mac.
Claude Code shows `0 hooks configured` on Linux	Claude has not loaded the current root-managed AgentKeeper entries	`agentkeeper status --json`, then `/status` and `/hooks` in a newly started Claude session	Upgrade to the current signed RPM and fully restart Claude Code. Package reconciliation preserves existing managed policy and migrates earlier AgentKeeper drop-in entries automatically; do not add user-level hooks.
macOS enrolled before login, but user hooks are waiting	Machine enrollment succeeded before a regular console session existed	`targeting_mode=active_console_user`, `active_console_user`, `maintenance_state`, and the hook matrix	Sign in with a regular account, then wait for the one-minute maintenance tick or run the installed remediation helper. Do not add a username to the MDM profile. The runtime never scans `/Users` or guesses from folder names.
Windows waiting for user session	MDM installed as SYSTEM before a developer session was available	Runtime status and WTS user evidence	Let the device retry after sign-in; keep the documented Windows identity behavior.
Self-test passes but Activity is empty	Synthetic delivery works, but no real agent event has run	Last self-test versus last live event	Restart the selected AI agent and run a harmless tool action.
PASS missing	The policy/logging settings may not retain pass events, or the source is after-only	Activity filters and policy settings	Check log-all-tool-calls and source capability before treating it as an install failure.
BLOCK missing	The tested surface may not be an enforceable pre-execution path	Last command preflight and verdict trace	Test a supported pre-execution hook or gateway route; after-only telemetry cannot block.
Restart required	Hooks or plugin state changed after the app started	`restart_required=true` in runtime status	Fully restart the selected AI agent, then run one live event.
Mixed state	Some selected surfaces are healthy and others are degraded	Hook matrix per surface	Repair or remove the degraded surface from the validation scope until validated.
RPM installed, not enrolled	The package correctly contains no customer token	`agentkeeper status --json` and `/etc/agentkeeper`	Pipe a current Enterprise Installer token to `enroll-enterprise --token-stdin` with explicit deployment/user fields.
Linux socket failure	Runtime service is stopped, `/run` was recreated, or service hardening blocked startup	`systemctl status agentkeeper-runtime` and `ls -l /run/agentkeeper/runtime.sock`	Restart the service; never relax socket peer authentication or copy the device credential into user scope.
Linux repair blocked	An existing JSON/TOML file is malformed	`agentkeeper reconcile --json` and the reported path hash	Repair the customer file manually from its timestamped backup, then rerun reconcile. AgentKeeper will not overwrite malformed content.
Linux RPM removal refused	AgentKeeper could not safely remove an owned hook or managed Gateway route	`agentkeeper uninstall-integrations --json`	Repair the reported customer config and retry. Do not force-remove the binary while an IDE still routes through it.
Cowork unsupported	RHEL/Rocky is outside Anthropic's current Linux desktop/Cowork distribution contract	AI Discovery limitation	AgentKeeper keeps the available discovery evidence and reports the limitation. Cowork enforcement is unavailable on RHEL/Rocky.
SSSD target user not found	The domain user was not resolvable when enrollment/reconciliation ran	`getent passwd 'DOMAIN\\user'`	Correct SSSD/domain connectivity and rerun reconcile. Do not crawl `/home` or substitute an unverified local username.
Proxy or custom CA failure	Go runtime cannot establish outbound TLS	`journalctl`, `HTTPS_PROXY`, and `SSL_CERT_FILE` in `/etc/agentkeeper/runtime.env`	Install the enterprise CA in system trust or set an approved CA bundle, then restart. Do not disable TLS verification.
SELinux denial	Enforcing policy blocked a required file/socket/network action	`ausearch -m avc -ts recent`	Capture the AVC and use the release-certified policy/status. Do not globally set SELinux permissive.

Capture for support

Collect these before escalation:

OS/distribution, architecture, package/runtime/gateway/catalog version, package NEVRA, install source, and deployment provider.
agentkeeper status --json.
agentkeeper doctor.
Redacted support bundle.
MDM assignment name, deployment id, and last run result.
Workstation id and latest protection state in AgentKeeper.
The exact selected surfaces and whether the app was restarted after install.

Do not send raw enrollment tokens, fleet API keys, Microsoft Graph secrets, or unredacted support bundles through normal email.

On macOS, config.json and State/credential.json are runtime-generated only after a successful enrollment exchange. If enrollment.json exists, it is bootstrap retry state. Never copy, rename, or hand-edit any of these files. If a bootstrap file was copied to config.json, do not create a credential or perform manual file surgery. The device remains installed_unhealthy and hook reconciliation remains blocked. Refresh the metadata profile, stage a fresh token through the provider's root After/Post-install script, and validate the result. A successful exchange atomically writes the legitimate config and credential. If a token appears in a screenshot, profile, log, or support message, revoke it and create a replacement.

On macOS, install.log is the enrollment log; runtime.log can be empty before enrollment. Capture only safe state transitions before creating the redacted support bundle:

sudo grep -Eh 'Managed-profile enrollment|runtime maintenance state=|postinstall completed' \
  "/Library/Logs/AgentKeeper/install.log" \
  "/Library/Logs/AgentKeeper/runtime.err.log" 2>/dev/null

sudo "/Library/Application Support/AgentKeeper/bin/agentkeeper" support-bundle \
  --program-data "/Library/Application Support/AgentKeeper" \
  --install-dir "/Library/Application Support/AgentKeeper" \
  --redact

Was this page helpful?