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

> Configure Open-Notebook easily by setting up environment variables, paths, and AI provider credentials. Follow our guide for a seamless setup process.

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

---

**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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/config.py) and created automatically at startup.

## Core Filesystem Paths in [`open_notebook/config.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/config.py)

The module [`open_notebook/config.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/config.py).
- **`LOG_LEVEL`** — Controls logging verbosity (`DEBUG`, `INFO`, `WARNING`). Read by [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py).
- **`MAX_WORKERS`** — Thread-pool size for background jobs such as podcast generation and embedding rebuilds. Used in [`api/podcast_service.py`](https://github.com/lfnovo/open-notebook/blob/main/api/podcast_service.py).
- **`CORS_ORIGINS`** — Comma-separated list of allowed origins for development CORS. Read by [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py).
- **`AUTH_PASSWORD`** — Simple password for the dev-only authentication middleware in [`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py).

## AI Provider and Model Configuration

### Reading Provider Keys

The `KeyProvider` class in [`open_notebook/ai/key_provider.py`](https://github.com/lfnovo/open-notebook/blob/main/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.

```python

# 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`](https://github.com/lfnovo/open-notebook/blob/main/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`.

```python
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`](https://github.com/lfnovo/open-notebook/blob/main/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:

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

```dotenv
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

```dotenv

# 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

```bash
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/key_provider.py) and [`open_notebook/ai/models.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/models.py) handle dynamic model selection and fallback logic.
- Database migrations run automatically via [`open_notebook/database/async_migrate.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.