Environment Variables Required for AI Provider Configuration in Open Notebook: Complete Reference

Open Notebook requires provider-specific API keys set as environment variables—such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or AZURE_OPENAI_API_KEY—which are validated at startup by the ProviderKeyLoader class in open_notebook/ai/key_provider.py to enable LLM, embedding, and speech services.

Open Notebook uses the Esperanto library to manage connections with large language models (LLMs) and speech-to-text (STT) / text-to-speech (TTS) services. Configuring these integrations requires setting specific environment variables for AI provider configuration that the runtime reads via os.getenv checks during the model discovery phase. The central mapping of these credentials is defined in open_notebook/ai/key_provider.py, while the documentation reference lives in docs/5-CONFIGURATION/environment-reference.md.

Standard AI Provider Environment Variables

Most AI providers require only a single API key environment variable. According to the source code in open_notebook/ai/key_provider.py, the following providers are supported with their respective required variables:

• OpenAI: OPENAI_API_KEY (line 31)
• Anthropic: ANTHROPIC_API_KEY (line 34)
• Google (Gemini): GOOGLE_API_KEY (line 37)
• Groq: GROQ_API_KEY (line 40)
• Mistral: MISTRAL_API_KEY (line 43)
• DeepSeek: DEEPSEEK_API_KEY (line 46)
• xAI: XAI_API_KEY (line 49)
• OpenRouter: OPENROUTER_API_KEY (line 52)
• Voyage AI: VOYAGE_API_KEY (line 55)
• ElevenLabs: ELEVENLABS_API_KEY (line 58)
• Deepgram (STT/TTS): DEEPGRAM_API_KEY (line 61)
• DashScope: DASHSCOPE_API_KEY (line 68)
• MiniMax: MINIMAX_API_KEY (line 71)

These variables are read during the model discovery process in open_notebook/ai/model_discovery.py, where the system checks for their presence before constructing provider clients.

Azure OpenAI Configuration Requirements

Azure OpenAI requires three core environment variables to establish the endpoint connection. As implemented in open_notebook/ai/key_provider.py (lines 188-198), you must provide:

• AZURE_OPENAI_API_KEY
• AZURE_OPENAI_ENDPOINT
• AZURE_OPENAI_API_VERSION

Service-Specific Overrides

You can configure separate Azure OpenAI resources for different service types by using per-service suffixes. These optional overrides take precedence over the base variables:

• LLM: AZURE_OPENAI_API_KEY_LLM, AZURE_OPENAI_ENDPOINT_LLM, AZURE_OPENAI_API_VERSION_LLM
• Embedding: AZURE_OPENAI_API_KEY_EMBEDDING, AZURE_OPENAI_ENDPOINT_EMBEDDING, AZURE_OPENAI_API_VERSION_EMBEDDING
• STT: AZURE_OPENAI_API_KEY_STT, AZURE_OPENAI_ENDPOINT_STT, AZURE_OPENAI_API_VERSION_STT
• TTS: AZURE_OPENAI_API_KEY_TTS, AZURE_OPENAI_ENDPOINT_TTS, AZURE_OPENAI_API_VERSION_TTS

OpenAI-Compatible Provider Setup

For generic OpenAI-compatible endpoints (such as local LLM servers or alternative providers), the system requires two base variables as referenced in the codebase:

• OPENAI_COMPATIBLE_API_KEY
• OPENAI_COMPATIBLE_BASE_URL

Service-Specific Overrides

Similar to Azure, you can specify different endpoints for specific service types:

• LLM: OPENAI_COMPATIBLE_API_KEY_LLM, OPENAI_COMPATIBLE_BASE_URL_LLM
• Embedding: OPENAI_COMPATIBLE_API_KEY_EMBEDDING, OPENAI_COMPATIBLE_BASE_URL_EMBEDDING
• STT: OPENAI_COMPATIBLE_API_KEY_STT, OPENAI_COMPATIBLE_BASE_URL_STT
• TTS: OPENAI_COMPATIBLE_API_KEY_TTS, OPENAI_COMPATIBLE_BASE_URL_TTS

How Environment Variables Are Loaded at Runtime

The ProviderKeyLoader class in open_notebook/ai/key_provider.py centralizes the mapping between provider names and their required environment variables. When the application starts, the model discovery logic in open_notebook/ai/model_discovery.py iterates through available providers and checks for the presence of these variables using os.getenv.

The API endpoint defined in api/routers/models.py exposes this configuration state, allowing you to verify which credentials the server has detected at runtime.

Configuration Examples

Environment File Setup

Create a .env file or export variables in your shell:

# Standard providers

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=...
export GROQ_API_KEY=...

# Azure OpenAI

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/
export AZURE_OPENAI_API_VERSION=2024-10-21

# OpenAI-Compatible (e.g., local LLM)

export OPENAI_COMPATIBLE_API_KEY=not-needed-for-local
export OPENAI_COMPATIBLE_BASE_URL=http://localhost:1234/v1

# Optional: Service-specific overrides

export OPENAI_COMPATIBLE_BASE_URL_EMBEDDING=http://localhost:1234/v1
export AZURE_OPENAI_API_KEY_TTS=...

Programmatic Access

You can manually trigger the key loading mechanism in Python:

from open_notebook.ai.key_provider import ProviderKeyLoader

loader = ProviderKeyLoader()
loader.apply_to_environment(provider="openai")

# After this call, OPENAI_API_KEY is guaranteed to be set

# or an exception is raised if missing

Verify Configuration

Check which providers are active via the API:

curl -s http://localhost:5055/api/routers/models | jq .

Summary

• Open Notebook requires provider-specific API keys set as environment variables to enable AI services through the Esperanto library.
• Standard providers (OpenAI, Anthropic, Google, etc.) each require a single *_API_KEY variable as defined in open_notebook/ai/key_provider.py.
• Azure OpenAI requires three base variables (AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION) with optional per-service overrides.
• OpenAI-Compatible endpoints require OPENAI_COMPATIBLE_API_KEY and OPENAI_COMPATIBLE_BASE_URL, also supporting service-specific overrides.
• The ProviderKeyLoader class validates these variables at runtime, and the /api/routers/models endpoint reports which credentials are detected.

Frequently Asked Questions

Do I need to set all environment variables listed?

No. You only need to set the environment variables for providers you intend to use. The model discovery logic in open_notebook/ai/model_discovery.py checks for available credentials at startup and only initializes providers with valid keys. Unused providers can be left unconfigured.

Can I use different Azure OpenAI endpoints for different services?

Yes. While Azure OpenAI requires the three base variables (AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION), you can override these for specific service types (LLM, Embedding, STT, TTS) by using the suffixed variants like AZURE_OPENAI_ENDPOINT_LLM or AZURE_OPENAI_API_KEY_TTS. These overrides take precedence over the base configuration.

How do I verify my AI provider configuration is working?

You can verify configuration by querying the /api/routers/models endpoint via curl http://localhost:5055/api/routers/models, which returns the list of detected providers and their available models. Additionally, the ProviderKeyLoader.apply_to_environment() method will raise an exception if a required key is missing when explicitly loading a provider.

What happens if an environment variable is missing?

If a required environment variable is missing for a provider you are attempting to use, the ProviderKeyLoader will fail to initialize that provider, and it will not appear in the available models list. The application will continue running, but API calls to that specific provider will be unavailable. For Azure OpenAI and OpenAI-Compatible providers, all three (or two) base variables must be present for the provider to be considered configured.

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