A Guardian watches one target and decides what to do when it looks unhealthy. It is the answer to "who restarts the service at 3am" — with the important detail that it can only take actions you have explicitly allowed, and only ones that are reversible.
Each Guardian is a policy (what to watch, how carefully, what it may do) that produces incidents (what it saw, what it decided, what happened next).
The level decides how far a Guardian may go on its own. They escalate:
level
behaviour
observe
records what it sees; never notifies
notify
tells you something is wrong
suggest
tells you, and proposes a specific fix
auto_heal
applies a fix from its allow-list, then tells you
auto_heal_escalate
applies a fix and escalates if the problem persists
Two safety properties hold at every level.
Auto-heal is reversible-only. The actions a policy may take live in an explicit allow-list (restart_service, scope_action:restart and similar). Destructive operations are never stored there, so a Guardian cannot delete a Scope, drop data or tear down a network no matter how it reads the evidence. An empty allow-list downgrades the policy to suggest-only even if the level says auto-heal.
Actions are rate-capped.max_actions_per_hour (3 by default) bounds how often a Guardian may act. A policy that keeps failing trips a circuit breaker and stops acting until you look at it — a restart loop is not made faster by restarting faster.
Every detection opens an incident carrying the evidence snapshot, the verdict, the action taken and the outcome. A decision is one of observed, notified, suggested, healed, escalated or failed, and an incident has a severity and a resolution time.
Incidents deduplicate. A persistent problem produces one incident with a cooldown rather than a new alert every tick — the same approach the platform's own alerting uses, and the reason a broken service does not generate a hundred notifications overnight.
Read them in the panel under GUARDIANS, or over the API:
GET /api/v1/guardian/policies lists your policies. GET /api/v1/guardian/incidents/stream is a Server-Sent Events endpoint for live updates — a client that waits for a complete response body will hang on it.
A policy notifies through in_app, email or telegram channels.
Quiet hours and maintenance windows suppress notification during periods you choose — useful when you are deploying and expect a service to bounce. Suppression affects notification, not observation: incidents are still recorded, so the history stays complete.