How to Self-Host OpenMAIC: A Complete Deployment Guide

To self-host OpenMAIC, clone the THU-MAIC/OpenMAIC repository, configure your LLM API keys in .env.local, and run docker compose up --build to launch the Next.js application server with optional PostgreSQL persistence and MP4 rendering services.

OpenMAIC is an open-source AI-powered course generation platform built with Next.js. Deploying your own instance of the THU-MAIC/OpenMAIC repository gives you full control over data privacy, model selection, and feature enablement. This guide covers deploying everything from a lightweight browser-only setup to a full-featured deployment with database persistence and video export capabilities.

Prerequisites

Before self-hosting OpenMAIC, ensure your environment meets the following requirements:

• Node.js: Version 22 or higher
• Package manager: pnpm 10 or higher
• Docker and Docker Compose: Required for containerized deployment with optional services
• LLM API access: At least one provider key (OpenAI, Anthropic, or compatible)

The repository uses a monorepo structure with workspace packages including @openmaic/generation and @openmaic/storage that power the generation pipeline.

Step-by-Step Self-Hosting Instructions

Clone the Repository and Install Dependencies

Start by cloning the repository and installing the workspace dependencies:

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

The pnpm install command pulls in all workspace packages located in the packages/ directory, including the storage abstraction layer and generation logic found in packages/@openmaic/storage/ and related modules.

Configure Environment Variables

Copy the example environment file and configure your settings:

cp .env.example .env.local

Edit .env.local to include at minimum one LLM provider key. The file supports extensive configuration options defined in .env.example:

# Required: LLM provider authentication

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxx

# Optional: Enable Pro workbench features

NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true
OPENMAIC_AGENT_RUNTIME_ENABLED=true
DATABASE_URL=postgres://openmaic:openmaic-dev@postgres:5432/openmaic
PERSISTENCE_DEV_TOKEN=openmaic-local-dev

# Optional: Enable MP4 video export

NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true
RENDER_SERVICE_URL=http://render-service:9000

Environment variables prefixed with NEXT_PUBLIC_* are embedded at build time and control UI feature visibility, while server-only variables like DATABASE_URL configure the backend persistence layer.

Launch with Docker Compose

The docker-compose.yml file defines three service tiers controlled via Docker profiles:

Basic deployment (browser-only storage):

docker compose up --build

With PostgreSQL persistence:

docker compose --profile server-persistence up --build

Full deployment (PostgreSQL + MP4 rendering):

docker compose --profile server-persistence --profile video-export up --build

The application container exposes port 3000 and mounts the openmaic-data volume for persistent storage. When using the server-persistence profile, the PostgreSQL service stores durable documents, runtime state, and agent sessions in the openmaic-postgres volume.

Optional Components and Advanced Configuration

Enable PostgreSQL Persistence

To enable durable storage for documents and agent sessions, you must configure the PostgreSQL backend through docker-compose.yml. Set the following in .env.local:

• DATABASE_URL: Connection string pointing to the postgres service
• PERSISTENCE_DEV_TOKEN: Authentication token for the persistence API

The storage abstraction layer in packages/@openmaic/storage/ handles the connection, allowing the application to swap between browser storage, PostgreSQL, or S3 backends without code changes.

Configure the Pro Workbench and Agent Runtime

The Pro workbench adds a chat-first agent capable of planning and revising courses. To enable this feature:

1. Set NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true (build-time flag)
2. Enable the runtime: OPENMAIC_AGENT_RUNTIME_ENABLED=true
3. Configure the model routing in MODEL_ROUTES:

MODEL_ROUTES='{"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'

The agent runtime implementation in lib/server/agent-runtime/ validates these routes at startup. If MODEL_ROUTES is missing or invalid, the /api/agent/* endpoints return 404 and the workbench remains disabled.

Set Up the MP4 Render Service

The render service runs in an isolated network and converts exported classrooms into MP4 video using Chromium and FFmpeg. Enable it by:

1. Adding the video-export profile to your docker compose command
2. Setting NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true in .env.local
3. Configuring RENDER_SERVICE_URL=http://render-service:9000

The service defined in render-service/ operates on an internal render network with egress locked down by iptables, ensuring secure video processing without external internet access.

Verifying Your Deployment

After the containers start, access the application at http://localhost:3000. If you configured ACCESS_CODE in .env.local, the landing page requires this password before granting access.

Test the persistence endpoint with:

curl -X POST http://localhost:3000/api/persistence/documents \
  -H "Authorization: Bearer openmaic-local-dev" \
  -d '{"id":"test-doc","content":"Hello world"}' \
  -H "Content-Type: application/json"

A successful response confirms that the storage layer in packages/@openmaic/storage/ is properly connected to PostgreSQL (or browser storage if the database is not configured).

Summary

• Core application: The Next.js app in app/ and lib/ serves the UI and API routes on port 3000
• Database option: PostgreSQL provides durable storage for documents and agent sessions when using the server-persistence profile
• Video export: The optional render service in render-service/ requires the video-export profile and isolated network configuration
• Environment configuration: .env.local controls feature flags, LLM routing, and authentication tokens
• Agent features: The Pro workbench requires specific MODEL_ROUTES configuration and the agent runtime enabled in lib/server/agent-runtime/

Frequently Asked Questions

What are the minimum system requirements for self-hosting OpenMAIC?

The basic application requires Node.js 22+ and pnpm 10+ for development builds, or Docker for containerized deployment. For full functionality including the Pro workbench, you need approximately 2GB RAM for the Node.js application plus 1GB for PostgreSQL. The MP4 render service requires significant additional resources (4GB+ RAM) due to Chromium and FFmpeg processing.

Can I run OpenMAIC without Docker?

Yes, you can run the Next.js application directly using pnpm install followed by pnpm dev or pnpm build and pnpm start. However, without Docker you lose the managed PostgreSQL and render service containers. You would need to manually install and configure PostgreSQL, and the MP4 export feature would be unavailable unless you separately deploy the render-service/ container.

How do I enable the Pro workbench features?

Enable the Pro workbench by setting NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true and OPENMAIC_AGENT_RUNTIME_ENABLED=true in .env.local. You must also provide a DATABASE_URL for persistent agent sessions and configure MODEL_ROUTES to specify which LLM handles the maic-agent-driver stage. The runtime code in lib/server/agent-runtime/ validates this configuration at startup.

Is the MP4 render service required for basic course generation?

No, the render service is optional. Basic course generation and editing work entirely within the browser or with the core application server. The render service only enables the "Export Video" feature that converts classrooms into downloadable MP4 files. If you don't need video export capabilities, you can omit the video-export profile and save significant system resources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}