# How to Run Open Notebook with Ollama for Local AI Processing

> Learn to run Open Notebook with Ollama for local AI processing. Configure Ollama credentials, match model names, and deploy using Docker Compose for seamless local AI.

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

---

**To run Open Notebook with Ollama for local AI processing, configure an Ollama credential in the Settings → API Keys UI with your Ollama server URL (typically `http://localhost:11434`), ensure model names match exactly with `ollama list` output, and use the provided Docker Compose file to orchestrate SurrealDB, Ollama, and the Open Notebook services.**

Open Notebook is a three-tier system comprising a **Next.js frontend**, a **FastAPI backend**, and a **SurrealDB graph database**. According to the `lfnovo/open-notebook` source code, the backend uses the **Esperanto** library to communicate with LLM providers, making it straightforward to connect to a locally-hosted Ollama instance for fully private AI processing.

## Architecture Overview

### The Three-Tier System

The application architecture consists of distinct layers that communicate via HTTP APIs:

- **Frontend** (`frontend/`): The Next.js UI for notebooks, sources, chat, and podcast generation calls the REST API at `http://localhost:5055` (default)
- **API** (`api/` and `open_notebook/`): FastAPI endpoints (`/chat`, `/ask`, `/transformations`) and LangGraph workflows that orchestrate extraction, embedding, and generation
- **Database** (`surrealdb/`): Stores notebooks, sources, embeddings, and credentials including the Ollama configuration

### How Ollama Fits In

The backend integrates with Ollama through the **Esperanto** library, which proxies requests to the Ollama HTTP API endpoints (`/api/generate`, `/api/tags`). When you add an Ollama credential with provider name "ollama", the system stores the base URL in a `Credential` record in SurrealDB (defined in [`open_notebook/domain/models.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/domain/models.py)) and routes all language and embedding model requests to your local server via the `ModelManager` implementation in [`open_notebook/ai/model_manager.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/model_manager.py).

## Network Configuration for Ollama

Because Ollama binds only to `localhost` by default, you must configure the correct base URL based on your deployment scenario:

- **Ollama on same host as Open Notebook (no Docker)**: `http://localhost:11434`
- **Open Notebook in Docker, Ollama on host (Linux)**: `http://host.docker.internal:11434` (requires `extra_hosts: ["host.docker.internal:host-gateway"]` in [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml))
- **Both services in same Docker Compose stack**: `http://ollama:11434`
- **Remote Ollama server**: `http://<IP-ADDRESS>:11434`

For Docker deployments, the container cannot reach `localhost` on the host, so you must either expose Ollama on all interfaces using `OLLAMA_HOST=0.0.0.0:11434` or use the Docker-specific hostname.

## Docker Compose Setup

The repository provides a ready-made orchestration file at [`examples/docker-compose-ollama.yml`](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml) that launches SurrealDB, Ollama, and Open Notebook together:

```yaml
services:
  surrealdb:
    image: surrealdb/surrealdb:v2
    command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
    ports: ["8000:8000"]
    volumes: ["./surreal_data:/mydata"]
    restart: always

  ollama:
    image: ollama/ollama:latest
    ports: ["11434:11434"]
    volumes: ["ollama_models:/root/.ollama"]
    restart: always

  open_notebook:
    image: lfnovo/open-notebook:v1-latest
    ports: ["8502:8502", "5055:5055"]
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string
      - SURREAL_URL=ws://surrealdb:8000/rpc
      - SURREAL_USER=root
      - SURREAL_PASSWORD=root
      - SURREAL_NAMESPACE=open_notebook
      - SURREAL_DATABASE=open_notebook
      - OLLAMA_BASE_URL=http://ollama:11434
    volumes: ["./notebook_data:/app/data"]
    depends_on: [surrealdb, ollama]
    restart: always

volumes:
  ollama_models:

```

Save this as [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml), update the encryption key, and run `docker compose up -d`. Once containers are healthy, access the UI at `http://localhost:8502`.

## Configuring Models in Open Notebook

Open Notebook does not rewrite model names. You must use the exact string shown by the `ollama list` command (e.g., `qwen3:latest` or `mxbai-embed-large:latest`). A mismatch causes "Failed to send message" errors.

### Typical Workflow

1. **Pull models** inside the Ollama container:
   ```bash
   docker exec <ollama-container-name> ollama pull qwen3
   docker exec <ollama-container-name> ollama pull mxbai-embed-large
   ```

2. **Add language model**: In the UI, navigate to **Settings → Models → Add Model**, enter the exact name (`qwen3:latest`), select provider `ollama`, and mark as default chat model.

3. **Add embedding model**: Repeat the process for the embedding model and set it as the default "search embedding" model.

4. **Verify credential**: Ensure **Settings → API Keys** contains your Ollama base URL (`http://ollama:11434` for the Docker Compose setup above).

## Verification and Testing

Verify Ollama connectivity before adding models to Open Notebook:

```bash

# Check if Ollama is reachable

curl -s http://localhost:11434/api/tags | jq '.models[].name'

```

If running inside the Open Notebook container, replace `localhost` with the configured hostname (`host.docker.internal` or `ollama`).

For Python-based verification or custom scripts:

```python
import os, requests

OLLAMA_BASE = os.getenv("OLLAMA_API_BASE", "http://localhost:11434")

# List available models

resp = requests.get(f"{OLLAMA_BASE}/api/tags")
print("Available models:", [m["name"] for m in resp.json()["models"]])

# Test generation

payload = {
    "model": "qwen3:latest",
    "prompt": "Explain why local AI is useful",
    "stream": False,
}
generated = requests.post(f"{OLLAMA_BASE}/api/generate", json=payload).json()
print(generated["response"])

```

## Troubleshooting Common Issues

### Model Name Mismatch

The most common error occurs when the model name in Open Notebook does not match Ollama's exact identifier. Always verify with:

```bash
ollama list

# Use the full string including tags (e.g., "qwen3:latest", not just "qwen3")

```

### Network Connectivity

When Open Notebook runs in Docker but Ollama runs on the host, ensure Ollama is accessible:
- Set `OLLAMA_HOST=0.0.0.0:11434` when starting Ollama to expose it on all interfaces, or
- Use `host.docker.internal` with proper Docker Compose configuration

### Health Check Script

Use this bash script to verify connectivity before configuring Open Notebook:

```bash
#!/usr/bin/env bash
set -e
BASE=${OLLAMA_API_BASE:-http://localhost:11434}
echo "Checking Ollama..."
if curl -s "${BASE}/api/tags" > /dev/null; then
  echo "✅ Ollama is running"
  curl -s "${BASE}/api/tags" | jq -r '.models[].name'
else
  echo "❌ Ollama not reachable at ${BASE}"
  exit 1
fi

```

## Summary

- **Open Notebook** uses a three-tier architecture (Next.js, FastAPI, SurrealDB) with the **Esperanto** library handling LLM provider abstraction
- Configure the **Ollama base URL** in Settings → API Keys based on your deployment topology (localhost, Docker internal networking, or remote host)
- Use **exact model names** from `ollama list` when registering models to avoid "Failed to send message" errors
- The [`examples/docker-compose-ollama.yml`](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml) file provides a complete local deployment stacking SurrealDB, Ollama, and Open Notebook
- Key source files include [`open_notebook/domain/models.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/domain/models.py) (credential storage), [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) (FastAPI entry point), and [`open_notebook/ai/model_manager.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/model_manager.py) (provider mapping)

## Frequently Asked Questions

### How do I fix "Failed to send message" errors when using Ollama?

This error typically indicates a model name mismatch. Open Notebook passes the model name directly to Ollama without modification, so you must enter the exact string shown by `ollama list` (including the tag, such as `qwen3:latest` rather than `qwen3`). Verify the name in the UI matches the Ollama output character-for-character.

### Can I run Open Notebook with Ollama without Docker?

Yes. Install SurrealDB locally, start Ollama on your host machine (`ollama serve`), and run the Open Notebook backend directly. Set the Ollama credential URL to `http://localhost:11434` in the UI settings. Ensure you have the proper Python dependencies installed as specified in the repository's requirements.

### Why can't Open Notebook connect to Ollama when running in Docker?

By default, Ollama binds only to `localhost`, which is not accessible from inside Docker containers. You must either set `OLLAMA_HOST=0.0.0.0:11434` when starting Ollama to expose it on all interfaces, or use `http://host.docker.internal:11434` (with `extra_hosts` configuration on Linux) to reach the host from within the container.

### Which embedding models work with Open Notebook and Ollama?

Any Ollama-compatible embedding model works, provided you use the exact model name. The documentation recommends `mxbai-embed-large:latest` for good performance, but you can use `nomic-embed-text`, `all-minilm`, or others. Register the model in Settings → Models as the default "search embedding" model after pulling it with `ollama pull`.