OpenMAIC Docker setup: how to self-host the classroom

Before you start

• Docker with Compose for the container route, or Node.js 22.19+, pnpm 10+ and PostgreSQL 16 for the source route.
• A model API key. The example configuration needs only OPENAI_API_KEY; you can switch to any supported provider.
• Git, to clone github.com/THU-MAIC/OpenMAIC.

Option 1: Docker Compose

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
cp .env.example .env.local
# Edit .env.local with your API keys, then:
docker compose up --build

Open http://localhost:3000 when the build finishes. What you get:

• Two containers — the app and PostgreSQL. The app starts once PostgreSQL reports healthy.
• Persistent data — courses, generated media and runtime sessions live in the named volumes openmaic-postgres and openmaic-data. They survive docker compose down and rebuilds; docker compose down -v deletes them.
• A personal installation by default — single-user mode is on, so every browser sees the same course library, and the app is published on 127.0.0.1:3000 only. PostgreSQL is not published at all.

Configure your models

Secrets stay in .env.local. Which provider and model each job uses is declared in openmaic.yml, created from openmaic.example.yml. Providers are accounts; slots are uses of AI such as the outline, slide content, text-to-speech or web search:

providers:
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}      # OPENAI_API_KEY=sk-... in .env.local

slots:
  llm: openai:gpt-5.5              # the default chat model

With Docker, uncomment the openmaic.yml mount in docker-compose.yml to use the file; otherwise connect a model service from the model settings inside the running app.

The README lists these providers: OpenAI, Azure OpenAI, Anthropic, Amazon Bedrock, Google Gemini, DeepSeek, Qwen, Kimi, MiniMax, Grok (xAI), hosted API aggregators, TokenDance, Doubao, Tencent Hunyuan, Xiaomi MiMo, GLM (Zhipu), Ollama and Lemonade for local models, FunASR for local speech recognition, and any OpenAI-compatible API.

Before you expose it to other machines

The README gives three steps for a shared deployment:

1. Set a long random ACCESS_CODE in .env.local — at least 16 characters from a random generator. Visitors then see a password prompt and the API routes are protected too.
2. Set PERSISTENCE_POSTGRES_PASSWORD to a random value of letters and digits before the first start.
3. Publish on the network address:

OPENMAIC_PUBLISH_ADDRESS=0.0.0.0 docker compose up -d --build

These Compose-level variables come from your shell or a .env file next to docker-compose.yml, not from .env.local. Put a reverse proxy with HTTPS in front for anything public, and keep up with the project’s security releases — there have been several since v1.0.0.

Option 2: run from source with pnpm

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install
cp .env.example .env.local
cp openmaic.example.yml openmaic.yml
pnpm db:up
pnpm dev

pnpm db:up starts a development PostgreSQL in Docker on 127.0.0.1:5432. Then uncomment the local database line in .env.local:

DATABASE_URL=postgres://openmaic:[email protected]:5432/openmaic

Without a DATABASE_URL the server refuses to start and tells you how to provide one. For a production build:

pnpm build && DATABASE_URL=postgres://... pnpm start

Option 3: Vercel

The repository has a one-click Vercel button. A serverless function cannot run a database itself, so you must set DATABASE_URL to an external PostgreSQL that Vercel’s network can reach, plus at least one model API key.

Optional extras

docker compose --profile video-export up --build

On a slow network, the Docker build accepts mirror arguments for Alpine and npm:

ALPINE_MIRROR=mirrors.tuna.tsinghua.edu.cn \
NPM_REGISTRY=https://registry.npmmirror.com \
docker compose up --build

What self-hosting costs

The code is MIT-licensed and free to run. Your costs are the machine and the model usage: every lesson calls your provider for the outline, each scene, and optionally images, narration and web search. Local models through Ollama or Lemonade remove the API bill in exchange for hardware.

When self-hosting is more than you need

Self-hosting is the right choice when you need your own models, an intranet deployment or to change the code. If you only want a finished lesson, two routes skip the setup: the official demo (Open MAIC Chat explained) and the independent classroom builder on this site, which is walked through in how to use OpenMAIC. For a map of the codebase, see the OpenMAIC GitHub guide.

Frequently asked questions