Prerequisites for Enabling the Pro Workbench and Durable Sessions in OpenMAIC

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

# .env

NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true
NEXT_PUBLIC_MAIC_EDITOR_ENABLED=true

The readBoolean function in 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:

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

npm run db:migrate

The migration files, referenced in test suites such as 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. 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:

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:

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.

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 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.

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.

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