How Open Notebook Integrates with Ollama for Local AI Models

Open Notebook treats Ollama as a first-class AI provider by querying the local /api/tags endpoint to discover available models, storing connection credentials in a centralized Credential table, and validating network connectivity before registering models for language and embedding tasks.

The lfnovo/open-notebook repository implements Ollama integration using the same abstraction layer as cloud providers like OpenAI and Anthropic, but routes requests to a locally-hosted Ollama server. This allows you to run entirely local AI workflows without exposing data to external APIs, while maintaining support for both language generation and embedding models through a unified credential and discovery system.

Provider Registration and Model Discovery

Open Notebook automatically discovers Ollama models through a dedicated discovery pipeline that interrogates your local server.

The Discovery Pipeline

In open_notebook/ai/model_discovery.py, the function discover_ollama_models() performs a GET request to the Ollama /api/tags endpoint. This returns a JSON payload listing all locally available models, which the system converts into DiscoveredModel objects. Each discovered model inherits its model_type (language or embedding) through the classify_model_type utility, ensuring the correct modality is assigned before registration.

If the Ollama server requires network traversal—such as when running Open Notebook in Docker while Ollama runs on the host—the discovery mechanism respects the configured base_url, allowing cross-container or cross-host model enumeration.

Model Registration Requirements

Discovered models are persisted as Model records with provider set to "ollama". The model name must match exactly what ollama list returns, including tags like :latest. A mismatch between the registered name and the actual Ollama tag will result in a "Failed to send message" error at runtime.

Credential Management and Connection Testing

Before models can be used, Open Notebook validates that it can reach the Ollama instance through a structured credential and testing workflow.

Configuring Ollama Credentials

Credentials are managed in api/credentials_service.py, where create_credential_from_env() constructs a Credential object containing the base_url and default modalities (language and embedding). You can configure this via:

• Environment Variable: Set OLLAMA_API_BASE (e.g., http://localhost:11434) for legacy configurations
• UI Configuration: Navigate to Settings → API Keys → Add Credential → Ollama, then enter the base URL specific to your network topology

The credential stores only the connection endpoint and supported modalities—no API key is required for local Ollama instances.

Connection Validation

Before saving, the system calls _test_ollama_connection() in open_notebook/ai/connection_tester.py. This function performs a GET request to <base_url>/api/tags and expects a 200 response. Upon success, the UI displays "Connected" along with a summary of available models, preventing misconfiguration errors before they affect chat or embedding operations.

Network Configuration Scenarios

Depending on your deployment architecture, the base_url configuration varies to ensure container-to-host or container-to-container connectivity:

Scenario	Ollama Location	Base URL Configuration
Same host (no Docker)	Local binary	http://localhost:11434
Open Notebook in Docker, Ollama on host	Host machine	http://host.docker.internal:11434 (macOS/Windows) or http://host.containers.internal:11434 (Linux)
Both in Docker Compose	Service name	http://ollama:11434
Remote host	IP address	http://<host-ip>:11434

Critical: When running Ollama in Docker or binding to a specific interface, you must set OLLAMA_HOST=0.0.0.0:11434 to allow external connections. On Linux Docker hosts, you may need to add extra_hosts: ["host.docker.internal:host-gateway"] to your docker-compose.yml to resolve the host gateway correctly.

Complete Configuration Workflow

Follow these steps to activate Ollama support in Open Notebook:

1. Install and serve Ollama: Run ollama serve and ensure the server is listening on the correct interface
2. Pull required models: Download both language models (e.g., Llama 3) and embedding models (e.g., nomic-embed-text) using ollama pull
3. Add credentials: In the UI, create an Ollama credential with the appropriate base_url for your network scenario
4. Test connectivity: Verify the connection test returns model counts and names
5. Discover models: Trigger model discovery to populate the Model registry with available Ollama models
6. Set defaults: Navigate to Settings → Models to select default language and embedding providers from the discovered Ollama models

Code Examples and Implementation

Health Check Script

Verify your Ollama instance is accessible before configuring Open Notebook:

import os
import requests

base = os.getenv("OLLAMA_API_BASE", "http://localhost:11434")
resp = requests.get(f"{base}/api/tags")

if resp.status_code == 200:
    models = [m["name"] for m in resp.json()["models"]]
    print(f"Ollama is alive – models: {', '.join(models)}")
else:
    print(f"Failed to reach Ollama: {resp.status_code}")

This mirrors the internal validation logic found in open_notebook/ai/connection_tester.py.

Creating Credentials via REST API

Programmatically add an Ollama credential for Docker-based deployments:

curl -X POST http://localhost:5055/api/credentials \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Local Ollama",
        "provider": "ollama",
        "base_url": "http://host.docker.internal:11434"
      }'

This creates a Credential record equivalent to what create_credential_from_env() generates from environment variables.

Programmatic Model Discovery

Inspect available models using the same logic as discover_ollama_models():

import asyncio
import httpx

async def discover():
    base = "http://localhost:11434"
    async with httpx.AsyncClient() as client:
        resp = await client.get(f"{base}/api/tags")
        for mdl in resp.json().get("models", []):
            print(f"{mdl['name']} type: {mdl.get('model')}")

asyncio.run(discover())

Docker Compose Configuration

Run Open Notebook alongside Ollama using the official example from examples/docker-compose-ollama.yml:

services:
  open_notebook:
    image: lfnovo/open_notebook:v1-latest
    ports:
      - "8502:8502"
      - "5055:5055"
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me
      - SURREAL_URL=ws://surrealdb:8000/rpc
      - OLLAMA_API_BASE=http://ollama:11434
    depends_on:
      - surrealdb
      - ollama

  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    environment:
      - OLLAMA_HOST=0.0.0.0:11434

Summary

• Open Notebook registers Ollama as a native provider in open_notebook/ai/model_discovery.py, using discover_ollama_models() to poll the /api/tags endpoint
• Credentials are stored via create_credential_from_env() in api/credentials_service.py, supporting both environment variables and UI-based configuration with base_url and modality fields
• Connection reliability is enforced by _test_ollama_connection() in open_notebook/ai/connection_tester.py before models are registered
• Network configurations vary by deployment type, requiring specific Docker host aliases or IP addresses to bridge container and host boundaries
• Model names must exactly match Ollama's output (including tags) to avoid runtime errors

Frequently Asked Questions

Do I need an API key to connect Open Notebook to Ollama?

No. Ollama runs locally without authentication by default. Open Notebook only requires the base_url field (e.g., http://localhost:11434) configured in the Credential table. The create_credential_from_env() function in api/credentials_service.py explicitly sets this up without API key validation.

Why do I see "Failed to send message" when using an Ollama model?

This error occurs when the model name registered in Open Notebook does not exactly match the identifier returned by ollama list. The system queries /api/tags during discovery, and any deviation in tagging—for example, using llama3 instead of llama3:latest—will cause the chat completion request to fail. Verify the exact name in Settings → Models.

Can I use Ollama running on a different machine than Open Notebook?

Yes. Configure the base_url in your credential to point to the remote IP address (e.g., http://192.168.1.100:11434). Ensure the remote Ollama server is started with OLLAMA_HOST=0.0.0.0:11434 to accept external connections, and verify network accessibility using the _test_ollama_connection() routine or the health-check script above.

How do I enable embedding models from Ollama in Open Notebook?

During credential creation, the system automatically assigns language and embedding as supported modalities. After adding the credential, pull your desired embedding model (such as nomic-embed-text) using the Ollama CLI, then run model discovery. The embedding model will appear in Settings → Models and can be selected as the default embedding provider.

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