Self-host with Docker

Docker mode runs two services:

• App (control plane): UI + scheduler/state machine + SQLite + SSE
• Runner (execution plane): isolated execution (starts sandbox containers and streams logs back)

Quick start

1. Download docker-compose.release.yml and .env.production

    curl -fsSL -o docker-compose.release.yml https://raw.githubusercontent.com/obiscr/maia/main/docker-compose.release.yml
    curl -fsSL -o .env.production https://raw.githubusercontent.com/obiscr/maia/main/env.example

2. Edit .env.production and set RUNNER_TOKEN.

   .env.production

   RUNNER_TOKEN=your-token

3. Start

   docker compose -f docker-compose.release.yml --env-file .env.production up -d

Set up

Initial setup Open http://localhost:3690 to run the initial setup wizard.

Get updates

When you use docker-compose.release.yml (pre-built image) to deploy, updates usually involve “pulling new image → rebuilding and restarting”:

docker compose -f docker-compose.release.yml --env-file .env.production pull
docker compose -f docker-compose.release.yml --env-file .env.production up -d --remove-orphans

Database migration

In Docker mode, database migrations are handled by a one-time migrator service. When you pull a new image and restart the container:

1. The new image contains the latest migration files
2. The migrator will run prisma migrate deploy before the maia container starts
3. Already applied migrations are skipped

The entire process requires no manual intervention - Maia automatically handles database version upgrades.

Verify migration status

If you need to confirm that migrations were successfully applied, you can view the container logs:

docker compose -f docker-compose.release.yml --env-file .env.production ps -a
docker compose -f docker-compose.release.yml --env-file .env.production logs migrator --no-log-prefix

The logs will show detailed information about migration execution.