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

> Discover essential environment variables for OpenMAIC. Learn how to configure your API keys and optional features like image generation for a seamless experience.

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

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/server-auth.ts)

## Configuration Examples

### Minimal Local Setup

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

```env

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

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

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

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