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

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