Complete Environment Reference

Comprehensive list of all environment variables available in Open Notebook.

API Configuration

Important: OPEN_NOTEBOOK_ENCRYPTION_KEY is required for storing AI provider credentials via the Settings UI. Without it, you cannot save credentials. If you change or lose this key, all stored credentials become unreadable.

Database: SurrealDB

Database: Retry Configuration

Database: Concurrency

LLM Timeouts

Text-to-Speech (TTS)

Content Extraction

Setup:

• Firecrawl: https://firecrawl.dev/
• Jina: https://jina.ai/

Network / Proxy

Route all outbound HTTP requests through a proxy server. Useful for corporate/firewalled environments.

The underlying libraries (esperanto, content-core, podcast-creator) automatically detect proxy settings from these standard environment variables.

Affects:

• AI provider API calls (OpenAI, Anthropic, Google, Groq, etc.)
• Content extraction from URLs (web scraping, YouTube transcripts)
• Podcast generation (LLM and TTS provider calls)

Format: http://[user:pass@]host:port or https://[user:pass@]host:port

Examples:

# Basic proxy
HTTP_PROXY=http://proxy.corp.com:8080
HTTPS_PROXY=http://proxy.corp.com:8080

# Authenticated proxy
HTTP_PROXY=http://user:[email protected]:8080
HTTPS_PROXY=http://user:[email protected]:8080

# Bypass proxy for local hosts
NO_PROXY=localhost,127.0.0.1,.local

Debugging & Monitoring

Setup: https://smith.langchain.com/

Environment Variables by Use Case

Minimal Setup (New Installation)

OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key
SURREAL_URL=ws://surrealdb:8000/rpc
SURREAL_USER=root
SURREAL_PASSWORD=password
SURREAL_NAMESPACE=open_notebook
SURREAL_DATABASE=open_notebook

Then configure AI providers via Settings → API Keys in the browser.

Production Deployment

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-strong-secret-key
OPEN_NOTEBOOK_PASSWORD=your-secure-password
API_URL=https://mynotebook.example.com
SURREAL_USER=production_user
SURREAL_PASSWORD=secure_password

Self-Hosted Behind Reverse Proxy

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-secret-key
API_URL=https://mynotebook.example.com

Corporate Environment (Behind Proxy)

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-secret-key
HTTP_PROXY=http://proxy.corp.com:8080
HTTPS_PROXY=http://proxy.corp.com:8080
NO_PROXY=localhost,127.0.0.1

High-Performance Deployment

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-secret-key
SURREAL_COMMANDS_MAX_TASKS=10
TTS_BATCH_SIZE=5
API_CLIENT_TIMEOUT=600

Debugging

OPEN_NOTEBOOK_ENCRYPTION_KEY=your-secret-key
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your-key

Validation

Check if a variable is set:

# Check single variable
echo $OPEN_NOTEBOOK_ENCRYPTION_KEY

# Check multiple
env | grep -E "OPEN_NOTEBOOK|API_URL"

# Print all config
env | grep -E "^[A-Z_]+=" | sort

Notes

• Case-sensitive: OPEN_NOTEBOOK_ENCRYPTION_KEY ≠ open_notebook_encryption_key
• No spaces: OPEN_NOTEBOOK_ENCRYPTION_KEY=my-key not OPEN_NOTEBOOK_ENCRYPTION_KEY = my-key
• Quote values: Use quotes for values with spaces: API_URL="http://my server:5055"
• Restart required: Changes take effect after restarting services
• Secrets: Don't commit encryption keys or passwords to git
• AI Providers: Configure via Settings → API Keys in the browser (not via env vars)
• Migration: Use Settings UI to migrate existing env vars to the credential system. See API Configuration

Quick Setup Checklist

• Set OPEN_NOTEBOOK_ENCRYPTION_KEY in docker-compose.yml
• Set database credentials (SURREAL_*)
• Start services
• Open browser → Go to Settings → API Keys
• Add Credential for your AI provider
• Test Connection to verify
• Discover & Register Models
• Set API_URL if behind reverse proxy
• Change SURREAL_PASSWORD in production
• Try a test chat

Done!

Legacy: AI Provider Environment Variables (Deprecated)

Deprecated: The following AI provider API key environment variables are deprecated. Configure providers via the Settings UI instead. These variables may still work as a fallback but are no longer recommended.

If you have these variables configured from a previous installation, click the Migrate to Database button in Settings → API Keys to import them into the credential system, then remove them from your configuration.