# Agent Workbench Runtime Requirements: OpenMAIC Setup Guide

> Discover the Agent Workbench runtime requirements for OpenMAIC setup. Learn about Node.js, Docker Compose, PostgreSQL, and essential environment variables to get started.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: getting-started
- Published: 2026-09-09

---

**To run the Agent Workbench runtime, you need Node.js 18 or higher, Docker Compose with PostgreSQL 13+, required environment variables (`OPENAI_API_KEY`, `POSTGRES_URL`), and the `@openmaic/*` monorepo packages installed via pnpm.**

The Agent Workbench provides the interactive foundation for OpenMAIC's Pro Mode, hosting AI-driven learning sessions through a React-based interface. Setting up this Agent Workbench runtime requires specific infrastructure components from the THU-MAIC/OpenMAIC repository, including containerized services and monorepo dependencies.

## Node.js Engine Requirements

The server-side code targets modern ECMAScript features only available in recent Node releases. According to the `engines.node` field in [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json), you must run **Node.js ≥ 18**. This powers the HTTP-based runtime store, the Next.js API routes, and Docker-based services documented in `packages/@openmaic/storage/docs/runtime-http-contract.md`.

## Database and Infrastructure Dependencies

### PostgreSQL 13+

The **RuntimeStore** persists learner sessions, records, and progress through a PostgreSQL backend. The `PgRuntimeStore` implementation in `packages/@openmaic/storage/server/reference.ts` handles all database operations, requiring PostgreSQL 13 or newer for full compatibility.

### Docker Compose Orchestration

The runtime spans multiple containers defined in [`docker-compose.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/docker-compose.yml), including the Next.js frontend, PostgreSQL database, and optional MinIO service. You need **Docker Compose ≥ 2** to orchestrate these services so the Workbench can communicate with the database and asset storage endpoints.

## Environment Variables Configuration

The runtime expects specific secrets and endpoints via environment variables, listed in the repository's `.env.example` file:

- **`OPENAI_API_KEY`** – Required for LLM-backed tools in the workbench
- **`POSTGRES_URL`** (or individual `POSTGRES_HOST`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DATABASE`) – Database connection string for the RuntimeStore
- **`ASSET_S3_BUCKET`** – Optional; enables S3-compatible storage instead of the PostgreSQL fallback for assets

The runtime code reads these via `process.env` at startup.

## Monorepo Package Requirements

The Workbench UI imports TypeScript libraries from the `@openmaic/*` namespace. The workspace layout defined in [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) includes:

- `@openmaic/workbench` – UI components and hooks
- `@openmaic/storage` – Runtime store client and server implementations
- `@openmaic/generation` – LLM integration utilities

Install all dependencies with `pnpm install` and build with `pnpm run build` before starting the workbench.

## Browser Compatibility

The frontend requires a **modern ES2022-compatible browser** (recent Chrome, Edge, or Firefox). The React 18 interface uses Zustand for state management and Web APIs including Web Speech and MediaRecorder, which the build process bundles with necessary polyfills.

## Optional: S3-Compatible Asset Storage

For production deployments, configure an S3-compatible service like MinIO by setting:

- `ASSET_S3_BUCKET`
- `ASSET_S3_ENDPOINT`
- `ASSET_S3_ACCESS_KEY`
- `ASSET_S3_SECRET_KEY`

The [`docker-compose.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/docker-compose.yml) includes a MinIO service ready for local development. When `ASSET_S3_BUCKET` is defined, the runtime automatically uses the S3 store for `POST /assets` calls instead of the database fallback.

## Quick Start: Launching the Agent Workbench

Initialize the complete stack using Docker Compose:

```bash

# 1️⃣ Install dependencies

pnpm install

# 2️⃣ Copy the example env and fill in your secrets

cp .env.example .env.local

# → edit .env.local: set OPENAI_API_KEY, POSTGRES_*, etc.

# 3️⃣ Bring up the containers

docker compose up -d   # starts Postgres, MinIO (if enabled), and the Next.js app

# 4️⃣ Launch the dev server (hot-reload)

pnpm dev

```

Initialize the runtime client programmatically as implemented in [`lib/workbench/use-workbench-session.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/use-workbench-session.ts):

```typescript
import { createRuntimeClient } from '@openmaic/storage/runtime/http';

const client = createRuntimeClient({
  baseUrl: process.env.NEXT_PUBLIC_RUNTIME_URL ?? '/runtime',
  // The client automatically picks up the API key from the cookie-based auth layer
});

// Create a new session (the workbench does this on first load)
const session = await client.createSession({
  runtimeDslVersion: '1.0.0',
  stageId: 'stage-1',
  learnerKey: 'user-123',
});

```

Persist learner records during active sessions:

```typescript
await client.appendRecord(session.sessionId, {
  seq: 1,
  ts: Date.now(),
  sceneId: 'scene-42',
  data: {
    type: 'answer',
    answer: 'The capital of France is Paris.',
  },
});

```

Configure S3-backed storage via environment variables:

```bash

# In .env.local

ASSET_S3_BUCKET=my-bucket
ASSET_S3_ENDPOINT=http://localhost:9000   # MinIO URL

ASSET_S3_ACCESS_KEY=minioadmin
ASSET_S3_SECRET_KEY=minioadmin

```

## Core Implementation Files

- **[`lib/workbench/use-workbench-session.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/use-workbench-session.ts)** – React hook that opens Runtime Sessions, subscribes to record streams, and exposes session state to the UI
- **[`lib/workbench/workspace-session-memory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/workspace-session-memory.ts)** – In-memory façade used by the client-side when the HTTP store isn't needed (e.g., in tests)
- **`packages/@openmaic/storage/server/reference.ts`** – Node.js HTTP handler implementing the RuntimeStore contract (creates sessions, appends records)
- **`packages/@openmaic/storage/docs/runtime-http-contract.md`** – Formal HTTP API specification that the Workbench UI depends on
- **[`docker-compose.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/docker-compose.yml)** – Service orchestration for PostgreSQL and optional MinIO containers
- **[`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml)** – Defines the monorepo layout ensuring all `@openmaic/*` packages are linked together

## Summary

- **Node.js 18+** is required for modern ECMAScript support in the runtime server
- **PostgreSQL 13+** provides durable storage for sessions and learner records via the RuntimeStore
- **Docker Compose ≥ 2** orchestrates the multi-container architecture including the database and optional object storage
- **Environment variables** (`OPENAI_API_KEY`, `POSTGRES_URL`) configure the runtime connections and API access
- **Monorepo packages** (`@openmaic/*`) must be installed with pnpm and built before running the workbench
- **Modern browsers** support the React 18 frontend with Web Speech and MediaRecorder APIs

## Frequently Asked Questions

### What Node.js version is required for the Agent Workbench runtime?

The Agent Workbench runtime requires **Node.js 18 or higher**, as specified in the `engines.node` field of [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json). This version supports the modern ECMAScript features used in the HTTP-based runtime store and Next.js API routes.

### Can I run the Agent Workbench without Docker?

While possible for development, production deployments require **Docker Compose** to orchestrate the PostgreSQL database and optional S3-compatible storage. The [`docker-compose.yml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/docker-compose.yml) file defines these essential services that the RuntimeStore depends on for session persistence and asset management.

### Which database does the Agent Workbench use to store learner sessions?

The workbench uses **PostgreSQL 13+** as the default backing store for the RuntimeStore. The implementation in `packages/@openmaic/storage/server/reference.ts` provides the `PgRuntimeStore` class that handles session creation, record appending, and learner progress tracking through SQL operations.

### How do I configure cloud storage for assets in the Agent Workbench?

Set the `ASSET_S3_BUCKET` environment variable along with `ASSET_S3_ENDPOINT`, `ASSET_S3_ACCESS_KEY`, and `ASSET_S3_SECRET_KEY`. When configured, the runtime automatically uses S3-compatible storage (like MinIO) instead of the PostgreSQL fallback for asset bytes.