# How Open Notebook Integrates with Ollama for Local AI Models

> Learn how Open Notebook integrates seamlessly with Ollama to manage and utilize your local AI models. Discover available models, store credentials, and validate connections effortlessly.

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

---

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

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

### Creating Credentials via REST API

Programmatically add an Ollama credential for Docker-based deployments:

```bash
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()`:

```python
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`](https://github.com/lfnovo/open-notebook/blob/main/examples/docker-compose-ollama.yml):

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