Runbooks

Agent not checking in

1. 01Confirm the service is running: agent status, or Get-Service AgentAgent.
2. 02Check egress to ingest.getkoop.ai:443. A TLS-inspecting proxy is the single most common cause — the agent pins our intermediate and refuses an intercepted connection by design.
3. 03Check the certificate: agent cert --show. An expired device certificate needs re-enrollment.
4. 04Read agent.log around the last successful check-in. The failure reason is logged in full.
5. 05If the device was de-enrolled, its certificate is revoked and it must re-enrol with a fresh Enrollment token.

An action fails repeatedly

1. 01Open the incident in Ledger and read the execution stage. The failing step, its exit code and its stderr are recorded.
2. 02Confirm the device satisfies the action’s preconditions — they are listed on the Playbook page for that action.
3. 03Check the action’s fleet-wide success rate. If it dropped recently, it is us and not you; the Playbook channel can ship a fix without an agent update.
4. 04Deny with a structured reason. It feeds the action-quality metrics and is the fastest way to get it fixed.
5. 05If it is reverting on many devices at once, narrow the Guardrail rule for that action while it is investigated.

Ticket sync drift

1. 01Check the connector sync health panel: inbound rate, webhook versus polling, error rate, last error.
2. 02If webhooks are failing, Koop falls back to polling automatically. Resolutions appear in your system up to 60s later, but nothing is lost.
3. 03Use Replay failed writes for writebacks rejected by a business rule. Idempotency keys make replay safe.
4. 04If your correlation rate has dropped, a field mapping has probably changed on your side.

Rolling back an agent version

# pin a device group to a known-good version
# Fleet → select group → Pin agent version → 1.8.1

# or per device, locally
agent pin --version 1.8.1

Pinning stops Updater from updating that group. Updater also rolls back automatically on a failed post-update health check, so in most cases you will find this has already happened.

Emergency Halt

Halt is in the top bar of every console screen. Scope it globally, per group or per device. Every agent in scope stops acting within five seconds; telemetry continues, so you keep visibility.

It travels on a channel independent of orchestration and works when Act is down. Agents that are offline receive the stand-down as their first message on reconnect, before any work is dispatched.