# Prerequisites for Enabling the Pro Workbench and Durable Sessions in OpenMAIC

> Learn the essential prerequisites for OpenMAIC Pro workbench and durable sessions. Enable Pro features by setting NEXT_PUBLIC_PRO_WORKBENCH_ENABLED and configuring PostgreSQL.

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

---

**Setting `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true` and configuring a PostgreSQL backend with applied migrations are the mandatory prerequisites for activating the Pro workbench and enabling durable session persistence.**

The Pro workbench is a gated feature in OpenMAIC that exposes an agent-driven interface for advanced course building. Before the UI renders or durable sessions can persist user interactions, the application requires specific feature flags and database infrastructure. This guide details the exact configuration steps, source file locations, and environment variables required based on the OpenMAIC codebase.

## Feature Flag Configuration

### Enable the Pro Workbench Environment Variable

The primary gate for the Pro workbench is controlled by the `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED` environment variable. In [`lib/config/feature-flags.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts), the application reads this flag using the `readBoolean` utility function to determine whether the Pro UI components should mount.

Set the following in your `.env` file or deployment environment:

```dotenv

# .env

NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true
NEXT_PUBLIC_MAIC_EDITOR_ENABLED=true

```

The `readBoolean` function in [`lib/config/feature-flags.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts) parses the string value at runtime. If this variable is unset or set to `"false"`, the application will skip initialization of the Pro workbench routes and components.

### Ensure the MAIC Editor Gate is Active

According to the changes introduced in PR #1223, enabling the Pro workbench implicitly requires the MAIC Editor feature flag (`NEXT_PUBLIC_MAIC_EDITOR_ENABLED`) to be active. The Pro workbench depends on editor-specific APIs that are gated behind this secondary flag. Ensure both variables are set to `"true"` to prevent runtime dependency errors.

## Database and Storage Prerequisites

### Configure the PostgreSQL Backend

Durable sessions rely on a persistent storage backend to maintain session state across server restarts. The OpenMAIC storage layer, defined in `packages/@openmaic/storage/src/agent-session/types.ts`, uses PostgreSQL to store session metadata and message sequences. The `durableUserMessageSeq` type and related interfaces expect a connected SQL database to function correctly.

Configure your database connection:

```dotenv

# .env

DATABASE_URL=postgresql://user:password@localhost:5432/openmaic

```

Without this connection, the durable session features will fail to initialize, and the Pro workbench will be unable to persist user interactions.

### Run Database Migrations

The durable session storage requires specific tables, including the `agent_session` table referenced in the storage types. You must run the migration scripts to create these schemas before starting the application.

Execute the migration command:

```bash
npm run db:migrate

```

The migration files, referenced in test suites such as [`tests/store/stage-deletion-aggregate-recovery.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/store/stage-deletion-aggregate-recovery.test.ts), create the necessary tables for session persistence. Skipping this step results in query failures when the Pro workbench attempts to write durable session data.

## Verification and Testing

After configuring the environment variables and database, verify the setup using the test harness provided in [`tests/workbench/entry-gate.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/workbench/entry-gate.test.ts). This test file demonstrates how the application validates the `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED` flag at runtime.

You can manually verify the configuration in a Node.js environment:

```typescript
import { readBoolean } from '@/lib/config/feature-flags';

const isProEnabled = readBoolean(process.env.NEXT_PUBLIC_PRO_WORKBENCH_ENABLED);
console.log('Pro workbench active:', isProEnabled);

```

For durability verification, inspect the session store initialization:

```typescript
import { useSessionStore } from '@/store/session';
import { durableUserMessageSeq } from '@/lib/agent-runtime';

const session = useSessionStore.getState().createSession();
const message = session.appendUserMessage('Test message');
console.log('Durable sequence:', durableUserMessageSeq(message));

```

Successful execution confirms that the storage backend is accepting durable writes and that the feature flags are properly recognized by the runtime.

## Summary

- Set `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true` in your environment to unlock the Pro workbench UI.
- Ensure `NEXT_PUBLIC_MAIC_EDITOR_ENABLED=true` is set, as the Pro workbench depends on editor APIs introduced in PR #1223.
- Configure a PostgreSQL `DATABASE_URL` to provide the durable storage backend required by `packages/@openmaic/storage/src/agent-session/types.ts`.
- Execute `npm run db:migrate` to create the `agent_session` table and related schemas before starting the application.
- Verify functionality using the test patterns found in [`tests/workbench/entry-gate.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/workbench/entry-gate.test.ts).

## Frequently Asked Questions

### What happens if I enable the Pro workbench without running database migrations?

The application will fail to persist session data. The Pro workbench attempts to write to tables defined in `packages/@openmaic/storage/src/agent-session/types.ts`, which do not exist until migrations are applied. You will encounter SQL errors indicating missing relations when users attempt to save their work.

### Can I use a database other than PostgreSQL for durable sessions?

The current implementation in OpenMAIC specifically targets PostgreSQL for durable session storage, as evidenced by the SQL schema references and the `durableUserMessageSeq` implementations. While the storage abstraction layer may support other backends in the future, the codebase currently requires PostgreSQL for full durability guarantees.

### Where is the Pro workbench feature flag actually checked in the code?

The flag is evaluated in [`lib/config/feature-flags.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts) using the `readBoolean` function. This utility parses `process.env.NEXT_PUBLIC_PRO_WORKBENCH_ENABLED` and returns a boolean value that controls conditional rendering and API routing throughout the application, particularly in the workbench entry point tested by [`tests/workbench/entry-gate.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/workbench/entry-gate.test.ts).

### Is the MAIC Editor flag always required when enabling the Pro workbench?

Yes. As implemented in PR #1223, the Pro workbench functionality depends on components and utilities gated behind `NEXT_PUBLIC_MAIC_EDITOR_ENABLED`. Enabling only the Pro workbench flag without the editor flag will result in missing dependencies and UI rendering failures, since the workbench reuses the editor's core building blocks.