cd ../ sermon.fyi /docs/agents

sermon — agent operations guide

a single page that teaches an ai agent how to use sermon. written for an agent reading once. humans can read it too. 

version       : v1b
last_updated  : 2026-05-01
canonical     : https://sermon.fyi/docs/agents
audience      : ai agents (primary), humans (secondary)
status        : cli + rest agent api + hosted mcp shipped
contact       : https://github.com/heimann/sermon

contents

  1. what sermon is
  2. mental model
  3. install
  4. what gets collected
  5. how an agent reads the fleet today
  6. what's planned (v1c)
  7. conventions
  8. for humans

01 / what sermon is

sermon is a server monitor built for ai agents. operators install a small zig daemon on each host. the daemon collects host signals into a local database. a hosted phoenix server aggregates the fleet. an agent queries either surface to reason about what's happening.

sermon does not execute remediations. it provides structured, high-density context. the agent decides what to do with it.

02 / mental model

three components, one direction of data flow. 

[host]  zig daemon  ──▶  local duckdb  (7-day retention)
        │
        └──(authenticated push)──▶  sermon.fyi  ──▶  postgres
                                                        │
                                                        ▼
                                          agent queries via cli or api

an agent has three ways to read sermon: hosted mcp with an account-scoped token, hosted rest api fallback, or ssh onto a host and use the local cli/local mcp for full-fidelity host-local data.

03 / install

operators enroll each host from /agents. today they run the generated install command themselves; plan 14 turns that into an agent-driven setup flow where the agent runs the same reviewed command. 

curl -fsSL https://sermon.fyi/install.sh | bash -s -- \
  --server-name HOSTNAME \
  --ingestion-key INGESTION_KEY \
  --server-url https://sermon.fyi

04 / what gets collected

per sample (~once per minute):

  • cpu: percent, user, system, iowait
  • memory: total, used, percent, swap_total, swap_used
  • top processes: name, cmdline, cpu, mem, pid
  • disks: mountpoint, total, used, percent
  • log_stats: seen, uploaded, dropped (last sampling window)

log entries (sampled, push-on-change):

  • source, unit, identifier, systemd_unit, priority, pid, message
  • timestamps in iso-8601 utc

the local duckdb retains 7 days at full resolution. the hosted postgres aggregates across the fleet for queries that span hosts.

05 / how an agent reads the fleet today

three shipped surfaces. prefer hosted mcp when the agent runtime supports it.

a) local cli (ssh onto a host)

always pass --format json. the table format is for humans. 

sermon status                       --format json
sermon metrics    --period 1h       --format json
sermon processes  --sort mem        --format json
sermon logs       --unit nginx --since 1h --priority err --format json
sermon query      "SELECT cpu_percent, collected_at
                   FROM metrics
                   WHERE collected_at > now() - INTERVAL 15 MINUTE
                   ORDER BY collected_at DESC"

sermon query takes raw sql against the local duckdb. there is no explain or anomalies command — the agent does the diagnosis.

b) hosted mcp / rest api (no ssh required)

get an account-scoped agent token from /agents. send it as Authorization: Bearer <token>. 

MCP  fleet, latest_metrics, recent_metrics, recent_logs, log_facets, alerts
REST GET  /api/agent/fleet
REST GET  /api/agent/servers/:server_id/metrics?limit=60
REST GET  /api/agent/servers/:server_id/logs?limit=60&priority=err&since=...
REST GET  /api/agent/servers/:server_id/logs/facets
REST GET  /api/agent/alert_rules
REST GET  /api/agent/alert_events

log filter parameters:

  • limit (default 60), since, until (iso-8601)
  • unit, identifier, systemd_unit, service
  • priority (syslog 0..7 or names: emerg, alert, crit, err, warn, notice, info, debug)

a metrics response, abbreviated:

{
  "server_id": "aniara-1",
  "samples": [
    {
      "id": "...",
      "hostname": "aniara-1",
      "collected_at": "2026-04-27T14:02:03Z",
      "cpu_percent": 84.2,
      "cpu_user": 71.0, "cpu_system": 12.1, "cpu_iowait": 1.1,
      "mem_total": 16777216, "mem_used": 14260000, "mem_percent": 85.0,
      "swap_total": 0, "swap_used": 0,
      "processes": [ ... ],
      "disks":     [ ... ],
      "log_stats": { "seen": 412, "uploaded": 412, "dropped": 0 }
    }
  ]
}

06 / what's planned (v1c)

not callable yet unless listed above. an agent reading this should not attempt these.

  • hosted query/schema and CLI remote mode
  • agent session tokens distinct from ingestion keys; live presence on the web
  • shared query feed (what every agent on this account is doing right now)
  • copy-to-agent incident payload polish
  • url-addressable log slices
  • anomaly baselines if dogfood validation passes

07 / conventions

  • json everywhere. cli takes --format json; the rest api is json by default.
  • raw sql via sermon query. there are no pre-baked diagnosis commands. the agent diagnoses.
  • timestamps are iso-8601 utc.
  • log priority follows the syslog scale: 0=emerg, 1=alert, 2=crit, 3=err, 4=warn, 5=notice, 6=info, 7=debug. names are accepted.
  • the daemon never executes remediations. the agent runs them, under the operator's trust.

08 / for humans

this page is written for agents. if you're a human reading it, the rest of the site is at sermon.fyi. the source is on github.

a stripped url-only companion lives at /llms.txt.