Data retention

A cleanup loop runs every hour and applies two different policies.

Data	Kept for	Configurable
container_metrics	24 hours	No, the window is fixed in the code
events	30 days	Yes, KAIO_EVENTS_RETENTION_DAYS
containers	Current state only	Rows follow the host, deleted with the container
stacks, stack_versions, stack_env	Forever	Deleted with the stack, or per version with stack version-rm
image_scans	One row per image, overwritten by the next scan	Removed when the image goes

Metrics

The poller samples every running or paused container every 15 seconds, so a single container writes about 240 rows per hour, or 5,760 per day. With the fixed 24 hour window, the table settles at roughly that many rows per container and stops growing:

Containers	Rows at steady state
10	~58,000
50	~288,000
200	~1,150,000

Stopped containers cost nothing: the poller only fetches stats for containers that are running or paused.

This is also why the sparklines cover a short window. They read the same table, so no interface can show you a metric older than a day. For history beyond that, scrape Kaio with Prometheus: the window below stays what it is, and Prometheus keeps what it has seen for as long as you tell it to.

Events

Events are the only history that survives more than a day, and the only retention you control:

KAIO_EVENTS_RETENTION_DAYS=90

Set it to something long if you use events as a deployment log. They carry what happened and when, never who did it, so they are a timeline rather than an audit trail.

Stacks and versions

These are the rows that accumulate without limit, and the only ones that should. Every deploy writes a version holding the full compose file and a snapshot of the environment. A stack redeployed daily for a year carries 365 versions.

Prune them when the history stops being useful:

kaio-cli stack versions my-db
kaio-cli stack version-rm my-db 12

Deleting a stack removes its versions with it.

Reclaiming space

SQLite does not return freed pages to the filesystem on its own. After a large cleanup, compact the file with the server stopped:

docker compose stop kaio
sqlite3 data/kaio.db "VACUUM;"
docker compose start kaio

Take a backup first: VACUUM rewrites the whole database.