What Environment Variables Are Needed to Run OpenMAIC: Complete Configuration Guide

You only need one LLM provider API key (such as OPENAI_API_KEY) to run OpenMAIC; all other features—including image generation, text-to-speech, and persistence—are optional and activated by setting additional environment variables.

OpenMAIC is a highly configurable AI course generation platform developed by the THU-MAIC organization. Understanding what environment variables are needed to run OpenMAIC is essential for both local development and production deployments, as the application uses a modular architecture where services are enabled via specific configuration flags. The repository's .env.example file serves as the definitive reference for all available settings.

Core Required Variables

At minimum, OpenMAIC requires access to a large language model (LLM) for lesson generation. You must provide at least one provider API key.

LLM Provider API Keys

The application supports multiple LLM providers through a standardized naming convention. The primary variable is:

• OPENAI_API_KEY – Supplies the OpenAI API for lesson generation. If you use a different provider, substitute the prefix accordingly (e.g., ANTHROPIC_API_KEY, AZURE_OPENAI_API_KEY, GOOGLE_API_KEY).

According to the source code in .env.example (lines 11-33), the system accepts any provider following the pattern <PROVIDER>_API_KEY. If multiple keys are defined, the application uses DEFAULT_MODEL or MODEL_ROUTES to determine routing; otherwise, it falls back to the first defined provider.

Optional Security Variables

While not required for basic operation, these variables control access and security:

• ACCESS_CODE – Implements site-level password protection for the UI.
• ALLOW_LOCAL_NETWORKS – Controls network access for self-hosted deployments.

Optional Provider-Specific Variables

Each LLM, speech, and image provider supports three configuration patterns: <PROVIDER>_API_KEY, <PROVIDER>_BASE_URL, and <PROVIDER>_MODELS. These are defined in .env.example across the LLM Providers, TTS, ASR, and Image sections.

Azure OpenAI Service

• AZURE_OPENAI_API_KEY
• AZURE_OPENAI_BASE_URL
• AZURE_OPENAI_MODELS

Anthropic Claude

• ANTHROPIC_API_KEY
• ANTHROPIC_BASE_URL
• ANTHROPIC_MODELS

Google Gemini

• GOOGLE_API_KEY
• GOOGLE_BASE_URL
• GOOGLE_MODELS

Local/Custom Providers

• Lemonade (local OpenAI-compatible): LEMONADE_BASE_URL (no API key required)
• FunASR (local ASR): ASR_FUNASR_BASE_URL (no API key required)

To disable a specific provider, set <PREFIX>_ENABLED=false.

Feature-Gate and Runtime Variables

OpenMAIC uses NEXT_PUBLIC_* prefixes for client-side feature flags and OPENMAIC_* prefixes for server-side runtime configuration. Note that all NEXT_PUBLIC_* variables are compiled into the client bundle at build time; changing them requires a rebuild.

Pro Workbench and Agent Runtime

• NEXT_PUBLIC_PRO_WORKBENCH_ENABLED – Enables the Pro workbench UI (experimental features).
• OPENMAIC_AGENT_RUNTIME_ENABLED – Activates the durable agent runtime required for the Pro workbench.
• DATABASE_URL – PostgreSQL connection string (e.g., postgres://openmaic:openmaic-dev@localhost:5432/openmaic). Required when OPENMAIC_AGENT_RUNTIME_ENABLED is true or when using server-backed persistence.

Media and Speech Services

Each modality uses prefixed environment variables:

• TTS: TTS_LEMONADE_BASE_URL, TTS_OPENAI_API_KEY
• Image Generation: IMAGE_LEMONADE_BASE_URL, IMAGE_ENABLED
• Video Export: NEXT_PUBLIC_ENABLE_VIDEO_EXPORT

Persistence Configuration

When NEXT_PUBLIC_PERSISTENCE is enabled, the application requires:

• DATABASE_URL – PostgreSQL endpoint for the HTTP persistence API
• PERSISTENCE_DEV_TOKEN – Authentication token for the persistence endpoint, handled in lib/persistence/server-auth.ts

Configuration Examples

Minimal Local Setup

Create a .env.local file with only the essential LLM provider key:

# .env.local

OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXX

# Optional: specify default model if using multiple providers

DEFAULT_MODEL=openai:gpt-5.5

This configuration runs OpenMAIC in browser-only mode with all advanced features disabled.

Pro Workbench with PostgreSQL Persistence

Enable durable sessions and the advanced workbench interface:

# .env.local

OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXX
NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true
OPENMAIC_AGENT_RUNTIME_ENABLED=true
DATABASE_URL=postgres://openmaic:openmaic-dev@localhost:5432/openmaic
MODEL_ROUTES='{"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'

According to the docker-compose.yml, this profile launches the PostgreSQL service and connects the agent runtime to the database.

Docker Compose Deployment

For containerized deployments, copy the example file and modify the provider keys:

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
cp .env.example .env.local

# Edit .env.local to add your provider key

sed -i 's/^OPENAI_API_KEY=.*/OPENAI_API_KEY=sk-XXXXX/' .env.local

# Standard browser-only deployment

docker compose up --build

# With server-backed persistence

docker compose --profile server-persistence up --build

The docker-compose.yml file defines which variables are forwarded to containers and sets up the PostgreSQL service for persistence-enabled profiles.

Local LLM Integration (Lemonade)

Route all AI services to a local Lemonade server without external API calls:

# .env.local

LEMONADE_BASE_URL=http://localhost:13305/v1

# No API key needed for local Lemonade

TTS_LEMONADE_BASE_URL=http://localhost:13305/v1

OpenMAIC will route LLM, image generation, and TTS requests to localhost:13305 as specified in the provider configuration.

How Variables Integrate with Architecture

The environment variables map to specific architectural components within the OpenMAIC codebase:

1. Generation Pipeline (@openmaic/generation) – Pulls model configuration from DEFAULT_MODEL or MODEL_ROUTES. If undefined, uses the first available provider key discovered in environment variables.

2. Persistence Layer – When NEXT_PUBLIC_PERSISTENCE is true, the browser communicates with the embedded HTTP endpoint at /api/persistence. This endpoint requires DATABASE_URL and validates requests using PERSISTENCE_DEV_TOKEN as implemented in lib/persistence/server-auth.ts.

3. Agent Runtime – The durable workbench at /api/agent/* initializes only when OPENMAIC_AGENT_RUNTIME_ENABLED is true and DATABASE_URL presents valid PostgreSQL credentials. Model routing for the agent driver follows the MODEL_ROUTES JSON specification.

4. Proxy and Network Settings – HTTP_PROXY, HTTPS_PROXY, and NO_PROXY variables control outbound network access for self-hosted environments, defined in the .env.example network section.

Summary

• Only one requirement: Any LLM provider API key (e.g., OPENAI_API_KEY) is mandatory for core lesson generation.
• Optional features: Image generation, text-to-speech, speech-to-text, and web search activate only when their respective <PROVIDER>_API_KEY variables are set.
• Persistence needs PostgreSQL: DATABASE_URL is required only when enabling OPENMAIC_AGENT_RUNTIME_ENABLED or server-backed persistence.
• Client-side flags require rebuild: All NEXT_PUBLIC_* variables are baked into the build; runtime changes require recompilation.
• Reference files: Consult .env.example for the complete variable list and README.md for Quick Start instructions.

Frequently Asked Questions

What is the minimum configuration to run OpenMAIC locally?

You need only a single LLM provider API key, such as OPENAI_API_KEY, set in your .env.local file. The application will start in browser-only mode without persistence or advanced features.

Do I need a database to run OpenMAIC?

No, PostgreSQL is optional. You only need DATABASE_URL if you enable OPENMAIC_AGENT_RUNTIME_ENABLED for the Pro workbench or set NEXT_PUBLIC_PERSISTENCE to true for server-backed session storage. Otherwise, the application runs entirely in the browser.

Can I use local models instead of OpenAI or Anthropic?

Yes. Set LEMONADE_BASE_URL to point to your local OpenAI-compatible endpoint (e.g., Lemonade running on localhost:13305). For local speech recognition, configure ASR_FUNASR_BASE_URL. These local providers do not require API keys.

Why are my changes to NEXT_PUBLIC_* variables not taking effect?

Variables prefixed with NEXT_PUBLIC_ are compiled into the Next.js client bundle at build time. To apply changes to these feature flags, you must rebuild the application with docker compose up --build or npm run build.

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