# How to Self-Host OpenMAIC: A Complete Deployment Guide

> Learn to self-host OpenMAIC by cloning the THU-MAIC/OpenMAIC repo, configuring API keys, and running docker compose up. Deploy your AI instance easily today.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-10

---

**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](https://github.com/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:

```bash
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:

```bash
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`:

```env

# 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/docker-compose.yml) file defines three service tiers controlled via Docker profiles:

**Basic deployment** (browser-only storage):

```bash
docker compose up --build

```

**With PostgreSQL persistence**:

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

```

**Full deployment** (PostgreSQL + MP4 rendering):

```bash
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`:

```env
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:

```bash
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.