Deploy with Compose

services:
  kaio:
    image: kaio:latest
    container_name: kaio
    ports:
      - "8080:8080"
    restart: unless-stopped
    environment:
      - KAIO_ADDR=0.0.0.0:8080
      - KAIO_DB=sqlite:/app/data/kaio.db
      - KAIO_EVENTS_RETENTION_DAYS=30
      - KAIO_LOGS_TAIL=100
      - RUST_LOG=info
      # An AI agent over MCP, off unless you set it: read, write or admin, and
      # the Host names /mcp answers on top of loopback
      # - KAIO_MCP=read
      # - KAIO_MCP_ALLOWED_HOSTS=kaio.example.net
      # Prometheus scraping /metrics, off unless you set it, with a token in
      # front of an endpoint that names your stacks, images and CVE counts
      # - KAIO_METRICS=on
      # - KAIO_METRICS_TOKEN=a-long-random-string
    volumes:
      # Required to inspect and control containers/images
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # Persistent storage for the SQLite DB and user-deployed stacks
      - ./data:/app/data

docker compose up -d

The service is then available at http://localhost:8080.

What matters in that file

• KAIO_ADDR=0.0.0.0:8080: the default 127.0.0.1 is not reachable from outside the container.
• ./data: holds both the SQLite database and stacks/<name>/compose.yml. This is the one directory to back up.
• The socket, read-only: enough for the Docker API, which takes commands over the protocol spoken on the socket rather than through writes to the file.
• KAIO_MCP left out: the MCP endpoint is off until the variable says otherwise, and a container needs KAIO_MCP_ALLOWED_HOSTS too, since /mcp answers loopback Host headers only until you name one.
• KAIO_METRICS left out: /metrics is not routed at all until the variable says otherwise. Turning it on is how Prometheus and Grafana get a history longer than the day Kaio keeps, and alerts on what only Kaio knows. See Prometheus and Grafana. Configuration lists every other variable with its default.

Caution

Kaio has no authentication: whatever reaches its port controls the Docker daemon, which is root-equivalent on that host. Mounting the socket is what grants it that. Do not expose port 8080 publicly: put it behind a reverse proxy with authentication, or bind it to a private interface. See Security.

Images

CI publishes to GHCR on every push to main and on tags:

ghcr.io/rgaidot/kaio:latest
ghcr.io/rgaidot/kaio:<short-sha>
ghcr.io/rgaidot/kaio:<version>

See Build and release for the full set of build and push targets.

Upgrading

docker compose pull
docker compose up -d

Migrations run automatically on startup and only move forward, so back up ./data before you pull. The full procedure, and the way back when it goes wrong, is in Upgrading.

Related

• Security
• Reverse proxy
• Upgrading
• Backup and restore
• Configuration