Local Docker run

This guide will start Maia from the source code repository, but the running way is Docker (App + Runner). It’s closer to production environment than pnpm dev.

Prerequisites

• Docker + Docker Compose v2
• Git

Start Maia

1. Clone the source repo

   git clone https://github.com/obiscr/maia.git
   cd maia

2. Create env file

   cp env.example .env.production

3. Edit .env.production (minimum required)

   .env.production

   RUNNER_TOKEN=your-token

   Recommended for production:

   .env.production

   RUNNER_TOKEN=your-token
   SETTINGS_ENCRYPTION_KEY=your-stable-key

4. Build sandbox image

   docker build -f Dockerfile.sandbox -t maia-sandbox .

   Then set MAIA_SANDBOX_IMAGE=maia-sandbox in .env.production file and restart.

   .env.production

   RUNNER_TOKEN=your-token
   SETTINGS_ENCRYPTION_KEY=your-stable-key
   MAIA_SANDBOX_IMAGE=maia-sandbox

5. Build and start

   docker compose --env-file .env.production up -d --build

Then open:

Open Maia Docker default port: http://localhost:3690

LAN access

If you deploy Maia on a server and access it over plain HTTP (for example http://<IP>:3690), you may hit a login loop because the browser won’t persist Secure session cookies on HTTP.

Recommended: put Maia behind an HTTPS reverse proxy and set SESSION_COOKIE_SECURE=auto. If you intentionally run HTTP only on a trusted LAN, set SESSION_COOKIE_SECURE=false (not recommended for public access).

See:

• Reverse Proxy & HTTPS
• Can’t sign in (login loop)

Data storage location

In Docker mode, data is stored in Docker named volume by default. If you want to store it on the host machine, you can set:

.env.production

MAIA_DATA_MOUNT_TYPE=bind
MAIA_HOST_DATA_DIR=/absolute/path/on/host

For example:

macOS

.env.production

MAIA_HOST_DATA_DIR=/Users/alice/maia-data

Linux

.env.production

MAIA_HOST_DATA_DIR=/home/alice/maia-data

Windows

.env.production

MAIA_HOST_DATA_DIR=C:\Users\alice\maia-data

After setting, you need to restart the container.

Get updates

When maia source code has updates, run the following commands in the source code directory:

git pull
docker compose --env-file .env.production up -d --build --force-recreate

Database migration

In Docker (from source code) mode, database migrations are handled by a one-time migrator service:

1. After you run docker compose up ..., the migrator will run prisma migrate deploy first
2. The migrator will Exited (0) and exit (this is normal) after the migration is successful
3. maia / runner will only start after the migration is successful

If you need to manually trigger migrations (for example, for debugging), you can run the migrator:

docker compose --env-file .env.production run --rm migrator

Verify migration status

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