Skip to content
podmaker docs

Observability & Agents

Every server is observable through a mutually-authenticated agent, with live event streams and metrics on a store built for scale.

The agent

Each server runs an agent that, on first boot:

  1. Enrolls with the internal CA (step-ca), obtaining a client certificate.
  2. Dials a regional agent-gateway over an mTLS WebSocket.
  3. Runs a Hello → Heartbeat → Command protocol.

Heartbeats carry health and metrics; commands (installs, deploys, config) flow back down the same channel. Every connection is mutually authenticated.

agent-gateway

The agent-gateway is the regional edge that accepts agent connections, maintains a session registry, and fans Hello / Heartbeat / Command events between agents and the orchestrator.

Live event streams

The event-bridge bridges NATS to SSE. Browsers connect to it for live release and log streams; the control plane publishes events over HTTP and the bridge fans them out — so the panel updates without polling.

Metrics

The metrics-consumer is a durable consumer that reads the metrics stream (podmaker.metrics.*.samples) and inserts batches into ClickHouse. Metrics scale on a columnar store rather than the application database; batch size and flush interval are configurable.

→ Marketing overview: Observability & Agents