# How to Set Up OpenMAIC Project Locally: Complete Installation Guide

> Learn how to set up the OpenMAIC project locally with this complete installation guide. Clone the repo, install dependencies, configure env vars, and run pnpm dev to get started.

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

---

**Clone the repository, install dependencies with pnpm, configure environment variables from `.env.example`, and run `pnpm dev` to start the Next.js 16 application on `http://localhost:3000`.**

OpenMAIC is a modern, multi-agent learning platform built on **Next.js 16** and **React 19** using TypeScript. This guide walks you through the local setup process using the official source code from `THU-MAIC/OpenMAIC`, covering everything from basic installation to optional advanced features like PostgreSQL persistence and the Pro workbench.

## Prerequisites

Before installing OpenMAIC locally, ensure your environment meets the minimum requirements:

- **Node.js** ≥ 20
- **pnpm** ≥ 10

These version constraints are enforced by the project's package manager configuration and build scripts.

## Clone and Install Dependencies

Start by cloning the repository and installing the required packages:

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

```

The project uses pnpm workspaces to manage dependencies across the main application and sub-packages like `@openmaic/storage` located in `packages/@openmaic/storage/`.

## Configure Environment Variables

OpenMAIC requires environment variables to connect to LLM providers and configure runtime behavior:

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

```

Edit `.env.local` and add at least one API key for your preferred LLM provider:

```bash

# Required for generation and orchestration features

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

```

The `.env.example` file in the repository root serves as the template for all supported variables, including optional settings for local AI backends and database connections.

## Run the Development Server

Start the local development server with:

```bash
pnpm dev

```

This command launches the Next.js application on `http://localhost:3000`. The entry point for the home page is located at [`app/page.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/page.tsx), which renders the workspace UI where users submit generation prompts.

## Optional Advanced Features

### Enable PostgreSQL Persistence

By default, OpenMAIC uses browser-based storage. To enable durable server-side persistence using PostgreSQL, set the following environment variables:

```bash
echo "DATABASE_URL=postgres://openmaic:openmaic-dev@postgres:5432/openmaic" >> .env.local
echo "NEXT_PUBLIC_PERSISTENCE=1" >> .env.local

```

Then launch the Docker Compose profile that includes the PostgreSQL service:

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

```

The `@openmaic/storage` package in `packages/@openmaic/storage/` manages the swappable persistence layer, which switches between browser IndexedDB, HTTP, PostgreSQL, and S3 backends based on the `NEXT_PUBLIC_PERSISTENCE` flag.

### Activate the Pro Workbench

The Pro workbench provides advanced multi-agent orchestration features through a dedicated UI. Enable it by setting:

```bash
echo "NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true" >> .env.local
echo "OPENMAIC_AGENT_RUNTIME_ENABLED=true" >> .env.local
pnpm dev

```

The workbench components are located in `components/workbench/` and interface with the durable agent runtime in `lib/server/agent-runtime/`.

## Understanding the Architecture

OpenMAIC follows a three-layer architecture that becomes relevant when extending your local setup:

- **Presentation Layer**: Next.js App Router handles UI rendering in [`app/page.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/page.tsx) and classroom playback views.
- **Core Business Logic**: The `lib/` directory contains the two-stage lesson generation pipeline (`lib/generation/`), LangGraph-driven multi-agent orchestration (`lib/orchestration/`), and the agent runtime (`lib/server/agent-runtime/`).
- **Persistence Layer**: The storage abstraction in `packages/@openmaic/storage/` enables the build-time switching of data backends.

Configuration changes in [`next.config.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/next.config.ts) control build-time optimizations and Vercel integration settings, while [`docker-compose.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/docker-compose.yml) defines the containerized development environment.

## Summary

- **Prerequisites**: Install Node.js ≥ 20 and pnpm ≥ 10 before starting.
- **Installation**: Clone the repository and run `pnpm install` to set up the workspace.
- **Configuration**: Copy `.env.example` to `.env.local` and configure at least one LLM API key.
- **Development**: Run `pnpm dev` to start the application on `localhost:3000`.
- **Persistence**: Enable PostgreSQL by setting `NEXT_PUBLIC_PERSISTENCE=1` and using Docker Compose.
- **Pro Features**: Activate the workbench with `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true`.

## Frequently Asked Questions

### What Node.js version does OpenMAIC require?

OpenMAIC requires Node.js version 20 or higher. This requirement is specified in the project documentation and enforced by the build system to ensure compatibility with Next.js 16 and React 19 features.

### Can I use npm or yarn instead of pnpm?

No, OpenMAIC requires pnpm version 10 or higher. The project uses pnpm workspaces to manage the monorepo structure, including the `@openmaic/storage` package and other internal dependencies. Using npm or yarn will not correctly resolve workspace dependencies.

### How do I switch between storage backends?

Set the `NEXT_PUBLIC_PERSISTENCE` environment variable in `.env.local` to control the storage layer. Value `0` uses browser IndexedDB, while `1` enables PostgreSQL persistence. For PostgreSQL, you must also provide a valid `DATABASE_URL` and run the Docker Compose server persistence profile.

### Is the Pro workbench available in the default installation?

No, the Pro workbench is disabled by default. You must explicitly enable it by setting `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true` and `OPENMAIC_AGENT_RUNTIME_ENABLED=true` in your environment configuration before starting the development server.