Open Notebook Production AI Provider Deployment and API Keys Configuration

Open Notebook stores AI provider credentials in an encrypted database rather than plain environment variables, requiring OPEN_NOTEBOOK_ENCRYPTION_KEY and CORS configuration for secure production deployments.

The lfnovo/open-notebook repository provides a secure, production-ready approach to managing AI provider credentials. Instead of exposing API keys in environment variables, the system encrypts credentials at rest and manages them through a dedicated UI, with specific configuration requirements for high-availability deployments.

Core Production Configuration Components

Production deployment centers on three critical areas: encryption management, credential storage, and environment-specific networking settings.

Encryption Key Setup

The OPEN_NOTEBOOK_ENCRYPTION_KEY environment variable is mandatory for production deployments. This key encrypts all stored API credentials in the database. According to docs/5-CONFIGURATION/environment-reference.md, you must set this variable in your deployment manifest (e.g., docker-compose.yml) to enable the encryption subsystem.

Without this key, the application cannot securely store or retrieve provider credentials, making it a blocking dependency for production AI provider deployment.

Provider Credential Management

Credentials are added through Settings → API Keys in the web interface. As documented in docs/5-CONFIGURATION/ai-providers.md, each supported provider (OpenAI, Anthropic, Google Gemini, Groq, OpenRouter, Azure OpenAI, Ollama, and local OpenAI-compatible services) has a dedicated "Add Credential" flow.

The workflow follows this sequence:

1. Add Credential – Encrypts and stores the API key in the database
2. Test Connection – Validates connectivity via the provider's health endpoint
3. Discover Models – Fetches available models from the provider's API
4. Register Models – Makes models available to the notebook interface

While legacy environment-variable based keys are deprecated, they remain accepted as a fallback mechanism according to docs/5-CONFIGURATION/environment-reference.md.

Production Environment Variables

Critical networking and security settings for production include:

• API_URL – The public HTTPS URL of your API instance (e.g., https://notebook.example.com)
• CORS_ORIGINS – Whitelist of domains allowed to call the API; must match your frontend's domain in production to prevent cross-origin attacks

Optional performance tuning variables for high-load deployments, as specified in docs/5-CONFIGURATION/advanced.md, include:

• API_CLIENT_TIMEOUT – Global API client timeout in seconds
• ESPERANTO_LLM_TIMEOUT – Specific timeout for LLM operations
• SURREAL_COMMANDS_MAX_TASKS – Concurrency limits for database operations

Provider-Specific Configuration Options

Each AI provider requires specific credential fields and supports distinct model configurations. The following table summarizes production-recommended setups based on docs/5-CONFIGURATION/ai-providers.md:

Provider	Credential Fields	Production Model Recommendations
OpenAI	API key (starts with sk-proj-)	gpt-4o (balanced performance) or gpt-4o-mini (cost-effective)
Anthropic	API key (sk-ant-...)	claude-sonnet-4-5 (highest quality) or claude-3-5-haiku (faster, cheaper)
Google Gemini	API key	gemini-2.0-flash-exp (fast inference) or gemini-1.5-pro-latest (long context)
Groq	API key	llama-3.3-70b-versatile (quality) or gemma2-9b-it (speed optimized)
OpenRouter	API key, base URL	anthropic/claude-sonnet-4.5 or google/gemini-2.0-flash-exp
Azure OpenAI	API key, endpoint, API version	Same model names as OpenAI, accessed via Azure-specific endpoints
Ollama	Base URL (http://host:11434)	llama3.1:8b (balanced) or phi3:3.8b (low-memory)
Local OpenAI-compatible	Base URL (LM Studio, vLLM)	No API key required; uses backing service model names

For self-hosted options like Ollama or local OpenAI-compatible servers (LM Studio, vLLM), configuration requires only the base URL endpoint, with no API key necessary for local inference.

Production Deployment Checklist

Follow these steps to configure a production-ready Open Notebook instance:

1. Set OPEN_NOTEBOOK_ENCRYPTION_KEY to a cryptographically secure random string
2. Configure API_URL with your public HTTPS endpoint
3. Set CORS_ORIGINS to restrict API access to your authorized frontend domain
4. Deploy the container stack (Docker Compose or Kubernetes)
5. Navigate to Settings → API Keys in the UI
6. Add credentials for each required provider using the encrypted flow
7. Test connections and discover available models
8. Verify functionality with a test chat completion

Implementation Examples

Docker Compose Production Configuration

Configure your docker-compose.yml with the required encryption and networking variables:

services:
  open-notebook:
    image: ghcr.io/lfnovo/open-notebook:latest
    ports:
      - "5055:5055"
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=${OPEN_NOTEBOOK_ENCRYPTION_KEY}
      - API_URL=https://notebook.example.com
      - CORS_ORIGINS=https://notebook.example.com
      - SURREAL_URL=ws://surrealdb:8000/rpc
      - SURREAL_USER=prod_user
      - SURREAL_PASSWORD=${SURREAL_PASSWORD}
      - API_CLIENT_TIMEOUT=600
      - ESPERANTO_LLM_TIMEOUT=120
      - SURREAL_COMMANDS_MAX_TASKS=10

Adding Credentials via API

Automate provider credential creation using the underlying REST API:

curl -X POST https://notebook.example.com/api/credentials \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "provider": "openai",
        "name": "prod-openai",
        "api_key": "sk-proj-xxxxxxxxxxxxxxxxxxxx",
        "metadata": {}
      }'

Testing Model Integration

Verify your production deployment with a test completion request:

curl -X POST https://notebook.example.com/api/chat \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","message":"Explain the difference between GPT-4o and GPT-4o-mini."}'

Summary

• Encryption is mandatory: Set OPEN_NOTEBOOK_ENCRYPTION_KEY before storing any credentials in production
• UI-based credential management: Use Settings → API Keys to encrypt and store provider API keys, replacing legacy environment variable approaches
• Network security: Configure API_URL and CORS_ORIGINS to restrict cross-origin requests to authorized domains
• Provider flexibility: Support for OpenAI, Anthropic, Google, Groq, OpenRouter, Azure, and self-hosted Ollama/OpenAI-compatible endpoints
• Performance tuning: Adjust API_CLIENT_TIMEOUT, ESPERANTO_LLM_TIMEOUT, and SURREAL_COMMANDS_MAX_TASKS for high-load scenarios

Frequently Asked Questions

How does Open Notebook secure API keys compared to environment variables?

Open Notebook encrypts credentials using the OPEN_NOTEBOOK_ENCRYPTION_KEY and stores them in the database rather than exposing them in environment variables. According to docs/5-CONFIGURATION/environment-reference.md, while legacy environment-variable keys remain accepted as a fallback, they are deprecated in favor of the encrypted credential database accessible through the Settings UI.

What CORS configuration is required for production deployments?

You must set CORS_ORIGINS to the exact domain of your frontend application (e.g., https://notebook.example.com). As documented in docs/5-CONFIGURATION/environment-reference.md, this whitelist prevents unauthorized cross-origin requests to your API endpoint when running in production.

Can I use self-hosted models like Ollama in production?

Yes. Configure self-hosted providers by specifying the base URL (e.g., http://ollama-host:11434) in the credential setup without requiring an API key. The system supports Ollama, LM Studio, vLLM, and other OpenAI-compatible local endpoints, as detailed in docs/5-CONFIGURATION/ai-providers.md.

Which timeout settings should I adjust for high-traffic production environments?

For high-load deployments, modify API_CLIENT_TIMEOUT (global API timeout), ESPERANTO_LLM_TIMEOUT (LLM-specific operations), and SURREAL_COMMANDS_MAX_TASKS (database concurrency limits) in your environment configuration. These settings are documented in docs/5-CONFIGURATION/advanced.md and help prevent resource exhaustion under heavy load.

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