OpenMAIC 1.3: a self-hosted AI classroom where every upgrade is one way and the instance secret guards your keys

A topic goes in, a multi-agent classroom comes out

OpenMAIC, short for Open Multi-Agent Interactive Classroom, generates slides, quizzes, interactive simulations and project based learning activities from a topic or document. AI teachers and AI classmates deliver the lesson; they speak, draw on a whiteboard and discuss with the learner in real time. Classroom chat can be asked about any slide element, interactive or whiteboard drawing.

Since v1.3.0 every upload sits in its owner's knowledge base until deleted, organized in folders and parsed once for every conversation. The composer offers it through @, and the agent can read, search and organize it. Finished classrooms export as a PPTX that keeps every scene or as one offline HTML file that plays the lesson. The project was relicensed to MIT in v0.3.0, when its @openmaic/* SDKs also went to npm. A live demo runs at open.maic.chat.

Upgrades to 1.3.x cannot be rolled back casually

The two most recent releases both come with release conditions. For v1.3.0 you have to stop all old instances first, and there is no rollback below 1.3.0. For v1.3.1, published on 2026-11-02, you stop all 1.3.0 instances first, and rolling back needs a database restore. Earlier, v1.2.1 moved classroom chat permanently onto Pi, which requires a classroom model with tool calling.

The consequence is that an upgrade is a maintenance window, not a rolling deploy. If you run several instances against one database, they all go down together. Take a database backup before every upgrade, keep it until you are confident in the new version, and read the Breaking Changes on the GitHub release page and CHANGELOG.md each time, because the conditions differ from release to release.

Server-first since 1.2.0 rules out Vercel

Version 1.2.0 made server-first generation stable. Generation runs on the server and survives closed tabs and restarts, materials are parsed as soon as they are attached, and the web app and the API share one pipeline. The price is infrastructure: it needs PostgreSQL and a long-running server.

Vercel deployments stay on the 1.1.x line, so anyone on that platform cannot reach the knowledge base, export or 1.3 workbench changes without moving hosts. In .env.local, DATABASE_URL is required except under docker-compose.yml, which sets it for the bundled PostgreSQL. For local development, the package scripts start and stop a database container:

    "db:up": "docker compose -p openmaic-dev-db -f docker-compose.db.yml up -d --wait postgres",
    "db:down": "docker compose -p openmaic-dev-db -f docker-compose.db.yml stop postgres",

Models belong in openmaic.yml, and the old env variables are deprecated

Model configuration lives in openmaic.yml, copied from openmaic.example.yml, or in the model settings of the web app. The YAML file references provider keys as ${VAR} from the environment. It can set defaults, lock choices, and forbid users from supplying their own keys. By default the server reads openmaic.yml from the directory it starts in, which is the repository root, or /app in the Docker image. OPENMAIC_CONFIG points elsewhere, and when it is set the file must exist.

The file is read at startup only, so a change needs a restart. The provider variables in .env, server-providers.yml, DEFAULT_MODEL and MODEL_FALLBACK are the legacy setup: they still work while no openmaic.yml exists, and they are deprecated. Once you create openmaic.yml, stop relying on them. In v1.3.1 a single DeepSeek key covers chat, web search and web fetch.

Lose the instance secret and saved provider keys are unreadable

Provider keys saved through the web settings are encrypted with an instance secret. If you do not set one, OpenMAIC creates it on first start in data/instance-secret.key, inside the Docker data volume. Saved keys cannot be read without it, so it has to be backed up alongside the database.

Set it explicitly when you run more than one instance, when data/ does not survive a restart, or on a read only filesystem. The suggested way to generate one is:

openssl rand -base64 32

The server warns at startup when stored keys were sealed under a different secret. Instances that share a database also share one persistent data directory, data/ or /app/data in the image. Restoring the database without the matching secret leaves users re-entering every key they saved.

Docker publishes on loopback because one owner serves every request

The bundled docker-compose.yml binds the app to loopback by default. The reason is in the defaults file: a single user owner serves one course library to every request, so anyone who can reach the port shares, edits and can delete that library. To publish on the network, set ACCESS_CODE in .env.local, which the compose file strongly recommends, and start with OPENMAIC_PUBLISH_ADDRESS=0.0.0.0 or a specific interface address. Access code tokens expire since v1.0.3.

Feature switches behave differently from runtime settings. NEXT_PUBLIC_* values such as NEXT_PUBLIC_PRO_WORKBENCH_ENABLED or NEXT_PUBLIC_ENABLE_VIDEO_EXPORT are compiled into the browser bundle at build time, and env_file does not feed build args. Changing one of them means rebuilding the image, not restarting the container.

A heavy build: Node 22.19, native libraries and many workspace packages

The root package.json declares engines node >=22.19.0. A postinstall hook runs build:packages, which builds mathml2omml, pptxgenjs and the @openmaic dsl, geometry, generation, storage, importer, renderer and editor packages in sequence, then syncs the importer and interactive assets. A plain install therefore compiles a lot before the app starts.

The Dockerfile starts from node:22-alpine, activates [email protected] through corepack, and installs python3, build-base, g++, cairo-dev, pango-dev, jpeg-dev, giflib-dev and librsvg-dev as native build tools for sharp and @napi-rs/canvas. ALPINE_MIRROR and NPM_REGISTRY build args let you point both package sources at a mirror, which matters on networks where the default registries are slow or blocked.

A run of security fixes since 1.0

OpenMAIC has shipped several security releases in a short span. v1.0.2 fixed SSRF and DNS rebinding issues plus a classroom overwrite bug. v1.0.3 added expiring access code tokens, a render service network policy, pinned audio connections and a Next.js RCE patch. v1.1.1 hardened MinerU Cloud parsing under GHSA-cpjc-vgjh-c5jp, and v1.1.2 made provider requests connect only to validated addresses and refuse redirects under GHSA-g87c-cm4q-cw5x.

The fixes matter because the app fetches remote content on the server: provider calls, document parsing and, since v1.2.1, web search and web fetch through Kimi, DeepSeek or Firecrawl. An instance left on an old version keeps those holes open, yet the one way upgrades above make staying current a planned task. The last push was on 2026-11-02.

Editorial conclusion

OpenMAIC fits teams that can run a long-lived Node server with PostgreSQL and want to generate interactive lessons with their own model providers. It is a poor fit for a quick Vercel deploy past 1.1.x, or for operators who need to roll back freely, since 1.3.0 and 1.3.1 both carry release conditions that block easy downgrades. Before upgrading or exposing an instance, read the release's Breaking Changes, back up the database together with the instance secret, and set ACCESS_CODE before binding to anything other than loopback.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes