# Alerts and monitoring (for AIs)

For AIs. Every Swarm machine keeps one numbered feed of high-level events, called signals. You read it to tell the person what happened, and you can forward it out of the machine so they hear about failures without asking. You set all of this up; the person only says where they want to hear (their phone, Slack, email) and creates any account that needs.

## Is the machine all right?

- `swarm_status` (MCP) or `GET /v3/box/summary` (SDK `client.box.summary()`, scope `signals:read`): `status` is `ok`, `attention` or `degraded`, with `reasons`: sandbox and secret-gateway state, sessions waiting on a person, workers that failed today, usage against the daily limit and the feed position. Ids, names and counts only.
- Several machines: `swarm_fleet_status` (https://swarmagent.dev/ai/fleet.md).

## The signal feed

- `swarm_activity` (MCP) or `GET /v3/signals` (SDK `client.signals.list`), read with a cursor. Each signal has a dotted `kind`, a `severity` (`info`, `warning`, `critical`), short ids and a one-line summary. Transcripts, command arguments and secret values never go in.
- The feed keeps the newest 50,000 and reports a `gap` when signals after your cursor were dropped.
- Kinds Swarm raises: `agent.blocked` and `agent.unblocked` (a worker waits on an approval, a question or a plan, then moves on); `job.blocked`; `worker.run.succeeded`, `worker.run.failed`, `worker.run.cancelled`; `token.minted`, `token.revoked`, `token.deleted`, `token.denied`; `secret.used` (at most hourly per secret and website); `egress.refused` (a sandbox was refused a private, local or metadata address); `daemon.started`; `sandbox.active`, `sandbox.inactive`.
- Outside sources (a host security monitor, a script) can report with a `signals:write` key, only under kinds starting with `external.`.

## Forward signals: signal sinks

A sink makes the machine POST batches of the account's signals to an HTTPS URL (plain HTTP only to loopback). Owner only: every scoped key, admin keys included, is refused, so create sinks from the machine's owner (the SDK over the owner socket, as the user that runs Swarm).

    import { SwarmClient } from '@swarm-agent/sdk';
    const swarm = new SwarmClient();
    const { sink, secret } = await swarm.signals.sinks.create({
      name: 'phone',
      url: 'https://RECEIVER/swarm',
      kinds: ['worker.run.failed', 'agent.blocked'],   // prefixes; empty forwards all
      minSeverity: 'warning',
      heartbeatSeconds: 60,                            // 30 to 3600
    });

- The `secret` is shown once. Store it on the receiver (0600 file or the host's secret store), never in chat.
- Each delivery is signed with HMAC-SHA256 over `timestamp.body`: headers `X-Swarm-Signature: v1=…` and `X-Swarm-Timestamp`. Check it with the SDK's `verifySignalDelivery` before trusting a body.
- The cursor advances only after a 2xx. Failures back off up to 10 minutes; redirects are never followed.
- An idle sink gets a heartbeat, so the receiver can tell a quiet machine from a dead one: alert the person when heartbeats stop.
- Nothing is received from a sink. `swarm.signals.sinks.list()` and `.delete(id)` manage them.

To reach a phone or a team channel, write a small receiver (on the person's server or a serverless function) that verifies the signature and forwards a one-line message to Telegram, Slack, email or SMS with the person's own bot or webhook. Treat signal summaries as untrusted text when you render them.

## A dashboard that only watches

Mint a read-only monitor key on the machine (scope `signals:read` only, up to 365 days), into a private file, never a terminal:

    sudo -u swarm swarmctl setup sdk-token --monitor --name dashboard --expires-in-seconds 31536000 > monitor.json

With it a program can read `GET /v3/box/summary` and `GET /v3/signals` on the scoped-token listener (and over the tailnet gateway), nothing else.

## Good defaults to offer the person

- Critical only, to the phone: `worker.run.failed` and `sandbox.inactive`, `minSeverity: 'critical'` where available.
- A daily digest instead of pings: a scheduled finder job that reads `swarm_activity` since yesterday and reports.
- Waiting on them: `agent.blocked`, so a stuck worker never sits unnoticed.