Read the whole setupGet the setup that works.
Drop your email and unlock the rest: what you need, the install, the four settings with my values, the course-building workflow, and the two ways it drifts.
One email. No follow-up unless I ship something that fits.
WHAT YOU NEED- Node.js 22.19 or newer if running from source
- pnpm, the package manager the repo is built on
- An API key from at least one model provider: OpenAI, Anthropic, Azure OpenAI or Bedrock
- Docker, only if you want the self-hosted Postgres stack instead of Vercel
INSTALLVercel for a quick look, Docker to keep it
The one-click Vercel deploy is the fastest way to see it working. For anything you plan to keep running, clone it and use the Docker Compose stack, which gives you the persistent Postgres backend the Vercel path skips.
The install
terminalcloned repo
$ git clone https://github.com/THU-MAIC/OpenMAIC.git $ cd OpenMAIC && pnpm install $ docker compose up --build → app on :3000, Postgres persistence included
First build compiles the mathml2omml and pptxgenjs packages, which takes a few minutes. That is normal, not a hang.
Prove itOpen localhost:3000, add your model key in Settings, and type a one-line topic. A generated slide deck within a minute or two means the provider connection is live.
CONFIGUREThe env vars that decide what runs
.env.local is where every provider key and feature flag lives. Most of the file is optional; these are the ones that change what you actually get.
.env.localmy values
OPENAI_API_KEY=sk-... NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true NEXT_PUBLIC_ENABLE_PPTX_IMPORT=true NEXT_PUBLIC_PERSISTENCE=postgres
| Setting | Default | Why I change it |
|---|
| ENABLE_VIDEO_EXPORT | false | Off by default because it needs the video-export Docker profile. Worth turning on once you have watched it run once. |
| ENABLE_PPTX_IMPORT | false | Most course material starts life as a deck. Turning this on is the difference between retyping content and importing it. |
| PERSISTENCE | memory | Memory-only loses every course on restart. Postgres is one flag away if you used the Docker stack. |
Provider neutralNothing is hardcoded to one model vendor. Swap OPENAI_API_KEY for ANTHROPIC_API_KEY and the same workbench runs on Claude instead, no code change.
DAILY DRIVINGMaterials in, then steer
The one-click generator is fine for a quick draft. The agent workbench is the mode worth learning: it holds a session open so you can keep revising instead of starting over.
- Upload first. Documents, audio or video, or a web search the agent runs itself. The course is only as specific as what you feed it.
- One prompt to start. State the audience and the outcome, not just the topic. The agent plans a curriculum from that.
- Revise in the session. Sessions are durable and server-backed. Cancel, come back tomorrow, and resume exactly where the course was.
A course built from an uploaded slide deck and two policy documents comes out closer to what you meant than one built from a single-sentence topic.
WHEN IT DRIFTSTwo failures, both configuration
PPTX import silently fails
NEXT_PUBLIC_ENABLE_PPTX_IMPORT is still false, or the importer sanitization added in v1.0.1 rejected the filename. Rename the file without special characters and retry.
Video export never finishes
The video-export Docker profile is not running. Start it with docker compose --profile video-export up --build rather than the default compose command.
On v1.0.0 stillUpgrade to v1.0.1 before anything else. It patches four disclosed advisories and tightens two defaults the changelog names directly.
THE SHAPE OF ITWhere everything lives
.env.localevery provider key and feature flag app/the Next.js workbench and generator UI packages/generation/the course-building agent logic packages/importer/PPTX and document parsing render-service/the standalone video and slide renderer
A course lives in whichever persistence backend you set. Postgres means it survives a redeploy; memory mode does not.
That is the whole setupOne prompt, an agent that plans and revises, twenty skills already built in. The next course you need to teach starts as a document you already have, not a blank slide deck.
Open on GitHub →
↑ Unlocks the moment you submit the form above.
