How to Set Up OpenMAIC Project Locally: Complete Installation Guide

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:

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:

cp .env.example .env.local

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

# 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:

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, 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:

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:

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:

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 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 control build-time optimizations and Vercel integration settings, while 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.

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