Configuration¶
Paeon is configured in two places:
- The rules file, one YAML file named by
PAEON_CONFIG: what Paeon does. Correlation, maintenance windows, sources, models, the stages, notification channels, actions, the console. - The environment: where a process runs and every secret. The address it listens on, the database path, tokens and keys.
Start from examples/paeon.yaml and .env.example. Every key is optional and every stage is off until you enable it: with an ingest token and nothing else, Paeon records alerts and groups them into incidents.
| To configure | Read |
|---|---|
| Every key of the rules file, with its type and default | Configuration reference |
| Where alerts come from | Connect your alerts |
| Each monitoring service: its alerts and what an investigation may read | Sources |
| Where Paeon sends, service by service | Notifications |
| Plans, approvals and the executor | Acting |
| The console and its proxy | The console |
How the file is read¶
- The file is read once, when the process starts. A change needs a restart of the process
that reads it (
paeon serve, andpaeon executorfor its own copy). - It is checked as a whole before anything starts. A key that does not exist, a value of the wrong type, a model alias or a channel that is named and not defined, a source with a key its service does not have: each stops the start and says which key is wrong.
- Secrets never go in the file. A key ending in
_envholds the name of an environment variable (api_key_env,token_env,webhook_env), and every secret also acceptsNAME_FILE=/path, for Docker secrets. - The executor reads the same format from its own copy, and trusts only that copy. See Acting.
The sections of the file¶
| Section | What it holds | Reference |
|---|---|---|
correlation |
How alerts become incidents: windows, host labels, flapping. | correlation |
maintenance |
Weekly windows in which alerts are expected. | maintenance |
sources |
Named monitoring services: their alerts, and what an investigation may read. | sources |
models |
Model aliases: backend, model name, key, price. A stage names an alias. | models |
triage |
Stage 1: a cheap first look at each incident. | triage |
investigation |
Stage 2: a strong model with the read-only tools you allow. | investigation |
postmortems |
Drafts written once an incident stays resolved. | postmortems |
digest |
The daily summary and its feedback questions. | digest |
notifiers |
Named notification channels, one per service. | notifiers |
actions |
Stages 3 and 4: the catalog, policies, runbooks, the executor. | actions |
ui |
The console. | ui |
telemetry |
Traces of Paeon's own work over OTLP. | telemetry |
Stages¶
| Stage | What it does | Model |
|---|---|---|
triage |
One call per incident with a context pack built by code. Verdict: noise, transient, known_issue or real. Recorded and shown in the digest. It changes no notification; the one thing it decides is whether stage 2 investigates the incident (investigation.verdicts). Page-level alerts are never sent. |
cheap |
investigation |
An agent loop with read-only tools and a budget. Hands in a summary, the impact, a root cause with a confidence, the evidence, the hypotheses it rejected and a plan. A second model can take over when the first fails or declines. | strong, with tool calls |
postmortems |
A markdown draft with YAML front matter once an incident that was investigated or acted on has stayed resolved. Timeline and automation review come from the event log; the model writes the prose; the file says status: draft. Optionally committed and pushed to a git repository. |
strong |
actions |
No model. Plans from an analysis or from a runbook go to the executor. See Acting. | none |
The budgets (daily_budget, budget_per_incident), the storm guard (max_per_hour) and the limits on tool calls and time are set per stage in the same file. A spent budget never hides an alert: Paeon fails open and treats the incident as real.
Sources¶
A monitoring service is defined once under sources, by a name of yours: Prometheus,
Alertmanager, Grafana, Loki, VictoriaLogs, OpenObserve, uptime-kuma, Gatus, Healthchecks,
Netdata, Zabbix or Beszel. A source that pushes its alerts posts them to /ingest/<name>, and
what an investigation may read in it is the allow-list of that source. See
Sources.
Notifications¶
The digest, the analysis and the approvals go to the channels you name: ntfy, Telegram, Discord,
Slack, e-mail, Gotify, Pushover, Teams, Matrix, a webhook of your own, or anything Apprise
knows. Channels are defined once under notifiers and listed per stage in notify. See
Notifications.
Environment¶
Every secret below also accepts NAME_FILE=/path.
The core (paeon serve)¶
| Variable | Default | |
|---|---|---|
PAEON_INGEST_TOKEN |
required | Bearer token the webhook senders and the API clients present. 24 characters or more. |
PAEON_CONFIG |
none | Path of the rules file. Without it, Paeon records and correlates with the defaults. |
PAEON_DB |
paeon.sqlite |
Where the event log lives. |
PAEON_HOST |
127.0.0.1 |
The address the API listens on. 0.0.0.0 in a container. |
PAEON_PORT |
8080 |
Its port. |
PAEON_OPENOBSERVE_URL |
none | Switches on the OpenObserve pull adapter. The internal address, for example http://openobserve:5080. The same can be written in the rules file, as a source. |
PAEON_OPENOBSERVE_ORG |
default |
The organisation. |
PAEON_OPENOBSERVE_USER |
The account. Required with the URL. | |
PAEON_OPENOBSERVE_PASSWORD |
Its password. Required with the URL. | |
PAEON_OPENOBSERVE_POLL_SECONDS |
60 |
How often alerts are pulled. 5 at least. |
PAEON_OPENOBSERVE_STALE_SECONDS |
900 |
No evaluation row for this long opens the internal source_stale alert. 60 at least. |
PAEON_HEARTBEAT_URL |
none | A push URL called while Paeon is healthy (an uptime-kuma Push monitor). |
PAEON_HEARTBEAT_SECONDS |
60 |
How often it is called. 10 at least. |
PAEON_EXECUTOR_TOKEN |
How the core proves itself to the executor. Required with actions.enabled, 24 characters or more, the same as the executor's. |
|
PAEON_UI_PROXY_SECRET |
The value your proxy adds to each console request. Required with ui.proxy_secret, 24 characters or more. The name can be changed there. |
The executor (paeon executor)¶
| Variable | Default | |
|---|---|---|
PAEON_EXECUTOR_TOKEN |
required | The token the core presents. 24 characters or more. |
PAEON_CONFIG |
required | Path of the executor's own copy of the rules file. |
PAEON_SIGNING_KEY |
none | The key that signs Go / No-go links. 32 characters or more, different from the token. Without it nothing can be approved. Never give it to the core. |
PAEON_EXECUTOR_DB |
executor.sqlite |
Where the executor's journal lives. |
PAEON_EXECUTOR_HOST |
127.0.0.1 |
The address it listens on. |
PAEON_EXECUTOR_PORT |
8081 |
Its port. |
PAEON_KILL_SWITCH |
off | 1, true, yes or on: every plan is only recorded, whatever the policies say. |
Variables the rules file names¶
These have no fixed name: a key of the rules file says which variable to read. The names below are the ones the examples use.
| Named by | Example | Read by | Holds |
|---|---|---|---|
models.<alias>.api_key_env |
ANTHROPIC_API_KEY |
core | A model provider's API key. |
notifiers.<name>.token_env, webhook_env, password_env, user_env, url_env, authorization_env, urls_env |
PAEON_TELEGRAM_TOKEN |
the process that sends to the channel | A channel's secret. See Notifications. |
sources.<name>.token_env, password_env, api_key_env |
PAEON_GRAFANA_TOKEN |
core | A source's secret. See Sources. |
digest.ntfy.token_env, investigation.ntfy.token_env |
PAEON_NTFY_TOKEN |
core | The ntfy token of a stage's own ntfy: block. |
actions.ntfy.token_env |
PAEON_ACTIONS_NTFY_TOKEN |
executor | The ntfy token of the approval topic. |
investigation.tools.uptime_kuma.api_key_env |
PAEON_UPTIME_KUMA_API_KEY |
core | An uptime-kuma API key, for /metrics. |
telemetry.authorization_env |
PAEON_OTLP_AUTHORIZATION |
core | The whole Authorization header of the OTLP endpoint. |
actions.coolify.token_env |
PAEON_COOLIFY_TOKEN |
executor | A Coolify API token that can deploy. |
actions.repository.github.token_env |
PAEON_GITHUB_TOKEN |
executor | A token that can open pull requests on the deployment repository. |
ui.proxy_secret.value_env |
PAEON_UI_PROXY_SECRET |
core | The value the proxy adds to console requests. |
Traces¶
telemetry:
otlp_endpoint: http://openobserve:5080/api/default
authorization_env: PAEON_OTLP_AUTHORIZATION # "Basic <base64 of user:password>"
Each incident becomes an OpenTelemetry trace: a span for the incident and one per step, with its duration, model, token counts, cost and outcome. Spans carry facts about a step and never its content: no prompt, no answer, no tool input or result.