How to Configure LLM Providers in OpenMAIC: Environment Variables vs. YAML Setup

OpenMAIC supports any OpenAI-compatible LLM through server-side configuration using either environment variables in .env.local or a structured server-providers.yml file, ensuring API keys never reach the browser.

OpenMAIC (THU-MAIC/OpenMAIC) is a provider-neutral platform that allows you to integrate any large language model speaking the OpenAI-compatible API. When you configure LLM providers in OpenMAIC, all sensitive credentials remain server-side, protecting your API keys from client exposure while supporting generation, media, TTS, and ASR backends.

Understanding OpenMAIC's Provider-Neutral Architecture

The core abstraction lives in the lib/ai package, specifically within providerRegistry.ts and modelResolver.ts. This architecture accepts any provider implementing the standard OpenAI API format, including OpenAI, Azure OpenAI, Anthropic, AWS Bedrock, Google Gemini, MiniMax, and Grok.

Configuration occurs exclusively on the server. The startup script reads your settings from either environment variables or the YAML file, registers each provider in the ProviderRegistry, and makes them available to all AI backends. The browser only sends the providerId and model name; the server injects the actual credentials.

Method 1: Configure LLM Providers Using Environment Variables

The most common approach uses a .env.local file copied from the project's .env.example. This method stores API keys, base URLs, and default models as environment variables that the server reads during boot.

First, copy the example environment file from the repository root:

cp .env.example .env.local

Next, add your provider credentials to .env.local. You can configure multiple providers simultaneously. For example, to set up OpenAI and Azure OpenAI according to the README (lines 25-38):

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
AZURE_OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
AZURE_OPENAI_BASE_URL=https://YOUR-RESOURCE.openai.azure.com/openai
AZURE_OPENAI_MODELS=YOUR-DEPLOYMENT-NAME
DEFAULT_MODEL=openai:gpt-5.5

Finally, restart the server using pnpm dev or Docker. OpenMAIC automatically reads the variables from process.env and registers each provider in the registry.

Method 2: Configure LLM Providers Using server-providers.yml

For advanced use cases requiring multiple models per provider or centralized management, create a server-providers.yml file at the repository root. When this file exists, OpenMAIC parses it on startup and overrides any corresponding environment variables.

Structure the YAML with provider IDs as top-level keys:

providers:
  openai:
    apiKey: sk-xxxxxxxxxxxxxxxxxxxx
  azure:
    apiKey: sk-xxxxxxxxxxxxxxxxxxxx
    baseUrl: https://YOUR-RESOURCE.openai.azure.com/openai
    models:
      - YOUR-DEPLOYMENT-NAME
  anthropic:
    apiKey: sk-ant-xxxxxxxxxxxxxxxxxxxx

You can also specify a default model per provider within the YAML:

providers:
  openai:
    apiKey: sk-xxxxxxxxxxxxxxxxxxxx
    defaultModel: gpt-5.5

Setting the Default Model

You can configure a default LLM that OpenMAIC uses when requests omit specific model parameters. Set this globally via environment variable:

DEFAULT_MODEL=openai:gpt-5.5

Or set provider-specific defaults in server-providers.yml. If no default is configured, OpenMAIC falls back to the first enabled provider according to the fallback configuration in opencode.json (lines 1-8).

Runtime Provider Resolution

When the server receives a generation or media request, the resolution logic in lib/ai/modelResolver.ts performs the following sequence:

1. Extracts the provider id (e.g., openai, azure, anthropic, minimax) from the request payload
2. Validates the provider against the ProviderRegistry to ensure it is enabled
3. Injects the stored API key and base URL into the request context
4. Applies fallback logic only if the provider's allow_fallbacks flag is true, as defined in opencode.json

If a request references a disabled or unknown provider, the system returns a clear PROVIDER_DISABLED or PROVIDER_NOT_FOUND error. No automatic fallback occurs unless explicitly enabled in the fallback configuration.

Complete Configuration Examples

Example 1: OpenAI and MiniMax via .env.local

# .env.local

OPENAI_API_KEY=sk-abcdef1234567890
MINIMAX_API_KEY=abc123def456
MINIMAX_BASE_URL=https://api.minimaxi.com/anthropic/v1
DEFAULT_MODEL=openai:gpt-5.5

Example 2: Anthropic and AWS Bedrock via server-providers.yml

# server-providers.yml

providers:
  anthropic:
    apiKey: sk-ant-abcdef123456
  bedrock:
    models:
      - us.anthropic.claude-sonnet-5
      - us.anthropic.claude-opus-4-8

Example 3: Calling the generation API with an explicit provider

const response = await fetch('http://localhost:3000/api/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    providerId: 'openai',          // matches the key in .env or YAML
    model: 'gpt-5.5',
    prompt: 'Explain quantum computing in simple terms.'
  })
});

Summary

• OpenMAIC keeps all LLM credentials server-side in either .env.local or server-providers.yml, never exposing keys to the browser
• Environment variables offer the fastest setup for simple configurations and follow 12-factor app principles
• The YAML file provides structured, multi-model configurations and overrides environment variables when both exist
• The lib/ai package handles provider registration, model resolution, and error handling through ProviderRegistry and modelResolver.ts
• Set a global default using DEFAULT_MODEL or per-provider defaults in YAML; otherwise, OpenMAIC uses the first configured provider
• Runtime resolution validates provider IDs and enforces error codes like PROVIDER_DISABLED without automatic fallbacks unless configured in opencode.json

Frequently Asked Questions

Can I configure LLM providers on the client side in OpenMAIC?

No. OpenMAIC strictly prevents API key exposure to browsers by design. All provider configuration happens server-side through environment variables or the server-providers.yml file. The client only transmits the providerId and model name; the server retrieves the actual API key from its secure registry.

What happens if I specify both environment variables and a YAML file?

When server-providers.yml exists at the repository root, OpenMAIC loads it during the boot process and overrides any corresponding environment variables. The YAML file takes precedence, allowing you to maintain a single declarative source of truth for complex multi-provider setups while keeping .env.local for simpler overrides.

How do I set a default model for all generation requests?

Configure the DEFAULT_MODEL environment variable in .env.local using the format provider:model (e.g., openai:gpt-5.5 or minimax:MiniMax-M2.7-highspeed), or set defaultModel within the specific provider block in server-providers.yml. If neither is set, OpenMAIC defaults to the first provider in the registry.

Which provider IDs are valid when configuring OpenMAIC?

Valid provider IDs include openai, azure, anthropic, minimax, bedrock, gemini, and grok, along with any custom OpenAI-compatible endpoints. These IDs must match the keys in your .env.local file (e.g., OPENAI_API_KEY maps to provider openai) or the top-level keys under providers in your server-providers.yml file.

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