Complete Environment Reference
Comprehensive list of all environment variables available in Open Notebook.
API Configuration
| Variable | Required? | Default | Description |
|---|---|---|---|
API_URL | No | Auto-detected | URL where frontend reaches API (e.g., http://localhost:5055) |
INTERNAL_API_URL | No | http://localhost:5055 | Internal API URL for Next.js server-side proxying |
API_CLIENT_TIMEOUT | No | 300 | Client timeout in seconds (how long to wait for API response) |
OPEN_NOTEBOOK_PASSWORD | No | None | Password to protect Open Notebook instance |
OPEN_NOTEBOOK_ENCRYPTION_KEY | Yes | None | Secret string to encrypt credentials stored in database (any string works). Required for the credential system. Supports Docker secrets via _FILE suffix. |
HOSTNAME | No | 0.0.0.0 (in Docker) | Network interface for Next.js to bind to. Default 0.0.0.0 ensures accessibility from reverse proxies |
Important:
OPEN_NOTEBOOK_ENCRYPTION_KEYis 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
| Variable | Required? | Default | Description |
|---|---|---|---|
SURREAL_URL | Yes | ws://surrealdb:8000/rpc | SurrealDB WebSocket connection URL |
SURREAL_USER | Yes | root | SurrealDB username |
SURREAL_PASSWORD | Yes | root | SurrealDB password |
SURREAL_NAMESPACE | Yes | open_notebook | SurrealDB namespace |
SURREAL_DATABASE | Yes | open_notebook | SurrealDB database name |
Database: Retry Configuration
| Variable | Required? | Default | Description |
|---|---|---|---|
SURREAL_COMMANDS_RETRY_ENABLED | No | true | Enable retries on failure |
SURREAL_COMMANDS_RETRY_MAX_ATTEMPTS | No | 3 | Maximum retry attempts |
SURREAL_COMMANDS_RETRY_WAIT_STRATEGY | No | exponential_jitter | Retry wait strategy (exponential_jitter/exponential/fixed/random) |
SURREAL_COMMANDS_RETRY_WAIT_MIN | No | 1 | Minimum wait time between retries (seconds) |
SURREAL_COMMANDS_RETRY_WAIT_MAX | No | 30 | Maximum wait time between retries (seconds) |
Database: Concurrency
| Variable | Required? | Default | Description |
|---|---|---|---|
SURREAL_COMMANDS_MAX_TASKS | No | 5 | Maximum concurrent database tasks |
LLM Timeouts
| Variable | Required? | Default | Description |
|---|---|---|---|
ESPERANTO_LLM_TIMEOUT | No | 60 | LLM inference timeout in seconds |
ESPERANTO_SSL_VERIFY | No | true | Verify SSL certificates (false = development only) |
ESPERANTO_SSL_CA_BUNDLE | No | None | Path to custom CA certificate bundle |
Embeddings
| Variable | Required? | Default | Description |
|---|---|---|---|
OPEN_NOTEBOOK_EMBEDDING_BATCH_SIZE | No | 50 | Number of texts sent per embedding batch. Lower this for CPU-only or stricter OpenAI-compatible embedding providers. |
OPEN_NOTEBOOK_MIN_CHUNK_SIZE | No | 5 | Minimum chunk size in tokens. Chunks below this threshold are dropped before embedding to avoid degenerate single-character fragments that some providers (e.g. llama.cpp) return null embeddings for. Set to 0 to disable filtering. |
API / CORS
| Variable | Required? | Default | Description |
|---|---|---|---|
CORS_ORIGINS | No | * | Comma-separated list of origins allowed to call the API (e.g. https://app.example.com,https://www.example.com). Default * accepts any origin; for production, set this explicitly to your frontend origin(s). Changes require an API restart. The API logs a warning on startup when unset. |
When to change this:
- You access the UI at a custom domain (reverse proxy, HTTPS, public deployment).
- The frontend runs on a different port than
3000. - You serve the frontend from a different host than the API (e.g. CDN).
Example for a production deployment behind a reverse proxy:
CORS_ORIGINS=https://notebook.example.comText-to-Speech (TTS)
| Variable | Required? | Default | Description |
|---|---|---|---|
TTS_BATCH_SIZE | No | 5 | Concurrent TTS requests (1-5, depends on provider) |
ESPERANTO_TTS_TIMEOUT | No | 300 | Text-to-speech request timeout in seconds (passed through to Esperanto). Increase it for slow or self-hosted TTS providers that take longer than 5 minutes to synthesize a segment, otherwise long podcast segments can fail with a timeout. |
Content Extraction
| Variable | Required? | Default | Description |
|---|---|---|---|
FIRECRAWL_API_KEY | No | None | Firecrawl API key for advanced web scraping |
JINA_API_KEY | No | None | Jina AI API key for web extraction |
Setup:
- Firecrawl: https://firecrawl.dev/
- Jina: https://jina.ai/
Network / Proxy
| Variable | Required? | Default | Description |
|---|---|---|---|
HTTP_PROXY | No | None | HTTP proxy URL for outbound HTTP requests |
HTTPS_PROXY | No | None | HTTPS proxy URL for outbound HTTPS requests |
NO_PROXY | No | None | Comma-separated list of hosts to bypass 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:password@proxy.corp.com:8080
HTTPS_PROXY=http://user:password@proxy.corp.com:8080
# Bypass proxy for local hosts
NO_PROXY=localhost,127.0.0.1,.localDebugging & Monitoring
| Variable | Required? | Default | Description |
|---|---|---|---|
LANGCHAIN_TRACING_V2 | No | false | Enable LangSmith tracing |
LANGCHAIN_ENDPOINT | No | https://api.smith.langchain.com | LangSmith endpoint |
LANGCHAIN_API_KEY | No | None | LangSmith API key |
LANGCHAIN_PROJECT | No | Open Notebook | LangSmith project name |
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_]+=" | sortNotes
- Case-sensitive:
OPEN_NOTEBOOK_ENCRYPTION_KEY≠open_notebook_encryption_key - No spaces:
OPEN_NOTEBOOK_ENCRYPTION_KEY=my-keynotOPEN_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_KEYin 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_URLif behind reverse proxy - Change
SURREAL_PASSWORDin 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.
| Variable | Provider | Replacement |
|---|---|---|
OPENAI_API_KEY | OpenAI | Settings → API Keys → Add OpenAI Credential |
ANTHROPIC_API_KEY | Anthropic | Settings → API Keys → Add Anthropic Credential |
GOOGLE_API_KEY | Google Gemini | Settings → API Keys → Add Google Credential |
GEMINI_API_BASE_URL | Google Gemini | Configure in Google Gemini credential |
VERTEX_PROJECT | Vertex AI | Settings → API Keys → Add Vertex AI Credential |
VERTEX_LOCATION | Vertex AI | Configure in Vertex AI credential |
GOOGLE_APPLICATION_CREDENTIALS | Vertex AI | Configure in Vertex AI credential |
GROQ_API_KEY | Groq | Settings → API Keys → Add Groq Credential |
MISTRAL_API_KEY | Mistral | Settings → API Keys → Add Mistral Credential |
DEEPSEEK_API_KEY | DeepSeek | Settings → API Keys → Add DeepSeek Credential |
XAI_API_KEY | xAI | Settings → API Keys → Add xAI Credential |
OLLAMA_API_BASE | Ollama | Settings → API Keys → Add Ollama Credential |
OPENROUTER_API_KEY | OpenRouter | Settings → API Keys → Add OpenRouter Credential |
OPENROUTER_BASE_URL | OpenRouter | Configure in OpenRouter credential |
VOYAGE_API_KEY | Voyage AI | Settings → API Keys → Add Voyage AI Credential |
ELEVENLABS_API_KEY | ElevenLabs | Settings → API Keys → Add ElevenLabs Credential |
OPENAI_COMPATIBLE_BASE_URL | OpenAI-Compatible | Settings → API Keys → Add OpenAI-Compatible Credential |
OPENAI_COMPATIBLE_API_KEY | OpenAI-Compatible | Configure in OpenAI-Compatible credential |
OPENAI_COMPATIBLE_BASE_URL_LLM | OpenAI-Compatible | Configure per-service URL in credential |
OPENAI_COMPATIBLE_API_KEY_LLM | OpenAI-Compatible | Configure per-service key in credential |
OPENAI_COMPATIBLE_BASE_URL_EMBEDDING | OpenAI-Compatible | Configure per-service URL in credential |
OPENAI_COMPATIBLE_API_KEY_EMBEDDING | OpenAI-Compatible | Configure per-service key in credential |
OPENAI_COMPATIBLE_BASE_URL_STT | OpenAI-Compatible | Configure per-service URL in credential |
OPENAI_COMPATIBLE_API_KEY_STT | OpenAI-Compatible | Configure per-service key in credential |
OPENAI_COMPATIBLE_BASE_URL_TTS | OpenAI-Compatible | Configure per-service URL in credential |
OPENAI_COMPATIBLE_API_KEY_TTS | OpenAI-Compatible | Configure per-service key in credential |
DASHSCOPE_API_KEY | DashScope (Qwen) | Settings → API Keys → Add DashScope Credential |
MINIMAX_API_KEY | MiniMax | Settings → API Keys → Add MiniMax Credential |
AZURE_OPENAI_API_KEY | Azure OpenAI | Settings → API Keys → Add Azure OpenAI Credential |
AZURE_OPENAI_ENDPOINT | Azure OpenAI | Configure in Azure OpenAI credential |
AZURE_OPENAI_API_VERSION | Azure OpenAI | Configure in Azure OpenAI credential |
AZURE_OPENAI_API_KEY_LLM | Azure OpenAI | Configure per-service in credential |
AZURE_OPENAI_ENDPOINT_LLM | Azure OpenAI | Configure per-service in credential |
AZURE_OPENAI_API_VERSION_LLM | Azure OpenAI | Configure per-service in credential |
AZURE_OPENAI_API_KEY_EMBEDDING | Azure OpenAI | Configure per-service in credential |
AZURE_OPENAI_ENDPOINT_EMBEDDING | Azure OpenAI | Configure per-service in credential |
AZURE_OPENAI_API_VERSION_EMBEDDING | Azure OpenAI | Configure per-service in credential |