The cleanest path for any host — Linux, macOS, Windows, or a NAS. This guide covers the four-step Docker Compose install, connecting to Ollama on the host via host.docker.internal, NVIDIA GPU passthrough, volume persistence, and every error you'll hit along the way.
The Docker install is the simplest path to Odysseus AI, but it has three real prerequisites. Get all three sorted before the install and the rest takes five minutes.
On Linux, install Docker Engine and the Compose plugin. On macOS and Windows, Docker Desktop ships both. Verify both are present:
If docker compose (with a space) is unknown but docker-compose works, you're on the legacy v1 binary. Upgrade — Odysseus AI's compose file uses v2 syntax for healthchecks and depends_on.
Odysseus AI itself runs comfortably in 1 GB. The headroom is for model loading — even quantized 7B models need ~5 GB of RAM at inference time. If you also run Ollama in Docker on the same host, double that estimate. On Docker Desktop, raise the memory limit in Settings → Resources before installing.
Odysseus AI in Docker can talk to (a) Ollama on the host machine, (b) Ollama in a sibling container, or (c) cloud APIs like OpenAI and Anthropic. The simplest setup is option (a) — install Ollama natively on the host, then bridge from the container. The Ollama bridge section covers the exact configuration.
These commands are identical on Linux, macOS, and Windows. Open your terminal in a folder where you want the project to live.
If Docker Desktop, make sure the app is open and shows green. On Linux, the daemon should be active.
If you see "Cannot connect to the Docker daemon", start the daemon (Linux: sudo systemctl start docker) or launch Docker Desktop.
Always clone from pewdiepie-archdaemon/odysseus — the active official repo. Mirror and impostor repos exist; verify before running anything in production.
The official docker-compose.yml in the repo handles everything — image pull, network, volumes, healthcheck. The -d flag runs detached so your terminal stays free.
First boot pulls images (~600 MB) and may take 3–8 minutes on slower connections. Watch for the line "Uvicorn running on http://0.0.0.0:7000" — that's the signal Odysseus AI is ready.
The admin password is printed in the container logs on first boot. Find it, save it somewhere safe, then open the browser.
Log in as admin using the password you just retrieved. The model dropdown will be empty — the next sections wire up Ollama and APIs.
The official compose file works fine, but most users want to customize ports, volumes, GPU access, or the Ollama bridge. This generator outputs a clean, opinionated compose file tailored to your setup.
Pick six options and copy a working compose file. All defaults are sensible — change only what you need.
Save this as docker-compose.yml in the project folder, then run docker compose up -d.
This is the single most common Docker confusion. Inside a container, localhost refers to the container itself — not your host machine. You have to use the special Docker hostname that points back to the host.
Docker Desktop ships with host.docker.internal pre-configured. Just use it as the host in your Ollama URL:
Linux Docker does not ship host.docker.internal. Without it, Docker Odysseus AI cannot reach the host's Ollama. Add the alias via extra_hosts in your compose file:
The host-gateway magic value tells Docker to resolve to the host's bridge IP automatically. After adding, run docker compose up -d to recreate the container. Verify connectivity:
If you get JSON back listing your Ollama models, the bridge is working.
If you'd rather run Ollama inside Docker too, the compose generator above includes that option. Both services join the same Docker network, and Odysseus AI talks to Ollama via its service name (ollama) instead of host.docker.internal. The trade-off: sibling Ollama can't share models with native Ollama on the host, so you'll re-pull each model.
GPU acceleration in Docker requires one piece of software on the host: the NVIDIA Container Toolkit. After installation, any container can request GPU access via the standard --gpus flag or compose syntax.
If you see your GPU listed, you're set. If not, check the NVIDIA driver version on the host (nvidia-smi directly) — the toolkit needs driver 525+ for CUDA 12.
The compose generator above adds this automatically when you pick NVIDIA. The relevant snippet:
On macOS, GPU passthrough to Docker containers is not supported — Docker Desktop on Mac runs in a VM that doesn't expose the Metal GPU. Use native install (not Docker) for GPU acceleration on Apple Silicon. On Windows, GPU passthrough works via WSL2 — Docker Desktop with WSL2 backend.
The diagnostic matches your error against 12 known Docker-specific Odysseus AI failure patterns and returns the exact command to fix it. Runs entirely in your browser.
Run docker compose logs odysseus, copy the failing lines, paste below, click match.
Docker containers are ephemeral by design — every restart starts from a clean image. Your Odysseus AI chats, settings, uploaded files and API keys live in named volumes that survive container recreation. Get this wrong and you'll lose everything on the first docker compose down -v.
The official compose file declares two named volumes: odysseus-data for the SQLite database and uploaded files, and odysseus-config for settings and API keys. Docker manages them in /var/lib/docker/volumes/ on Linux, or inside the Docker Desktop VM on macOS / Windows.
If you want to browse the data directly with your file manager, use a bind mount to a host directory instead. The compose generator above switches to this style when you pick "Bind mount". Trade-off: bind mounts can have permission issues on Linux if the container user UID doesn't match the host directory owner.
-v with downdocker compose down stops and removes containers but keeps volumes. docker compose down -v also deletes the volumes. The latter wipes your entire Odysseus AI workspace — chats, settings, files, everything. Only run it when you genuinely want to reset.
The official Docker setup works on every common NAS platform. Below are platform-specific notes for the three most popular — what to do differently from a generic Linux host.
Add a custom Docker container via the UI, or paste the official compose file into the Compose Manager plugin. Set the container path to /mnt/user/appdata/odysseus for native NVMe cache support.
Use Container Manager (formerly Docker package). Import the compose file via Project → Create → upload docker-compose.yml. Synology assigns containers UID 1000 by default — set the same UID for bind mount directories.
TrueNAS Scale runs on k3s, not vanilla Docker. The simplest path is a custom app definition that wraps the compose file. Future versions of Scale have native compose support — check your current TrueNAS version's app catalogue.
// landfall checklist
docker compose ps shows odysseus as healthyhttp://localhost:7000 (or your custom port) opens the login pagedocker compose logsdocker volume ls and confirmed the named volumes existThese cover about 90% of failed Odysseus AI Docker installs. Match your output against the error message in each card.
The Docker daemon isn't running. On Linux, start it via systemd. On macOS or Windows, launch the Docker Desktop app.
Your user isn't in the docker group on Linux. Either add the user, or prefix every command with sudo (not recommended for daily use).
NVIDIA Container Toolkit isn't installed on the Docker host. Without it, Docker can't talk to the NVIDIA driver no matter how new the GPU is.
Another process — often a previous Odysseus AI container that didn't stop cleanly — is holding the port. Find it and free it, or change the port mapping in the compose file.
The container hit its memory limit. Either no limit was set and the host ran out, or you set a limit that's too low for the model in use.
Docker's storage area is full — common after pulling many images and downloading models. Prune unused data.
http://host.docker.internal:11434/v1 in Odysseus AI Settings → Providers. On macOS and Windows that hostname works out of the box. On Linux Docker, you must add extra_hosts: - "host.docker.internal:host-gateway" to the compose file because Linux Docker doesn't ship this alias by default.git pull in the project folder, then docker compose pull (if you're using a registry image) or docker compose build (if building from source), followed by docker compose up -d. Your volumes survive, so all chat history and settings are preserved.docker pull --platform linux/amd64 image:tag as a fallback — it'll run via Rosetta emulation, slower but functional.ports: mapping so the container is only reachable on the internal Docker network. Add Traefik labels (or join an Nginx Proxy Manager network). The compose generator above offers a "behind reverse proxy" toggle that produces the right configuration for Traefik out of the box.docker compose -p name1 up -d and map them to different ports. The volumes and networks are namespaced by project name so they don't collide. Useful for testing upgrades or running separate workspaces for different teams.docker run --rm -v odysseus-data:/data -v $(pwd):/backup alpine tar czf /backup/backup.tar.gz -C /data . creates a portable backup. Restore by extracting the tarball into a new volume before starting the container.