Odysseus AI Linux Setup

Last updated: June 6, 2026

Linux is the strongest route for serious local model serving because Docker, CUDA, ROCm, tmux, and native Python are all first-class options. Start simple, then add GPU and model-serving complexity only after the web app is healthy.

Quick answer

Use Docker Compose for the first run. Use native Linux when you need direct CUDA, ROCm, tmux, or local model runtime control.

Copy command

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

1. Install Baseline Packages

Native Linux needs Python and tmux. Docker users still need Git and Docker Compose.

Copy command

sudo apt update
sudo apt install -y git python3 python3-venv tmux

Use your distro equivalent if you are not on Ubuntu or Debian.

2. Docker Compose Path

Docker is the recommended first run because it starts Odysseus and bundled services with local bind defaults.

Copy command

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

Open http://localhost:7000. If it fails, use the port 7000 troubleshooting page.

3. Native Linux Path

Native Linux is useful when you want to inspect Python dependencies, run uvicorn directly, and control model-serving processes without container boundaries.

Copy command

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py
python -m uvicorn app:app --host 127.0.0.1 --port 7000

Keep the host bound to 127.0.0.1 unless you intentionally configure LAN or reverse proxy access.

4. NVIDIA Docker GPU Setup

First prove the host driver works, then prove Docker passthrough works, then enable the Odysseus overlay.

Copy command

nvidia-smi
scripts/check-docker-gpu.sh
scripts/check-docker-gpu.sh --print-install-commands
scripts/check-docker-gpu.sh --enable-nvidia-overlay

If nvidia-smi works inside the container but llama.cpp still runs on CPU, use the llama.cpp CUDA fallback guide.

5. AMD / ROCm Docker Setup

AMD setups depend on ROCm, kfd, dri, and render group permissions on the host. The Odysseus AMD script reports the values you need to set.

Copy command

rocminfo
ls -l /dev/kfd /dev/dri/renderD*
scripts/check-docker-amd-gpu.sh

After the script reports the render group id, set COMPOSE_FILE and RENDER_GID in .env and recreate the stack.

6. Connect Host Ollama from Linux Docker

Plain Linux Docker usually cannot use Docker Desktop's host.docker.internal name. Bind Ollama on the host, then use a reachable host IP plus the OpenAI-compatible /v1 suffix.

Copy command

OLLAMA_HOST=0.0.0.0:11434 ollama serve
# In Odysseus settings:
http://<host-ip>:11434/v1

Keep Ollama on a private interface, LAN, or VPN. Do not expose a raw Ollama endpoint to the public internet.

Verify Against Official Docs

Linux GPU overlay files and scripts can change quickly. Check the official GitHub repository before changing GPU runtime settings.

FAQ

Should I use Docker or native Linux for Odysseus AI?

Use Docker first if you want the recommended quick start. Use native Linux when you need direct control over Python, tmux, CUDA, ROCm, or local model serving outside the container.

What does native Linux need for Cookbook downloads?

The official README says Cookbook needs tmux for background model downloads and serves. Install tmux before relying on the Cookbook workflow.

How do I enable NVIDIA GPU support in Docker on Linux?

Install the host NVIDIA Container Toolkit, verify passthrough, then enable the Odysseus NVIDIA compose overlay. The official scripts can diagnose and optionally enable the overlay.

How do I enable AMD GPU support in Docker on Linux?

Run the AMD GPU diagnostic script, then add the reported COMPOSE_FILE and RENDER_GID values to .env. Host ROCm, kfd, dri, video, and render group setup still matter.

How should Odysseus in Linux Docker reach host Ollama?

Use a host IP address reachable from the container plus /v1. Docker Desktop has host.docker.internal, but plain Linux Docker usually needs the host bridge or LAN IP.

Installation support

Need hands-on installation support?

Setup Helper is the self-service planner. Installation Support is for users who want a human to review the route, diagnose logs, or get Odysseus running. We confirm scope and price before any payment.