9 min read June 7, 2026

Odysseus AI Ollama Setup: Connect Local Models Without Guesswork

A practical setup guide for pointing Odysseus AI at an existing Ollama server, with separate Docker and native paths, endpoint checks, and fixes for the errors people hit first.

Odysseus AI Wiki
Odysseus AI Wiki
Fan-made editorial notes based on public Odysseus AI documentation and local self-hosting patterns.
Diagram showing Odysseus AI connecting to Ollama through localhost and Docker host endpoint

Short answer: If Odysseus AI runs in Docker and Ollama runs on your host machine, use http://host.docker.internal:11434/v1 in Odysseus Settings. If both run natively on the same machine, localhost is usually correct. The most common failure is using the right port from the wrong network namespace.

In this guide

Odysseus AI is a self-hosted workspace, while Ollama is a local model server. They work well together, but the connection is easy to misread because Docker changes what localhost means. This guide keeps the goal narrow: make Odysseus AI see models already served by Ollama, then verify the connection before you debug anything higher up the stack.

Use the endpoint that matches where Odysseus AI runs

The official Odysseus README calls out a Docker-specific Ollama endpoint: when Ollama runs on the host and Odysseus runs in a container, add the host endpoint in Settings. That endpoint is not a magic model name; it is the network address that lets a container reach a service running on the host.

For Docker installs, the practical default is host.docker.internal on port 11434 with the OpenAI-compatible /v1 path. For native installs where Odysseus AI and Ollama run on the same operating system session, start with localhost or 127.0.0.1 instead. Choose one path first, then test it directly before changing model settings.

Treat “install Ollama” and “connect Odysseus AI to Ollama” as two separate checks. First confirm the Ollama service answers on port 11434 and has at least one model available. Then enter the reachable endpoint from the same runtime layer as Odysseus AI; do not copy a localhost URL across Docker, WSL2, and the host without testing it.

Docker to host Ollama endpoint
http://host.docker.internal:11434/v1

Docker setup: Odysseus container to host Ollama

This is the highest-value setup because many people follow the recommended Docker path for Odysseus AI but already have Ollama installed on the host. In that layout, localhost inside the container points back to the container, not to your laptop or workstation.

The connection has three parts: Ollama must be running, it must listen on an address the container can reach, and Odysseus AI must store the correct endpoint in Settings.

1. Start Ollama so it listens beyond its own loopback when needed

If Docker cannot reach Ollama, start Ollama with an explicit host binding. Keep this binding limited to trusted local use unless you understand your network exposure.

OLLAMA_HOST=0.0.0.0:11434 ollama serve

2. Confirm Ollama has at least one model

Odysseus AI can connect to the endpoint and still show no useful model if Ollama has not pulled anything yet. Pull a small model first if you are only testing the connection.

ollama list
ollama pull llama3.2:3b

3. Put the Docker endpoint in Odysseus AI Settings

Use the OpenAI-compatible base URL in the model or service settings area. Do not use localhost for this Docker-to-host layout unless your Docker platform has been configured differently.

http://host.docker.internal:11434/v1

4. Check container health before debugging prompts

If the Odysseus service is degraded, fix that first. A model endpoint cannot repair a broken container startup, missing environment file, or unhealthy dependency.

docker compose ps
docker compose logs --tail=120 odysseus

Native setup: Windows, Linux, and macOS endpoint choices

When Odysseus AI and Ollama both run natively on the same machine, you usually do not need host.docker.internal. You are no longer crossing from a container into the host, so localhost normally means the machine you expect.

Platform-specific launch scripts can still change ports for the Odysseus web app itself, but the Ollama API is normally on 11434 unless you changed OLLAMA_HOST.

Setup Endpoint to try first What to watch
Windows native Odysseus + Windows Ollama http://127.0.0.1:11434/v1 Use localhost when both services run natively on the same Windows machine.
Linux native Odysseus + Ollama http://127.0.0.1:11434/v1 Check service permissions if either process runs as a background service.
macOS or Apple Silicon native path http://127.0.0.1:11434/v1 The Odysseus UI port can differ, but Ollama usually remains on 11434.
Odysseus in Docker + host Ollama http://host.docker.internal:11434/v1 Use the Docker host name because container localhost is not the host machine.

Troubleshooting Odysseus AI and Ollama connection errors

Work from the network layer upward. First prove Ollama answers locally, then prove Docker can reach it, then adjust Odysseus model settings. Randomly changing model names or ports usually makes the problem harder to isolate.

Symptom Likely cause Fix
Connection refused Ollama is not running or is listening only where Odysseus cannot reach it. Start Ollama, confirm port 11434, and use an explicit OLLAMA_HOST binding for Docker-to-host testing.
Host browser works but Docker fails The endpoint uses localhost inside the container. Switch the endpoint to http://host.docker.internal:11434/v1.
No model appears No model has been pulled or the model tag is wrong. Run ollama list, pull a small model, and select the exact tag.
Slow first response The model is loading or too large for the machine. Test a smaller model before agents, tools, or documents.
Unexpected LAN exposure A service was bound to all interfaces without a trust boundary. Return to localhost-only binding unless firewall, VPN, and auth are intentional.

Final verification checklist before you trust the setup

A working setup should pass these checks in order. Stop at the first failure and fix that layer instead of jumping ahead.

  1. Ollama responds on the host and ollama list shows a model.
  2. The Odysseus service is healthy in Docker or native logs.
  3. The endpoint matches the runtime layout.
  4. A small prompt works before larger agents or document workflows.
  5. Any LAN exposure is authenticated and intentional.
Keep the first setup local

Connecting Odysseus AI to Ollama does not require publishing either service to the public internet. Keep both local until authentication, firewall rules, and reverse proxy behavior are deliberate.

2026 verification notes before changing the endpoint

Before you edit Odysseus AI settings, verify the runtime boundary. The same Ollama server can require a different base URL depending on whether Odysseus runs natively, in Docker, or on another host.

Use the checks below to avoid the most common false fix: changing model names when the real issue is that the app cannot reach port 11434 from its own network namespace.

Check Good result What to do if it fails
Host Ollama API The host can reach http://127.0.0.1:11434 before Odysseus is involved. Start Ollama, pull a small model, and test the API outside Odysseus first.
Docker-to-host route A containerized Odysseus setup uses host.docker.internal:11434/v1. Do not use localhost from inside the container unless Ollama also runs in that container network.
Native route A native Odysseus setup uses 127.0.0.1:11434/v1 when Ollama is on the same machine. Remove Docker-specific hostnames from native settings and test with a small prompt.
  1. Keep Ollama local while testing unless you intentionally configured firewall and authentication rules.
  2. Confirm the selected model tag exists in ollama list before troubleshooting Odysseus prompts.
  3. Record which endpoint worked so future Docker or native migrations do not inherit the wrong URL.

Odysseus AI Ollama FAQ

Because localhost inside a container points to the container itself. host.docker.internal is Docker's hostname for reaching the host machine from inside the container.

Use the OpenAI-compatible base URL form when Odysseus expects an OpenAI-style provider endpoint. For the Docker host setup, that means http://host.docker.internal:11434/v1.

No. Ollama is a separate model server in this setup. Odysseus AI connects to it; it does not start Ollama inside the container.

If both Odysseus AI and Ollama run natively on Windows, try http://127.0.0.1:11434/v1 first. Use host.docker.internal only when Odysseus is in Docker and Ollama is on the host.

The endpoint may be reachable while the chosen model is missing, too large, or loading slowly. Check ollama list, pull a small model, and test with the exact model tag.

No. Ollama is a separate model server. Install and test Ollama first, pull a model, then configure Odysseus AI to use the endpoint that is reachable from its own runtime layer.

Sources and official references

  1. Official Odysseus AI GitHub repository - Docker, Windows, Apple Silicon, and Ollama endpoint guidance.
  2. Ollama API documentation - Local model server API behavior.
  3. Docker Desktop networking documentation - host.docker.internal host networking behavior.

Related Odysseus AI setup paths

2026-07-11

Back to the Odysseus AI Wiki