OpenMAIC

1. What is OpenMAIC?

OpenMAIC is open-source software from Tsinghua University (China) that turns a topic or a document into a whole interactive classroom. You type "teach me Excel" or upload a document, and the AI builds lesson pages, quizzes and interactive simulations, with AI "teachers" and "classmates" who talk, lecture aloud and draw on a whiteboard. Lessons can be exported as .pptx slides or .html pages.

The software is free (MIT license), but it has no AI brain of its own: you connect it to an AI model service (for example OpenAI, Anthropic, Google Gemini, DeepSeek…) with your own API key, and those services usually bill by usage. You can also connect a model running on your own machine (for example Ollama), which costs no service fees but needs a powerful computer.

OpenMAIC is built for people comfortable with Docker and the command line. For a beginner, the first setup takes roughly 30–60 minutes.

A good fit if:

• You are a teacher, student or self-learner who wants to try building lessons with AI.
• You already have (or are willing to create) an API key for an AI service and accept pay-per-use costs.
• You can install Docker and type a few commands.

Not a good fit if:

• You want something that works instantly with no install or API key. The README lists an online demo at https://open.maic.chat/ and a "hosted" mode that needs an access code from that site; look at it before deciding to install.
• You do not want to pay for an AI service and your computer cannot run a local model.

2. What do you need?

Item	Requirement
Computer	One that can run Docker (Windows, macOS or Linux)
Docker	Docker Desktop (Windows/macOS) from https://docs.docker.com/desktop/ , or Docker Engine on Linux from https://docs.docker.com/engine/install/
Git (optional)	To download the source with a command. Without Git, use Code > Download ZIP on https://github.com/THU-MAIC/OpenMAIC and unzip it
API key	At least one AI model service (OpenAI, Anthropic, Gemini, DeepSeek… or a local model). Most bill by usage

Running straight from source (without Docker) additionally needs Node.js 22.19 or newer, pnpm 10 or newer and PostgreSQL 16. This guide takes the Docker route because it is simpler: Docker handles the database too.

3. Step-by-step install

The commands below come from the "Docker Deployment" section of the official README. If you have never used a command line, see the "Never used a terminal?" box on the page.

Step 1: Get the source code

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC

Without Git, unzip the ZIP file and open Terminal/PowerShell inside the unzipped folder.

Step 2: Create the settings file

cp .env.example .env.local

On Windows PowerShell use copy .env.example .env.local. Open .env.local in a text editor and fill in the API key of the service you use on the matching line, for example OPENAI_API_KEY= for OpenAI. The README says the sample needs only OPENAI_API_KEY; if you use another provider, see the list in the README. You can also leave it blank and connect a model service in the app's model settings after it starts.

Note: an API key is a secret like a password. Do not post it online or send it to anyone.

Step 3: Run it

docker compose up --build

The first run builds the app and database, so it takes a while (a few minutes to over ten). The stack is two containers, the app and PostgreSQL; the app starts once the database reports healthy.

What you should see: lots of log lines, ending with the app running (keep this window open). Open http://localhost:3000 in your browser and the OpenMAIC interface appears.

By default the app listens only on your own machine (127.0.0.1:3000); other devices on your network cannot reach it. To open it to other machines the README says to set a long random ACCESS_CODE in .env.local first.

4. First use

1. Open http://localhost:3000.
2. If you did not enter an API key in Step 2, open the model settings in the app and connect your AI service.
3. Type a topic (for example "Introduction to Excel for beginners") or attach your own document, then start generating.
4. Wait while the AI builds the lesson. The result is a classroom of pages, quizzes and AI-made content. Try a short topic first to see how much usage it consumes before generating a large lesson.

The project can generate content in the language you use (the README mentions automatic language inference since v0.1.1), but quality in a given language depends on the model you connect. Test it before relying on it.

5. Common problems and fixes

Symptom	Cause	Fix
docker: command not found or docker compose not recognised	Docker not installed, or Docker Desktop not running	Install Docker per section 2 and start Docker Desktop before typing the command
git: command not found	Git not installed	Install Git from https://git-scm.com/downloads or use the ZIP download
http://localhost:3000 shows nothing	Containers still building, or port 3000 already used by another program	Wait until the log says the app is running; close whatever holds port 3000 (the README allows changing the port with OPENMAIC_PORT)
Generating fails with a model or key error	No API key, wrong key, or quota used up	Check the key in .env.local or the model settings; check your balance with the provider
Edited .env.local but nothing changed	The app reads settings only at startup	Stop it (Ctrl+C) and run docker compose up --build again
Cannot reach it from another machine	By default it is open only on the host	Follow the README's "Docker Deployment": set ACCESS_CODE and OPENMAIC_PUBLISH_ADDRESS

6. Uninstall / update

Stop. Press Ctrl+C in the running window, or run docker compose down in the OpenMAIC folder. According to the README, the lessons you created live in Docker volumes and survive docker compose down.

Delete all data. docker compose down -v also deletes the lessons you created. Use it only when you are sure you no longer need them.

Update. The project releases often and several recent releases are security fixes (see https://github.com/THU-MAIC/OpenMAIC/releases). Pull the new source (in the cloned folder: git pull), then run docker compose up --build again. Read the release notes first, because the README mentions changes in how it runs between versions.

7. FAQ

Does it cost money? The software is free, but the AI service you connect usually bills by usage. A model on your own machine has no service fee but needs a powerful computer.

Do I need internet? Yes, to download at install time and to call a cloud AI service if you use one.

Does my data go anywhere? Lessons are stored on the machine you set up. Text you enter or upload is sent to the AI provider you choose, so do not feed it sensitive documents without reading that provider's policy.

Will it run on a weak machine? With a cloud AI service the machine only needs to run Docker. The README gives no minimum RAM, so check the official site if you use an old computer.