# Open Notebook Production AI Provider Deployment and API Keys Configuration

> Discover secure production AI provider deployment for Open Notebook. Learn how to configure API keys using an encrypted database and CORS settings for maximum security.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: how-to-guide
- Published: 2026-06-19

---

**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`](https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/environment-reference.md), you must set this variable in your deployment manifest (e.g., [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) with the required encryption and networking variables:

```yaml
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:

```bash
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:

```bash
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/advanced.md) and help prevent resource exhaustion under heavy load.