How to Enable the Pro Workbench in OpenMAIC: Complete Configuration Guide

To enable the Pro workbench in OpenMAIC, you must set the public feature flag NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true alongside the agent runtime variables OPENMAIC_AGENT_RUNTIME_ENABLED=true and a valid DATABASE_URL, then restart your development server.

The Pro workbench in OpenMAIC provides a chat-first course building interface that requires both client-side feature flags and server-side agent runtime configuration. According to the OpenMAIC source code, this premium interface is gated by a dual-layer security model that prevents accidental exposure without proper infrastructure backing.

Prerequisites for Enabling the Pro Workbench

Before accessing the Pro workbench, your environment must satisfy two distinct runtime conditions enforced by the configuration layer in lib/config/feature-flags.ts:

• Public Feature Flag: The NEXT_PUBLIC_PRO_WORKBENCH_ENABLED environment variable must be set to true. The function isProWorkbenchEnabled() checks this value to determine whether to render the Pro workbench UI components.

• Agent Runtime Configuration: The server-side agent must be active. The isAgentRuntimeConfigured() function validates that OPENMAIC_AGENT_RUNTIME_ENABLED is true and that DATABASE_URL contains a non-empty PostgreSQL connection string. This ensures the background agent can drive the conversational course-building experience.

Additionally, middleware.ts (lines 54-57) implements a route guard that returns a 404 Not Found if either condition is false when requesting /workbench.

Step-by-Step Configuration

Follow these steps to properly enable the Pro workbench in your local or production environment.

Configure Environment Variables

Create your local environment file from the provided example and enable the required flags:

cp .env.example .env.local

Edit .env.local to include the following configuration (referencing lines 107-111 of .env.example):

# Public flag – enables the Pro workbench UI

NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true

# Agent runtime (required for the Pro workbench)

OPENMAIC_AGENT_RUNTIME_ENABLED=true
DATABASE_URL=postgres://openmaic:password@localhost:5432/openmaic

You can automate this configuration using sed:

sed -i '' 's/^# NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=.*/NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true/' .env.local

sed -i '' 's/^# OPENMAIC_AGENT_RUNTIME_ENABLED=.*/OPENMAIC_AGENT_RUNTIME_ENABLED=true/' .env.local

sed -i '' 's|^# DATABASE_URL=.*|DATABASE_URL=postgres://openmaic:pwd@localhost:5432/openmaic|' .env.local

Restart the Development Server

Environment variables in Next.js are evaluated at build time. Restart your development server to load the new configuration:

pnpm dev

Verify Access to the Workbench

Navigate to http://localhost:3000/workbench. If configured correctly, the Pro-mode UI loads via the transition handler in lib/workbench/pro-swap.ts. If you encounter a 404, verify that both the public flag and agent runtime variables are properly set, as the middleware.ts guard strictly enforces these requirements.

How the Pro Workbench Toggle Works

The OpenMAIC codebase implements a robust gating mechanism to ensure the Pro workbench only appears when fully supported.

In lib/config/feature-flags.ts, the isProWorkbenchEnabled() function (lines 32-34) parses the NEXT_PUBLIC_PRO_WORKBENCH_ENABLED environment variable. This boolean drives the client bundle's decision to render Pro-specific navigation and components.

Simultaneously, isAgentRuntimeConfigured() (lines 22-25) performs server-side validation:

// Conceptual implementation based on lib/config/feature-flags.ts
const isAgentRuntimeConfigured = () => {
  return process.env.OPENMAIC_AGENT_RUNTIME_ENABLED === 'true' && 
         !!process.env.DATABASE_URL;
};

The middleware.ts file combines these checks at the edge. When a request hits /workbench, the middleware evaluates both conditions. If either returns false, the request receives a 404 response before reaching the application layer, preventing broken UI states where the frontend expects an agent that isn't running.

Programmatic Access to Feature Flags

You can check the Pro workbench status programmatically in your components or API routes:

import { isProWorkbenchEnabled } from '@/lib/config/feature-flags';

if (isProWorkbenchEnabled()) {
  // Render Pro-workbench specific UI elements
  console.log('Pro workbench is active');
}

This import pattern allows feature-specific logic to remain synchronized with the environment configuration defined in lib/config/feature-flags.ts.

Summary

• Enable the Pro workbench in OpenMAIC by setting three required environment variables: NEXT_PUBLIC_PRO_WORKBENCH_ENABLED, OPENMAIC_AGENT_RUNTIME_ENABLED, and DATABASE_URL.
• The system uses dual validation: isProWorkbenchEnabled() checks the public flag while isAgentRuntimeConfigured() verifies server-side prerequisites.
• Middleware protection in middleware.ts blocks access to /workbench with a 404 if configuration is incomplete.
• Always restart the server after modifying environment variables to refresh the client bundle.
• Reference lib/config/feature-flags.ts for the authoritative logic and .env.example for recommended default values.

Frequently Asked Questions

What environment variables are required to enable the Pro workbench?

You need three specific variables: NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true for the UI flag, OPENMAIC_AGENT_RUNTIME_ENABLED=true to activate the server agent, and a valid DATABASE_URL pointing to your PostgreSQL instance. The OpenMAIC source code strictly requires all three; missing any one results in the Pro workbench remaining disabled or inaccessible.

Why do I get a 404 when accessing /workbench?

OpenMAIC's middleware.ts returns a 404 when either isProWorkbenchEnabled() or isAgentRuntimeConfigured() returns false. Verify that .env.local contains all required variables and that your server was restarted after making changes. The middleware explicitly checks these conditions at lines 54-57 to prevent partial activation.

Can I enable the Pro workbench without the agent runtime?

No. The Pro workbench is designed as a chat-first course building interface that requires the background agent for functionality. The isAgentRuntimeConfigured() function in lib/config/feature-flags.ts specifically checks for OPENMAIC_AGENT_RUNTIME_ENABLED and DATABASE_URL. Without these, the middleware blocks access even if the public UI flag is enabled.

Where is the feature flag logic implemented in OpenMAIC?

The primary logic resides in lib/config/feature-flags.ts, which exports isProWorkbenchEnabled() and isAgentRuntimeConfigured(). The route protection is implemented in middleware.ts at the application root, while the visual transition between classic and Pro modes is handled by lib/workbench/pro-swap.ts.

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