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

> Set up OpenMAIC locally for development. Follow this guide to install Nodejs and pnpm, clone the repository, and configure your env file to start the dev server.

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

---

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

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

```bash
cp .env.example .env.local

```

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

```env
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/server-providers.yml) instead of `.env.local`.

## Start the OpenMAIC Development Server

Launch the local development server with hot-reloading enabled:

```bash
pnpm dev

```

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

```bash
PORT=4000 pnpm dev

```

This starts the Next.js frontend layer ([`app/page.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`:

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

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

```bash
docker compose up --build

```

To include the render service for MP4 video export:

```bash
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/server-auth.ts).

Key configuration files include [`next.config.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/next.config.ts) for Next.js settings and [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.