Architecture
stromboli is a single Go binary and a Postgres database. The binary is both the server and its CLI. One instance serves one organisation: there is no multi-tenancy, and isolation comes from running separate instances (ADR 0002).
alert sources people and agents
openstatus · Alertmanager · Grafana · CLI · gRPC/Connect clients ·
generic · health checks MCP clients · Slack
│ │
▼ ▼
┌────────────────────────────────────────────────────┐
│ stromboli serve │
│ │
│ webhooks ──▶ trigger ──┐ ConnectRPC API │
│ ▼ (catalog, connectors,│
│ health checks ──▶ agent engine investigations, │
│ │ │ │ actions) │
│ brief ◀──┘ │ └──▶ action service ───┼──▶ Fly Machines API
│ │ LLM tool loop ▲ │ (after approval)
│ ▼ │ │ │
│ connector registry ◀───────────┘ │
│ │ │ │
│ │ └──▶ notifier (Slack) ─────┼──▶ Slack
└──────────────┼─────────────────────────────────────┘
│ │
logs · metrics · deploys · machines ▼
(queried on demand, read-only) Postgres: catalog, connectors,
investigations, steps, actions
The pieces
API first. Everything the CLI does goes through a public ConnectRPC API: CatalogService, ConnectorService, InvestigationService and ActionService, defined in protobuf. The same endpoints speak Connect, gRPC, gRPC-Web and plain JSON, so a future UI, scripts and other tools use the same contract as the CLI (ADR 0005). The MCP server is a thin layer over the same services.
Triggers. Webhooks normalise each alert source into one shape (title, services, fingerprint, time, resolved), match it to catalog services, and hand it to the engine. Health checks are another trigger: they read metrics on a timer and start an investigation when a threshold is crossed.
The agent engine owns investigations. It builds a deterministic brief, then runs one LLM conversation over read-only tools until a mitigation and a report are submitted. Investigations run in the background, outlive the request that started them, and are bounded by a timeout and a tool budget.
The connector registry turns a connector stored in Postgres (with encrypted secrets) into a client for Loki, Axiom, CloudWatch, Google Cloud, Prometheus, Fly.io, GitHub or Vercel. It reuses MCP sessions per connector and closes them on shutdown.
The action service stores machine actions proposed by investigations, and runs one only after a human approves it.
The notifier posts to Slack: one message per investigation, edited in place, with thread replies for what should notify on-call. Without Slack, everything is still available through the API.
Postgres holds all state: the catalog and runbooks, connectors, investigations with their audit trail, and actions (ADR 0004). Logs and metrics are not stored. Migrations run on startup.
Where it lives in the code
| Package | Job |
|---|---|
cmd/stromboli |
the CLI and serve |
internal/server |
wires everything into one HTTP server |
internal/config |
reads the environment |
internal/api |
ConnectRPC handlers and auth |
internal/trigger |
alert webhooks |
internal/agent |
the brief, the tool loop, the tools and the system prompt |
internal/llm |
provider adapters: Anthropic Messages, OpenAI-compatible, Vercel AI Gateway |
internal/catalog |
catalog YAML, validation, dependency graph, Fly helpers |
internal/connector |
the registry and one package per data source (logs, metrics, deploys, fly, gcp, mcpconn) |
internal/action |
machine actions: propose, approve, run |
internal/healthcheck |
scheduled metric checks |
internal/report |
Markdown rendering, Slack messages and buttons |
internal/mcpserver |
the MCP tools, over stdio and HTTP |
internal/policy |
redaction before data reaches the model |
internal/secrets |
AES-256-GCM encryption of connector secrets |
internal/store |
Postgres access, migrations and generated queries |
proto/stromboli/v1, gen |
the API definition and generated code |
Why one instance
A single process keeps operations simple: one container, one database, no queue. It also shapes some behaviour: alert dedupe relies on one database view of running investigations, and health checks run in every process, so a second replica would investigate the same breach twice. The deploy guides keep it to one machine for that reason. Investigations that were running when the process stops are marked failed on the next start, as are machine actions, which are worth checking by hand.
Why a CLI in the same binary
The binary that runs the server is also the client, so there is nothing else to install, and versions always match. The CLI follows clig.dev (ADR 0015): data on stdout, messages on stderr, --json for scripts, confirmation before destructive commands, and secrets never required on the command line.