How to Run Open Notebook with Ollama for Local AI Processing

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) and routes all language and embedding model requests to your local server via the ModelManager implementation in 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)
• 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 that launches SurrealDB, Ollama, and Open Notebook together:

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, 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:

   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:

# 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:

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:

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:

#!/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 file provides a complete local deployment stacking SurrealDB, Ollama, and Open Notebook
• Key source files include open_notebook/domain/models.py (credential storage), api/main.py (FastAPI entry point), and 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.

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