Odysseus Troubleshooting

Pick where you're stuck, paste an error log, or jump to a fix below.

Where are you stuck?

Before install

Git, Python, PowerShell

During install

Clone, Docker, ports

No AI model

Ollama, GPU, Cookbook

Admin password, can't sign in

Just installed?

First-week checklist

Paste an error log

Paste a few lines from PowerShell, Docker, or Odysseus logs. We'll suggest the closest fix — no data is sent anywhere.

Quick answer

Odysseus is early software (released May 2026). Most issues have known fixes — try a match above before opening a GitHub issue. Just finished install? First-week checklist →

Before install

PowerShell blocks launch-windows.ps1

Before install — launcher script

Symptom: Execution policy error on Windows.

terminal

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

During install

Official repo fails on Windows

Install step 1 — clone / setup errors

Symptom: Path or dependency errors with pewdiepie-archdaemon/odysseus on native Windows.

terminal

# Try the one-command launcher first:
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

# Still failing? Use the Windows fork:
git clone -b main https://github.com/amish-github/odysseus.git
cd odysseus
# Continue from venv step on /install/windows

Port 7000 already in use

Install step 4 — start server

Symptom: Server fails to start — address already in use. On Mac, AirPlay often holds 7000.

terminal

# Docker: edit .env
APP_PORT=7001

docker compose down
docker compose up -d --build

# Native Windows: change port in uvicorn command
python -m uvicorn app:app --host 127.0.0.1 --port 8000

# macOS: use official script (port 7860) instead of fighting AirPlay
./start-macos.sh
# Open http://127.0.0.1:7860

macOS — page not on port 7000

After start-macos.sh

Symptom: localhost:7000 fails; AirPlay holds the port.

terminal

# Official macOS script serves on 7860:
./start-macos.sh
# Open http://127.0.0.1:7860

# To use 7000: turn off AirPlay Receiver, then set APP_PORT=7000.

No AI model

Docker can't see NVIDIA GPU

After Docker install — Cookbook / GPU

Symptom: Cookbook shows wrong GPU or 0 VRAM. Chat says no models.

terminal

# Official path — use the GPU overlay (do not hand-edit deploy.resources):

# Diagnose / install toolkit helpers:
scripts/check-docker-gpu.sh --print-install-commands

# Enable overlay after passthrough works (writes COMPOSE_FILE in .env):
scripts/check-docker-gpu.sh --enable-nvidia-overlay

# Or set manually in .env:
# COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml

docker compose down
docker compose up -d --build
docker compose exec odysseus nvidia-smi -L

# Stack UIs needing one file: docker-compose.gpu-nvidia.yml
# Apple Silicon: Docker cannot use Metal — use ./start-macos.sh instead.

Cookbook downloaded model but chat shows 'No models'

Install step 8–9 — no model in dropdown

Symptom: Model downloaded to disk but not served or not visible in chat.

terminal

1. In Cookbook, click "Serve" on the downloaded model — wait for it to finish
2. Check terminal/logs for errors (HF token, VRAM insufficient)
3. Alternatively: install Ollama, pull a model, add endpoint in Settings
4. For Docker + Ollama on host: use http://host.docker.internal:11434/v1

Ollama connection fails from Docker

Install step 8 — Settings endpoint

Symptom: Odysseus in Docker can't reach Ollama on localhost.

terminal

# Wrong (inside container):
http://localhost:11434/v1

# Correct:
Windows/Mac Docker: http://host.docker.internal:11434/v1
Linux Docker:       http://172.17.0.1:11434/v1

# Ollama may need: OLLAMA_HOST=0.0.0.0:11434 ollama serve
Verify Ollama is running: ollama list

nvidia-smi works but Cookbook still on CPU

After enabling Docker GPU overlay

Symptom: Passthrough OK, but Cookbook logs: cudart / CUDA Toolkit not found.

terminal

# GPU passthrough ≠ CUDA-enabled llama.cpp build.

# If logs mention: Unable to find cudart, CUDA Toolkit not found, layers on CPU:
# Reinstall the serve engine via Cookbook → Dependencies (CUDA build).

# Confirm device first:
docker compose exec odysseus nvidia-smi -L

# Overlay reminder:
# COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml
# See /install/docker

Login & password

Lost admin password — reset auth.json

After install — cannot log in

Symptom: Temporary password lost; .env password change ignored after first boot.

terminal

# Find password first (often still in logs):
docker compose logs odysseus | Select-String -Pattern "password"
# Mac/Linux: docker compose logs odysseus | grep -i password

# If still lost — reset (creates a NEW password):
docker compose down
mv data/auth.json data/auth.json.bak
docker compose up -d
docker compose logs odysseus | Select-String -Pattern "password"

# Note: ODYSSEUS_ADMIN_PASSWORD in .env only applies before first boot.

After install (common traps)

AUTH_ENABLED=false ignored (Windows .env BOM)

After editing .env in Notepad

Symptom: Still forced to log in; env keys seem ignored.

terminal

# Notepad may save UTF-8 with BOM, turning AUTH_ENABLED into AUTH_ENABLED.

# Fix: re-save .env as UTF-8 without BOM
# VS Code: Save with Encoding → UTF-8
# Or recreate from .env.example and re-apply edits carefully.

# Prefer keeping AUTH_ENABLED=true for any non-toy setup.
# See /security before disabling auth.

Copy buttons do nothing over Tailscale/LAN HTTP

Accessing via http://100.x.y.z or LAN IP

Symptom: UI copy/clipboard fails; works on localhost.

terminal

# Browsers only allow navigator.clipboard on secure origins (HTTPS or localhost).

# Fixes:
# 1. Use https:// via reverse proxy or mkcert (see official setup guide)
# 2. Or open Odysseus on the host via http://localhost:7000 / :7860

# Prefer Tailscale + HTTPS over raw public port forwards — /security

ChromaDB falls back / memory broken (chromadb-client)

Native install — vector memory errors

Symptom: chromadb-client conflicts with full chromadb package.

terminal

# Official fix — uninstall the lightweight client, reinstall full chromadb:

./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb

# Windows venv:
# .\venv\Scripts\pip uninstall chromadb-client -y
# .\venv\Scripts\pip install --force-reinstall chromadb

# Then restart Odysseus.

Outlook / Microsoft 365 email login fails

Settings → Email

Symptom: IMAP password rejected; plaintext auth disallowed.

terminal

# Odysseus email uses IMAP/SMTP username+password today.
# Outlook / Microsoft 365 generally require OAuth — normal passwords fail.

# Options:
# 1. Use a provider that still allows app passwords / IMAP password auth
# 2. Follow official docs/email-outlook.md for current limitations
# 3. Prefer local mail only on trusted LAN with TLS when possible

# This is a known platform limitation, not a broken install.

FAQ

Common questions