Run an AI Multi-Agent Classroom on Your Laptop

// Before you start

What you need

Node.js version 20 or higher installed (nodejs.org)
pnpm version 10 or higher installed — run: npm install -g pnpm
An API key from at least one LLM provider (OpenAI, Anthropic, Google, etc.)
A terminal / command prompt you can type into
About 500 MB of free disk space for dependencies

Step 1 of 5

Clone the repo and install dependencies

5 min

This downloads the OpenMAIC source code to your computer and installs all the JavaScript packages it needs. The pnpm install step can take a few minutes depending on your internet speed — that is normal.

Terminal · mac

$ git clone https://github.com/THU-MAIC/OpenMAIC.git

$ cd OpenMAIC

$ pnpm install

What you should see

A long list of packages being downloaded, ending with something like 'Done in Xs'. No red error lines.

This might happen

Error saying pnpm is not found, or Node version is too old

Run 'node -v' to check your Node version — it must say v20 or higher. If pnpm is missing, run 'npm install -g pnpm' first, then retry.

Step 2 of 5

Create your config file from the example

1 min

The project ships with a sample config file called .env.example. This command copies it to .env.local, which is the file OpenMAIC actually reads. You will edit .env.local in the next step — do not skip this copy step first.

Terminal · mac

$ cp .env.example .env.local

What you should see

No output and no error — the command silently creates the file.

This might happen

On Windows Command Prompt, 'cp' is not recognised

Use PowerShell instead, or run: copy .env.example .env.local

Step 3 of 5

Add your LLM API key to .env.local

3 min

Open the file .env.local in any text editor (Notepad, TextEdit, VS Code — anything works). Find the line that matches your AI provider and paste your key after the equals sign. You only need ONE provider key to get started. For example, if you have an OpenAI key, find the line OPENAI_API_KEY= and change it to OPENAI_API_KEY=sk-your-key-here. Save the file when done.

Terminal · mac

$ # Example — replace with your real key before saving:

$ # OPENAI_API_KEY=sk-your-actual-key-here

$ #

$ # Other supported providers (pick one):

$ # ANTHROPIC_API_KEY=sk-ant-...

$ # GOOGLE_API_KEY=...

$ # OPENROUTER_API_KEY=sk-or-...

$ #

$ # Open the file with your text editor, e.g.:

$ notepad .env.local # Windows

$ open -e .env.local # macOS TextEdit

$ nano .env.local # Linux / macOS terminal

What you should see

The file opens, you paste your key, and save. No terminal output expected.

This might happen

The app starts but shows 'No provider configured' or generation fails immediately

Double-check .env.local — make sure there are no spaces around the = sign and the key has no extra quotes. It should look exactly like: OPENAI_API_KEY=sk-abc123

Step 4 of 5

Start the development server

2 min

This command compiles the app and starts a local web server. The first run may take 30–60 seconds while it builds everything. Once you see a localhost URL printed, the app is ready.

Terminal · mac

$ pnpm dev

What you should see

Lines ending with something like '▲ Next.js ready' and 'Local: http://localhost:3000'. The terminal stays open — that is correct.

This might happen

Port 3000 is already in use — you see an EADDRINUSE error

Stop whatever is using port 3000, or run: PORT=3001 pnpm dev — then open http://localhost:3001 instead.

Step 5 of 5

Open the classroom and generate your first lesson

5 min

Open your browser and go to http://localhost:3000. You will see the OpenMAIC interface. Type any topic — for example 'How does photosynthesis work?' — or upload a PDF or document. Click Generate. The multi-agent system will build a full interactive lesson with slides, quizzes, and simulations. Generation typically takes 1–3 minutes depending on your chosen model.

Terminal · mac

$ # No terminal command needed — open this URL in your browser:

$ http://localhost:3000

What you should see

The OpenMAIC web UI loads. After you submit a topic, you see a progress indicator while agents build the lesson, then a full classroom with slides and interactive elements.

This might happen

Generation starts but stalls or returns an API error

Check that your API key is valid and has credits. Also confirm the key is saved correctly in .env.local with no extra spaces. Restart the server after any .env.local change: press Ctrl+C then run pnpm dev again.

// Status

cooked. baked. worked.

A locally running AI classroom web app at http://localhost:3000 where you can type any topic and receive a full multi-agent interactive lesson with slides, quizzes, and simulations within a few minutes.

// the honest bit

The honest part

This is a TypeScript/Next.js project — the setup is straightforward but you are running a development server, not a polished desktop app. Lesson quality depends entirely on the LLM you connect; cheaper or smaller models produce noticeably weaker results. TTS (voice), image generation, and video features each need their own separate API keys configured in .env.local — they do not work out of the box with just an OpenAI key. The project is actively developed and the README changes frequently, so some config variable names may differ from what is shown here.