How to Install and Run OpenMAIC
This guide is based on the open-source project OpenMAIC by THU-MAIC, licensed under MIT. StackGuide AI is not affiliated with OpenMAIC.
OpenMAIC is an open multi-agent interactive classroom: instead of a single chat answer, it generates a lesson as slides, narration, images, video clips and interactive elements, with several agents playing different teaching roles. As of October 31, 2026, its GitHub repository has 42,081 stars. This guide is written in StackGuide AI's own words from the project's English README; it does not copy the project's official Chinese guide.
What OpenMAIC is, and who it is for
A classroom in OpenMAIC is a generated course: an outline, slide content, narration, and media, assembled by agents and presented as a lesson a learner can work through, ask questions about, and export. The project also has a Pro workbench, an agent that builds and edits courses conversationally, with durable sessions that can be resumed, follow-up instructions while a session runs, and a replayable event history. Courses, chat history, learner sessions and generated media live on the server, in PostgreSQL, so this is a server application, not a single static page.
It suits teachers, trainers and self-learners who want a structured lesson rather than a chat transcript, and who are comfortable running a Node.js server with a database. It is not a simple local chatbot, and it is not fully local by default: the model providers you configure may be hosted APIs, and only the local provider options keep model calls on your own machine. Read the provider section before assuming anything about where your prompts go.
Prerequisites
- For the source path: Node.js 22.19 or later, pnpm 10 or later, and PostgreSQL 16. For local development,
pnpm db:upstarts a PostgreSQL in Docker for you. - For the Docker path: Docker and Docker Compose, and API keys for the model providers you want to use.
- A model provider and key: the example configuration needs only an
OPENAI_API_KEYto start, but you can change its provider to one you already have a key for. Supported providers listed in the README include OpenAI, Anthropic, Google Gemini, DeepSeek, Qwen, Kimi, MiniMax, Grok, OpenRouter, Doubao, GLM and others, plus Ollama, Lemonade and FunASR as local options, and any OpenAI-compatible API. - A long-running server for real use: course generation runs inside the server and continues after the browser leaves the page. A laptop that sleeps will interrupt that work, so a small server suits anything beyond a first test.
Step 1: Install with Docker (recommended first path)
Copy the example environment file, edit it with your API keys, and start the stack:
cp .env.example .env.local
# Edit .env.local with your API keys, then:
docker compose up --buildOpen http://localhost:3000. The stack is two containers, the app and PostgreSQL. Courses, generated media and runtime sessions live in the named volumes openmaic-postgres and openmaic-data, which survive docker compose down and rebuilds; docker compose down -v deletes them, so do not use the -v flag unless you intend to delete your courses.
To configure models with openmaic.yml, create it from openmaic.example.yml and uncomment its mount in docker-compose.yml. Otherwise, connect a model service in the model settings once the app is running.
Important safety note from the README: the Compose file is a personal installation. It runs in single-user mode, where every browser sees one shared library, and it listens on 127.0.0.1:3000 only. To serve other machines, protect it first: set a long random ACCESS_CODE in .env.local, set PERSISTENCE_POSTGRES_PASSWORD to a random value before the first start, and publish on the network address with OPENMAIC_PUBLISH_ADDRESS=0.0.0.0 docker compose up -d --build. Without an access code, anyone who can reach the port owns, edits and can delete the whole library.
Step 2: Install from source (development path)
Clone, install, configure, start the database, and run:
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install
cp .env.example .env.local # API keys and server options
cp openmaic.example.yml openmaic.yml # which models the server uses
pnpm db:up
pnpm devAfter pnpm db:up, uncomment the local DATABASE_URL line in .env.local. The development database runs on 127.0.0.1:5432 by default. Then open http://localhost:3000 and start learning. Without a DATABASE_URL, the README says the server refuses to start and tells you how to provide one, which is a helpful failure rather than a silent one.
For production, build and keep the server running as a long-running process:
pnpm build && DATABASE_URL=postgres://localhost:5432/openmaic pnpm startCheck the project's deployment guide for the required configuration before treating a development run as a production deployment.
Step 3: Generate your first classroom
Pick a narrow topic you know well, so you can judge the result, and generate a short course rather than a long one. Check the outline first, then the slide content, then the narration and media. If a slide is wrong, edit it or regenerate that part rather than accepting the whole course at once; the workbench exists for exactly that kind of targeted edit, including importing .pptx slides with their layout preserved and exporting a classroom as a PPTX or as one offline HTML file.
If you want local models, configure Ollama as a provider, or the Lemonade local-AI and FunASR local-ASR options documented in the README, and turn off the hosted capabilities you do not want. The configuration file declares providers and gives each slot, such as the outline, slide content, text to speech and web search, a model, and the server validates the file at startup and names every mistake by its field.
Common problems and fixes
| Problem | Fix |
|---|---|
| The server refuses to start | Read the startup message: without a DATABASE_URL it exits and tells you how to provide one. For development, use pnpm db:up; for Docker, the Compose file sets it for you. |
| Model configuration errors at startup | The server validates openmaic.yml and names mistakes by field, or by line for broken YAML. Fix the named field rather than guessing. |
| Other people can edit your library | You exposed a single-user Compose install without an access code. Stop it, set a long random ACCESS_CODE, and read the hosting guide before publishing it again. |
| A Vercel deployment guide does not match | Serverless deployment is supported only up to version 1.1.x. From 1.2.0, OpenMAIC needs a long-running Node.js process with PostgreSQL, so use Docker or pnpm start instead. |
| Courses disappear after a rebuild | Check that you did not run docker compose down -v, which deletes the named volumes. A plain down keeps them. |
FAQ
Is OpenMAIC free? The code is MIT-licensed and free to run, but the models it calls usually are not: hosted providers charge for their API use, and even a local model needs hardware. Budget for provider costs separately from the software itself.
Can learners keep their own courses? Courses are stored per owner on the server, and the browser keeps only device-scoped values such as settings and playback position. Clearing the local cache never touches the server copy.
What if I only want local AI? Choose a local provider such as Ollama, Lemonade or FunASR, and check each slot in openmaic.yml: a slot left pointing at a hosted provider will still call that provider. Set a capability to null to turn it off, as the README's examples show for video.
Should I upgrade an old install casually? No. The README's release notes for recent versions include upgrade conditions, such as stopping all old instances first and no rollback below 1.3.0. Read the changelog for your version before upgrading.
Licence and attribution
OpenMAIC is licensed under MIT. In plain terms, and not as legal advice: you may use, copy, modify and distribute it, including commercially, provided you keep the copyright and licence notices with the code. That licence covers the OpenMAIC code; the models, voices, images and other generated media you use through it have their own providers and terms, so check those before publishing a generated course.
What to try next
Generate a short course on a topic you teach, export it, and show it to one learner. Their questions about the slides will tell you more about the classroom's quality than any feature list, and they will show you which agent role, outline, narration or media needs adjusting first.
This guide was checked against the official README and repository as of October 31, 2026. StackGuide AI did not run this tool for this guide, so this guide makes no claim based on running the tool; the commands below are the ones the official README publishes.