Agent Workbench Runtime Requirements: OpenMAIC Setup Guide

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

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

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:

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:

# 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 – React hook that opens Runtime Sessions, subscribes to record streams, and exposes session state to the UI
• 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 – Service orchestration for PostgreSQL and optional MinIO containers
• 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. 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 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.

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