Docker events

Kaio uses a hybrid approach: an event subscription for responsiveness, a polling loop for metrics and as a safety net.

Event stream

The backend subscribes to the Docker socket’s /events API. A smart debouncer coalesces bursts (a docker compose up emits a flurry of create/start/attach events) into a single synchronization pass, so a large stack coming up does not trigger a dozen redundant syncs.

Polling loop

A background worker polls the Docker API every 15 seconds to:

• collect metrics (CPU, RAM, network I/O), which the event stream does not carry;
• act as a fallback if the event subscription drops.

The poller only fetches the expensive stats for running or paused containers; a stopped container costs nothing.

Watching the stream

The same stream the dashboard consumes is a plain SSE endpoint:

curl -N -H "Accept: text/event-stream" http://127.0.0.1:8080/api/events

Each event carries the entity it concerns, a level, and the timestamp used for ordering:

{"id":4213,"kind":"stack","entity_id":"my-db","level":"info","message":"Stack my-db restarted successfully","timestamp":"2026-09-24T01:12:03Z"}

kind is stack, container or system, and level is info or error.

Persistence and ordering

Container and stack events are persisted before being pushed to the UI, so the SSE stream never shows something the database does not have.

They are ordered newest-first by (timestamp, id). The autoincrement id acts as a deterministic tiebreaker, so events sharing a timestamp, common when a stack starts several containers at once, never appear out of order between two reads.

What lands where

Data	Destination
Container state, metrics, events	SQLite (containers, container_metrics, events)
User-deployed compose files and their .env	./data/stacks/<name>/ on disk

Events are pruned after KAIO_EVENTS_RETENTION_DAYS days (default 30).

Related

• Overview
• Persistence
• Logs and terminal