Odysseus AI Docker Setup Guide

Last updated: June 5, 2026

Docker Compose is the recommended path for most Odysseus AI installs. It starts Odysseus and the bundled local services with loopback-only defaults, so you can test the workspace on your machine before changing network or GPU settings.

Odysseus is changing quickly. Use this guide as a practical checklist, but verify commands against the official GitHub repository before running a production deployment.

Requirements

- Docker Desktop or Docker Engine with Docker Compose V2
- Git installed locally
- 8GB RAM minimum, 16GB+ recommended if you will run local models
- Enough disk space for model downloads; 20GB is a practical starting point

Copy-Paste Docker Commands

Start from a clean terminal and run the official Docker path:

Copy command

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

The .env copy is optional in the README, but keeping it explicit makes port, bind, auth, and GPU settings easier to review before you expose anything beyond localhost.

Open localhost:7000

Once the containers are healthy, open http://localhost:7000. If another local service already uses port 7000, set APP_PORT=7001 in .env and recreate the container.

Follow the localhost:7000 troubleshooting checklist if the browser still cannot connect.

Copy command

docker compose ps
docker compose logs --tail 80 odysseus

Find the Admin Password

On first setup, Odysseus creates an admin account and prints a temporary password. For Docker, check the Odysseus container logs:

Copy command

docker compose logs odysseus | grep -i password

The default username is admin unless you set ODYSSEUS_ADMIN_USER before first boot. After login, change the password in Settings.

See the full admin password troubleshooting page.

Connect a Model Provider

Odysseus is the workspace layer. After Docker starts, connect a local runtime such as Ollama or a remote OpenAI-compatible provider in Settings. If Ollama runs on your host machine, Docker Desktop users usually point Odysseus at:

Copy endpoint

http://host.docker.internal:11434

Follow the Ollama setup guide for endpoint and model suggestions.

Enable GPU Overlays

CPU-only users can skip this. For local model serving with NVIDIA or AMD GPUs, configure host GPU passthrough first, then enable the matching Docker overlay.

NVIDIA

Copy command

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

AMD / ROCm

Copy command

scripts/check-docker-amd-gpu.sh
# Then set COMPOSE_FILE and RENDER_GID in .env

Do not expose GPUs to the container until the host runtime is working. The official scripts are diagnostics first; they do not silently install host GPU runtime or edit .env without explicit flags.

Common Docker Errors

Port 7000 is already taken

Copy command

lsof -i :7000

Set APP_PORT=7001 in .env, then recreate the container.

.env file is missing

Copy command

cp .env.example .env

Keep .env local and never commit real API keys or passwords.

GPU is not visible inside Docker

Copy command

docker compose exec odysseus nvidia-smi -L

Install the host GPU runtime first, then enable the matching overlay.

FAQ

What is the recommended Docker command for Odysseus AI?

Clone the official repository, copy .env.example to .env, then run docker compose up -d --build. Open http://localhost:7000 when the containers are healthy.

Where do I find the first admin password?

Odysseus prints a temporary admin password on first setup. For Docker installs, run docker compose logs odysseus and look for the generated admin password line.

What is the default Odysseus AI username?

The default username is admin unless ODYSSEUS_ADMIN_USER is set before first boot.

Can I expose Odysseus AI to my LAN?

Keep APP_BIND on 127.0.0.1 unless you intentionally want LAN or reverse-proxy access. If you bind to 0.0.0.0, keep authentication enabled and avoid direct public internet exposure.

How do I enable GPU support in Docker?

Use the official GPU diagnostic scripts first. For NVIDIA, scripts/check-docker-gpu.sh can check passthrough and enable the NVIDIA overlay after confirmation. AMD users should run scripts/check-docker-amd-gpu.sh and set the reported render group values manually.

Related Guides

Find Admin Password

Where Odysseus prints the first login password and how to change it safely.

Fix localhost:7000

Debug web UI port conflicts, Docker status, APP_PORT, and bind settings.

Connect Ollama

Use Ollama as a local model backend after the Docker stack is running.

Hardware Requirements

GPU, RAM, and storage recommendations for local model serving.