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

> Easily enable the Pro workbench in OpenMAIC with our complete configuration guide. Learn to set feature flags and runtime variables for full access.

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

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```bash
cp .env.example .env.local

```

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

```dotenv

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

```bash
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:

```bash
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```typescript
// 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```tsx
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts), which exports `isProWorkbenchEnabled()` and `isAgentRuntimeConfigured()`. The route protection is implemented in [`middleware.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/middleware.ts) at the application root, while the visual transition between classic and Pro modes is handled by [`lib/workbench/pro-swap.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/pro-swap.ts).