How to Configure Open-Notebook: Environment Variables, Paths, and Provider Setup

You configure Open-Notebook by copying .env.example to .env, filling in your SurrealDB credentials and at least one AI provider API key, and verifying that the folders defined in open_notebook/config.py are writable by the process.

Open-Notebook is a multi-tier, self-hosted AI research assistant built around SurrealDB and LangGraph. When you configure open-notebook, every runtime setting is supplied through environment variables read via os.getenv, plus a small set of filesystem constants in the source code. The repository provides a ready-made template at .env.example, while core paths are declared in open_notebook/config.py and created automatically at startup.

Core Filesystem Paths in open_notebook/config.py

The module open_notebook/config.py defines the runtime directory layout and ensures required folders exist by calling os.makedirs(..., exist_ok=True) on startup.

The key constants are:

• DATA_FOLDER — Root folder for all runtime data. Defaults to "./data".
• UPLOADS_FOLDER — Storage location for uploaded PDFs, audio, video, and other assets.
• LANGGRAPH_CHECKPOINT_FILE — SQLite file used by LangGraph to persist workflow state.
• TIKTOKEN_CACHE_DIR — Cache directory for the tiktoken tokenizer. You can override this by setting the TIKTOKEN_CACHE_DIR environment variable.

You do not need to create these directories manually; you only need to ensure the process has write access to ./data or to any custom location you set.

Mandatory Environment Variables (.env)

Open-Notebook reads every option via os.getenv. Copy the provided .env.example to .env and populate the mandatory fields before starting the stack:

• SURREAL_URL — URL of the SurrealDB instance, including port (for example, http://localhost:8000). Used in open_notebook/database/repository.py.
• SURREAL_USER — Username for SurrealDB authentication.
• SURREAL_PASS — Password for SurrealDB authentication.
• OPENAI_API_KEY (or ANTHROPIC_API_KEY, etc.) — API key for your chosen AI provider. The KeyProvider class in open_notebook/ai/key_provider.py supports eight providers through the Esperanto library, but you only need to set one.
• MODEL_NAME — Default LLM identifier (for example, gpt-4o, claude-3-sonnet-20240229). Consumed by open_notebook/ai/models.py.
• BASE_API_URL — Public base URL for the FastAPI server (for example, http://localhost:5055). The Next.js frontend references this via NEXT_PUBLIC_API_URL in frontend/.env.local.

Optional and Advanced Environment Variables

For Docker deployments, debugging, or custom networking, the following variables fine-tune behavior:

• TIKTOKEN_CACHE_DIR — Redirects the tokenizer cache (useful in read-only or Docker contexts). Read in open_notebook/config.py.
• LOG_LEVEL — Controls logging verbosity (DEBUG, INFO, WARNING). Read by api/main.py.
• MAX_WORKERS — Thread-pool size for background jobs such as podcast generation and embedding rebuilds. Used in api/podcast_service.py.
• CORS_ORIGINS — Comma-separated list of allowed origins for development CORS. Read by api/main.py.
• AUTH_PASSWORD — Simple password for the dev-only authentication middleware in api/auth.py.

AI Provider and Model Configuration

Reading Provider Keys

The KeyProvider class in open_notebook/ai/key_provider.py abstracts credential lookup. It first checks the environment for a provider-specific variable, then falls back to stored credentials in SurrealDB.

# From open_notebook/ai/key_provider.py

class KeyProvider:
    @staticmethod
    def get_key(provider: str) -> str | None:
        env_var = f"{provider.upper()}_API_KEY"
        return os.getenv(env_var)  # ← reads from .env

Because Esperanto supports multiple providers, you only need to export the key that matches the backend you intend to use.

Model Selection and Fallbacks

ModelManager in open_notebook/ai/models.py instantiates the LLM using MODEL_NAME and the active provider key. If a request exceeds the selected model’s context window, the manager automatically falls back to a long-context variant such as gpt-4-turbo-preview.

from open_notebook.ai.models import ModelManager

model = ModelManager.get_model()  # respects MODEL_NAME & provider keys

response = model.chat(messages=[{"role": "user", "content": "Explain LangGraph."}])
print(response.content)

Database Migration Behavior

On API startup, AsyncMigrationManager in open_notebook/database/async_migrate.py runs pending SurrealQL migrations from the migrations/ folder automatically.

You can control this with two environment variables:

• SKIP_MIGRATIONS — Set to 1 to skip migrations (useful for read-only containers).
• MIGRATION_LOG — Path for migration output; defaults to ./data/migration.log.

To run migrations manually:

uv run python -m open_notebook.database.async_migrate

The script checks SKIP_MIGRATIONS before executing any SurrealQL files.

Front-End Connection Settings

The React/Next.js UI does not share the backend .env. Instead, it reads NEXT_PUBLIC_API_URL from frontend/.env.local.

NEXT_PUBLIC_API_URL=http://localhost:5055

Update this file whenever the FastAPI server runs on a non-default port or behind a reverse proxy.

Step-by-Step: Start the Configured Stack

1. Prepare the environment. Copy .env.example to .env and fill in the mandatory variables.
2. Verify paths. Ensure the process can write to ./data (or override DATA_FOLDER).
3. Start SurrealDB. For example: surreal start --bind 0.0.0.0:8000.
4. Launch the API. For example: uvicorn api.main:app --reload --port 5055.
5. Start the frontend. Inside frontend/, run npm run dev.

All components pick up their configuration automatically on boot.

Configuration Code Examples

Minimal .env for Local Development

# Database

SURREAL_URL=http://localhost:8000
SURREAL_USER=root
SURREAL_PASS=mysupersecret

# AI provider (choose one)

OPENAI_API_KEY=sk-****************************************

# Model

MODEL_NAME=gpt-4o

# Optional – change data locations

DATA_FOLDER=./my_data
TIKTOKEN_CACHE_DIR=./my_data/tiktoken-cache

Docker Override for Token Cache

docker run -e TIKTOKEN_CACHE_DIR=/cache/tiktoken \
           -v $(pwd)/data:/cache \
           lfnovo/open-notebook:latest

The TIKTOKEN_CACHE_DIR variable is read in open_notebook/config.py around lines 19–20.

Summary

• All backend configuration for open-notebook lives in environment variables; copy .env.example to .env to get started.
• Core filesystem paths such as DATA_FOLDER and UPLOADS_FOLDER are defined in open_notebook/config.py and created automatically at startup.
• You must supply SurrealDB credentials (SURREAL_URL, SURREAL_USER, SURREAL_PASS) and at least one AI provider key (for example, OPENAI_API_KEY).
• The KeyProvider and ModelManager classes in open_notebook/ai/key_provider.py and open_notebook/ai/models.py handle dynamic model selection and fallback logic.
• Database migrations run automatically via open_notebook/database/async_migrate.py unless SKIP_MIGRATIONS=1 is set.
• The Next.js frontend requires its own frontend/.env.local with NEXT_PUBLIC_API_URL pointing to the running FastAPI server.

Frequently Asked Questions

What happens if I do not set DATA_FOLDER?

If you omit DATA_FOLDER, open-notebook falls back to the default "./data" as defined in open_notebook/config.py. The directory is created automatically with os.makedirs(..., exist_ok=True), so the application will start as long as the process has write permissions to that location.

Can I use multiple AI providers at the same time?

The KeyProvider class reads one key per provider from environment variables shaped like {PROVIDER}_API_KEY, and the Esperanto library supports eight providers. However, the active model for a given request is controlled by MODEL_NAME and the ModelManager, so while credentials for multiple providers can exist, the default behavior targets the single model configured in MODEL_NAME.

How do I disable automatic database migrations?

Set the environment variable SKIP_MIGRATIONS=1 before starting the API. When this variable is present, AsyncMigrationManager in open_notebook/database/async_migrate.py skips running SurrealQL migration files on startup, which is useful for read-only or ephemeral containers.

Why does the frontend not pick up changes to the backend .env?

The React/Next.js frontend is a separate build that reads NEXT_PUBLIC_API_URL from frontend/.env.local, not from the backend .env file. If you change the FastAPI port or host, you must update frontend/.env.local and restart the frontend dev server so the browser can reach the correct API endpoint.

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