Self-Host OpenMAIC: Turn Documents into an AI Classroom with Teachers and Classmates

A team lead asked me to review the onboarding pack for new hires: nearly 40 slides, three PDFs, a runbook dozens of pages long. Thorough material — yet two weeks later, new hires were still asking questions the slides already answered. Nobody finishes static documents.

Self-learning a new stack alone has the same problem: a chatbot answers instantly, but nobody questions you back, nobody discusses with you, and no exercise makes you do real work.

OpenMAIC exists for exactly that gap: an open-source, self-hostable multi-agent AI classroom that turns a topic or a document into an interactive lesson — an AI teacher, AI classmates, a whiteboard, quizzes, simulations, and project-based learning. This article shows how to self-host it.

What Is OpenMAIC? A Multi-Agent AI Classroom from Tsinghua MAIC

OpenMAIC — Open Multi-Agent Interactive Classroom — is an MIT-licensed open-source project from the MAIC lab at Tsinghua University. Source: github.com/THU-MAIC/OpenMAIC, demo: open.maic.chat. About 42,768 stars and 6,579 forks; latest release v1.4.1 came out on 6 November 2026.

Feed it a topic or a document and several AI agents become a classroom: the AI teacher lectures with slides and a whiteboard and asks check questions, AI classmates ask questions, raise different opinions, and discuss in real time, and learners discuss, take quizzes, and run simulations. PBL v3 lets an AI tutor guide the learner through requirements, design, and implementation.

It fits team leads and trainers running internal training, sysadmins and DevOps engineers turning runbooks into team lessons, developers self-learning a new stack, and homelab users. Distinguish OpenMAIC from DeepTutor, a 1-1 AI tutor over your own documents. DeepTutor is a private tutor: you ask, it answers from your documents. OpenMAIC is a multi-agent classroom with discussion, a teacher, and classmates. If you only need quick Q&A, a 1-1 tutor is enough and far lighter.

Architecture: Next.js, PostgreSQL, and the Provider/Slot Model

OpenMAIC runs on Next.js 16, React 19, TypeScript 5, and Tailwind CSS 4, with PostgreSQL 16 as its data store. Two ways to run it: Docker Compose, or dev from source with pnpm. Both need an LLM key — by default, just OPENAI_API_KEY.

The most interesting detail is openmaic.yml: it separates classroom orchestration from model selection, declaring providers and slots — each slot is one step, e.g. llm or course.outline — and assigning a specific model to each slot. Keys stay in .env.local, referenced as ${VAR}, so critical steps use a frontier model while secondary steps use a cheaper or local model.

A classroom here is a long-lived, stateful process, not a chatbot wrapped around slides. Sessions, learner progress, and edits persist in PostgreSQL, with background sync in v1.4.1. The knowledge base lets you upload documents and reference them with @; they are parsed once and reused. PBL v3 is opt-in and needs a sandbox provider and checkpoint storage. In my view, classroom quality depends on three things: the model per slot, durable sessions in Postgres, and the reverse proxy timeout.

flowchart TB
    A["User / Learner<br/>localhost:3000"] --> B["OpenMAIC App — Next.js 16<br/>Agent Workbench, Pro Mode, 24 skills<br/>Classroom UI: slides/whiteboard/quiz/simulation"]
    B --> C["Multi-agent Orchestrator<br/>AI teacher + AI classmates"]
    C --> D["openmaic.yml — Provider/Slot Router<br/>Slots: llm, course.outline...<br/>Model per step"]
    D --> E["LLM Providers<br/>OpenAI, Anthropic, Gemini, DeepSeek<br/>Ollama / Lemonade local, OpenAI-compatible"]
    E --> C
    C --> F["PostgreSQL 16<br/>Durable sessions, learner progress"]
    F --> B
    B --> G["Knowledge Base<br/>@ mention, parsed once"]
    G --> C
    C --> H["PBL v3 — opt-in<br/>Sandbox Provider + Checkpoint Storage"]
    H --> F
    B --> I["Export — outside the main learning flow<br/>PPTX / offline HTML<br/>MP4 via render service (video-export)"]

Data flow: the user submits a topic or document, the orchestrator calls a skill, the router picks a model per slot, the provider returns content, session and progress are written to Postgres, and the interface renders slides, whiteboard, and quizzes.

Self-Host OpenMAIC with Docker Compose

Prerequisites. Docker and Docker Compose installed. An LLM key: OpenAI by default, or another supported provider (Anthropic, Gemini, DeepSeek, OpenRouter, local Ollama, and more). Dev from source also needs Node.js 22.19+, pnpm 10+, and PostgreSQL 16 (pnpm db:up provides Postgres).

Option 1 — Docker Compose (recommended). This is the path with the fewest variables:

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
docker compose up --build

Then open http://localhost:3000. Two containers: app and PostgreSQL. Data lives in two named volumes, openmaic-postgres and openmaic-data, which survive docker compose down — only docker compose down -v deletes them. For access from another machine, set OPENMAIC_PUBLISH_ADDRESS=0.0.0.0.

Option 2 — Dev from source. To modify code or follow logs in detail:

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 dev runs the dev server; for production from source, use pnpm build && pnpm start.

Configuring .env.local and openmaic.yml. In .env.local, the default example only needs OPENAI_API_KEY; for another provider, change the provider in openmaic.yml. Keys always stay in .env.local, referenced as ${VAR} — never commit this file to Git. Check each slot’s model before your first classroom; in my view, assign a frontier model to course.outline and the main teaching steps.

Checks and common errors. Verify with docker compose ps — both app and Postgres containers must be running — then open http://localhost:3000 to see the classroom creation interface.

• Wrong provider key: the classroom reports a model call error — check .env.local and the provider in openmaic.yml, then restart the containers.
• Postgres not up yet: the app cannot connect — wait for Postgres to become healthy, or check docker compose logs postgres.
• Port 3000 busy: change the port mapping in the compose file or stop the app using the port.
• First Docker build slow or failing: it downloads many dependencies — check network and disk space, then run it again.
• Cannot open from another machine: check OPENMAIC_PUBLISH_ADDRESS=0.0.0.0 and that the firewall allows port 3000.

Create Your First AI Classroom

From a topic. Enter a topic such as “Docker basics for new operations staff”, pick a lecture, workshop, or vocational style, and let the system generate the outline, slides, and quiz. The AI teacher explains each section; AI classmates ask: “How is a container different from a virtual machine?”, “When should you use a volume?” Learners answer, discuss, then take the quiz.

From a document. If you already have material — a runbook, a process PDF, old slides — upload it to the knowledge base and reference it with @ when creating the classroom; it is parsed once and reused.

Inside the classroom. The AI teacher lectures, AI classmates ask questions and discuss, the whiteboard records key points, quizzes check understanding after each section, and simulations let learners operate directly. Agent Workbench and Pro Mode include 24 built-in skills. Try a small classroom with a real topic first, and read the AI-generated content carefully.

PBL v3 and Lesson Export

PBL v3 is project-based learning, added in v1.4.0: an AI tutor guides learners through requirements, design, and implementation.

PBL v3 is opt-in: you need a sandbox provider and checkpoint storage, then open /pbl-v3. Without those two, the feature will fail or lose learner progress.

Export: PPTX keeping every scene intact, or a single offline HTML file to share. One-click MP4 export needs a separate render service (profile video-export), not included in the default deployment.

docker compose --profile video-export up

Local AI and Cost Control

OpenMAIC supports local models via Ollama and Lemonade, local speech recognition via FunASR, and VoxCPM2 TTS. Cheap trial path: run a test classroom with a local model first, and only move to a paid API when it works well.

The slot strategy is the cost-control lever: a frontier model for the outline and teaching, a cheap or local model for secondary steps. But using a local or cheap model for every slot may degrade teaching and outline quality — I have not tested TTS or classroom quality with local models. The LLM key lives in .env.local, referenced as ${VAR} in openmaic.yml; never commit it, and for team deployments put it behind an authenticated reverse proxy.

Technical Assessment: Strengths, Weaknesses, Security, Operations

Strengths. Genuinely interactive multi-agent model, not a chatbot with slides attached. Flexible export: PPTX keeping scenes, offline HTML, MP4 when video is needed. Open providers: OpenAI, Anthropic, Gemini, DeepSeek, local Ollama, any OpenAI-compatible API. MIT license, active release pace — v1.4.1 released 6 November 2026.

Weaknesses. Classroom quality depends entirely on the model, prompts, and input documents — nothing guarantees the AI-generated content is technically or pedagogically correct. No verified performance or RAM/CPU figures; TTS quality is untested. Fast release pace, so pin to v1.4.1 exactly.

Security. Keys in .env.local, never committed. When publishing with OPENMAIC_PUBLISH_ADDRESS=0.0.0.0, put it behind an authenticated reverse proxy — never expose it directly to the internet.

Operations and upgrades. Upgrades from v1.3.x and v1.4.0 are one-way: stop all old instances before upgrading; the new release migrates the database and old instances exit on their own. Rollback is only possible by restoring the database. So pin the version in production and back up Postgres before every upgrade — via the openmaic-postgres volume or pg_dump.

Comparison with Alternatives

In my view, OpenMAIC does not replace an LMS or a 1-1 tutor — it fills the gap: interactive lessons instead of hand-authoring everything like an LMS, and more than a chatbot’s 1-1 Q&A.

Real-World Use Cases

Business and internal training. Onboarding new hires and standardizing operations knowledge: a team lead creates a classroom from an existing runbook; staff learn through discussion and quizzes.

Homelab. Run an AI classroom at home and try local models via Ollama or Lemonade before paying for an API — the cheapest way to evaluate OpenMAIC.

DevOps and IT admins. Turn runbooks, system documentation, and incident-response procedures into interactive lessons, so new staff learn by discussing their own team’s operations documents.

Teachers, trainers, and developers. Teach a new stack, and use PBL v3 so learners build a real project instead of just reading slides.

Conclusion: Who Should Self-Host, Who Should Not

Try it if you are a team lead, trainer, sysadmin, or DevOps engineer who needs interactive training from existing documents and already has an LLM key and a Docker host. Order: try the demo at open.maic.chat, deploy with Docker Compose, create a small classroom, then scale to the team.

Not yet if you only need quick Q&A over documents — a 1-1 tutor is enough. Not yet without a good LLM key, because classroom quality depends directly on the model. And do not use it for formal training until the content has been reviewed.

Lessons Learned

1. Choose Docker Compose first, dev-from-source second — fewest variables, and volumes keep data after docker compose down.
2. Assign models per slot in openmaic.yml — both quality and cost live there.
3. Treat classroom creation as a long-lived, stateful process in Postgres.
4. Pin the version and back up the database before every upgrade — upgrades are one-way, rollback only by database restore.
5. Do not open 0.0.0.0 and never commit .env.local — keys and classroom data need a reverse proxy and authentication.
6. Verify classroom quality with a real topic before using it for formal training.

Verification Scope

Checked on 6 November 2026 against the THU-MAIC/OpenMAIC README and GitHub API: MIT license, about 42,768 stars and 6,579 forks, v1.4.1 released 6 November 2026, Next.js 16 / PostgreSQL 16 stack, clone, pnpm, and Docker Compose commands, and the provider list. PBL v3, the whiteboard, PPTX/HTML/MP4 export, 24 built-in skills, Lemonade, and FunASR are as described in the documentation, not independently run. Not verified: classroom quality, TTS quality, RAM/CPU usage when self-hosting, and the first-time Docker build — I have not run it.

References

• OpenMAIC — GitHub: https://github.com/THU-MAIC/OpenMAIC
• OpenMAIC — online demo: https://open.maic.chat/
• OpenMAIC — v1.4.1 release: https://github.com/THU-MAIC/OpenMAIC/releases/tag/v1.4.1
• Self-host DeepTutor: AI tutor over your documents — phamnam.me: https://phamnam.me/posts/deeptutor-gia-su-ai-ca-nhan-hoa/