How to Set Up OpenMAIC Locally for Development: Complete Setup Guide

You can set up OpenMAIC locally by installing Node.js ≥20 and pnpm ≥10, cloning the THU-MAIC/OpenMAIC repository, running pnpm install, configuring your .env.local file with at least one LLM provider key, and starting the development server with pnpm dev on port 3000.

OpenMAIC is a Next.js-based multi-agent learning platform that generates interactive educational content through AI-powered pipelines. This guide walks through the exact steps to configure the THU-MAIC/OpenMAIC repository for local development, including optional features like the Pro workbench and PostgreSQL persistence.

Prerequisites for OpenMAIC Local Development

Before cloning the repository, verify your system meets the baseline requirements defined in the package.json and README:

• Node.js ≥ 20
• pnpm ≥ 10

These versions ensure compatibility with the Next.js App Router and the modern React components used in the frontend layer.

Clone the Repository and Install Dependencies

Execute the following commands to download the source code and install all required packages:

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

This process installs the Next.js framework, React dependencies, and the LangGraph orchestration libraries located in lib/orchestration/.

Configure Environment Variables for Local Development

OpenMAIC requires API keys for external AI providers (LLM, TTS, ASR, image/video generation) which are read from .env.local. Copy the template and configure your credentials:

cp .env.example .env.local

Edit .env.local to include at least one provider key and set the default model:

OPENAI_API_KEY=sk-...
DEFAULT_MODEL=openai:gpt-5.5

The provider-neutral adapters in lib/ai/ and lib/audio/ automatically route requests based on these environment variables. For production deployments, you can optionally use server-providers.yml instead of .env.local.

Start the OpenMAIC Development Server

Launch the local development server with hot-reloading enabled:

pnpm dev

The application will be available at http://localhost:3000. To run on a custom port:

PORT=4000 pnpm dev

This starts the Next.js frontend layer (app/page.tsx) and initializes the generation pipeline (lib/generation/) that creates course outlines and expands them into interactive scenes.

Optional: Enable Advanced OpenMAIC Features

Pro Workbench and Agent Runtime

The Pro workbench adds a chat-first agent that can plan, build, and revise courses using durable sessions stored in PostgreSQL. Enable these features by adding the following to .env.local:

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

The durable agent runtime is implemented in lib/server/agent-runtime/ and powers the collaborative course-building interface.

Server-Backed Persistence with PostgreSQL

To persist data beyond browser storage, configure PostgreSQL persistence:

NEXT_PUBLIC_PERSISTENCE=1
DATABASE_URL=postgres://user:password@localhost:5432/openmaic

The persistence layer in lib/persistence/ provides swappable storage backends including browser storage, PostgreSQL, and S3.

Docker Deployment for Local Development

For containerized local development, use the provided Dockerfile and Docker Compose configuration:

docker compose up --build

To include the render service for MP4 video export:

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

Understanding the OpenMAIC Architecture

The codebase is organized into three distinct layers that interact during development:

• Frontend / UI (app/): Contains React components including app/page.tsx (the generation entry point), workbench interfaces, and interactive scenes using the Next.js App Router.
• Business Logic (lib/): Houses the generation pipeline (lib/generation/) that implements the two-stage outline-to-scene expansion, plus LangGraph orchestration in lib/orchestration/ for multi-agent conversations.
• Persistence / Runtime (lib/persistence/ and lib/server/agent-runtime/): Manages storage abstractions and the durable runtime that powers the Pro workbench, with authentication logic in lib/persistence/server-auth.ts.

Key configuration files include next.config.ts for Next.js settings and package.json for build scripts and dependencies.

Summary

• Install Node.js ≥20 and pnpm ≥10 before cloning the THU-MAIC/OpenMAIC repository.
• Use pnpm install to fetch dependencies for the Next.js frontend and generation pipeline.
• Configure .env.local with at least one LLM provider API key and set DEFAULT_MODEL to enable AI generation capabilities.
• Run pnpm dev to start local development on localhost:3000, or specify a custom PORT.
• Enable Pro workbench by setting NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true and providing a DATABASE_URL for PostgreSQL-backed agent sessions.
• Use Docker Compose with optional profiles like video-export for containerized development environments.

Frequently Asked Questions

What are the minimum environment variables required to run OpenMAIC locally?

You need at least one LLM provider API key (such as OPENAI_API_KEY) and a DEFAULT_MODEL value (for example, openai:gpt-5.5) defined in .env.local. These credentials enable the generation pipeline in lib/generation/ to create course outlines and scenes.

How do I enable the Pro workbench for collaborative course building?

Set NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true and OPENMAIC_AGENT_RUNTIME_ENABLED=true in your .env.local file, plus provide a DATABASE_URL pointing to a PostgreSQL instance. This activates the durable agent runtime in lib/server/agent-runtime/ that stores session data and enables persistent chat-based course editing.

Can I run OpenMAIC without setting up PostgreSQL?

Yes. By default, OpenMAIC uses browser-based storage when NEXT_PUBLIC_PERSISTENCE is unset or set to browser mode. PostgreSQL is only required if you enable the Pro workbench or set NEXT_PUBLIC_PERSISTENCE=1 for server-backed storage.

What Node.js version is required for OpenMAIC development?

The repository requires Node.js version 20 or higher and pnpm version 10 or higher. These versions are necessary to support the modern ES modules and React Server Components used throughout the app/ directory and lib/ business logic layers.

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