Odysseus AI Linux Install: Native and Docker Setup Guide

Choose native Linux or Docker before installing

Docker is the better default when you want the documented multi-service stack, repeatable container recreation, and a clean boundary between the application and the host. Native Linux is useful when you want to inspect Python processes directly, develop against the repository, use host tools without container boundaries, or minimize Docker-specific networking layers.

Do not choose native installation merely because you plan to use a local model. Odysseus can connect to Ollama, vLLM, SGLang, or another OpenAI-compatible endpoint whether the workspace itself runs natively or in Docker. Likewise, Docker does not automatically grant GPU acceleration: the host runtime and the selected compose overlay must expose the correct device.

Run this Linux preflight checklist first

Confirm the branch, interpreter, free port, storage, and inference plan before cloning. The official repository currently uses dev as the default branch for the newest changes and describes main as the more curated branch. There are no official GitHub Releases or versioned binary assets to treat as a stable installer, so this page links to the repository rather than inventing a latest package number.

For a native install, verify Python 3.11 or newer. For Docker, verify the Docker Engine and Compose plugin. Port 7000 must be free unless you intentionally set APP_PORT to another value. If Cookbook will download or serve local models in the background, the upstream guide also calls out tmux for native Linux.

1. Pick dev or main

   Use dev for the newest upstream changes; use main when you prefer the curated branch and accept that it may lag behind dev.

2. Choose the model location

   Decide whether inference runs on this machine, another host, or a hosted API. This choice changes storage and GPU needs far more than the web workspace does.

3. Check the local port

   Confirm that port 7000 is available, or record a different APP_PORT before starting.

4. Keep the first launch private

   Bind to 127.0.0.1 until the generated admin password has been changed and remote access has been planned.

python3 --version
docker --version
docker compose version
ss -ltn | grep ':7000' || true

Native Odysseus AI Linux install step by step

The native path creates an isolated virtual environment, installs the pinned Python requirements, runs the project setup step, and starts the ASGI application with Uvicorn. Run these commands as a normal user inside a directory you control. Avoid sudo pip because it mixes project dependencies into the system Python and makes later cleanup harder.

The final command binds only to loopback. That is the correct first-run default. Keep the terminal open or place the process under a service manager only after the application works interactively. A service unit should use the same project directory, virtual-environment interpreter, environment file, and port you verified manually.

git clone https://github.com/odysseus-dev/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

Install Odysseus AI on Linux with Docker Compose

The official quick start treats Docker as the recommended route. Copying .env.example is optional but useful because it makes deployment defaults explicit. Build and start the containers, wait for health checks, then inspect the Odysseus logs for the temporary admin password.

Docker Compose binds the web UI to 127.0.0.1 by default. If port 7000 is occupied, set APP_PORT=7001 or another free port in .env and recreate the container. Do not change APP_BIND to 0.0.0.0 merely to fix a localhost problem; binding and port selection solve different issues.

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

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

Verify the first login before adding models

Open http://localhost:7000 from the Linux host. The first setup creates an admin account, using admin unless ODYSSEUS_ADMIN_USER was set, and prints a temporary password. Sign in, replace that password in Settings, and verify the page loads again in a fresh browser session before changing network exposure.

Next, configure one model or API endpoint in Settings and run a minimal chat. This separates application health from inference health. If the interface loads but a prompt fails, the Linux install is probably working and the remaining issue is the model URL, credentials, model name, firewall, or runtime.

1. Load the local page

   Confirm the browser reaches localhost:7000 and the login form appears without a redirect loop.

2. Use the generated password

   Read the native terminal or Docker logs; do not guess a default password.

3. Change the credential

   Replace the temporary admin password before enabling LAN, VPN, or reverse-proxy access.

4. Test one model

   Add one known endpoint and send a short prompt before enabling more services or tools.

Treat GPU support as a model-runtime decision

The Odysseus workspace itself is comparatively lightweight. GPU demand comes mainly from local model serving. A native Linux install can connect to a host Ollama or another runtime directly. A Docker workspace can also connect to a host or remote endpoint without mounting the Docker socket.

If you want Cookbook or another containerized runtime to use an NVIDIA or AMD GPU, first verify host drivers and container passthrough. The upstream repository provides diagnostic scripts and compose overlays. Passing nvidia-smi inside a container proves device access, but it does not guarantee that a selected llama.cpp, vLLM, or SGLang build has the matching CUDA or ROCm userspace.

scripts/check-docker-gpu.sh

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

Connect Odysseus to Tailscale on Linux safely

The Similarweb phrase-match data surfaced connect odysseus to tailscale linux as a low-difficulty supporting query. It belongs inside this Linux installation guide because the task begins only after a working local installation. It does not justify a separate thin page.

To make Odysseus reachable over Tailscale, bind the application to 0.0.0.0 or the appropriate interface, keep authentication enabled, restrict access with Tailscale policy or the host firewall, and prefer HTTPS when browser features require a secure origin. Never forward the raw application or model port to the public internet as a shortcut.

python -m uvicorn app:app --host 0.0.0.0 --port 7000

APP_BIND=0.0.0.0
AUTH_ENABLED=true

Update a Linux installation without pretending there is a release version

As of July 30, 2026, the official repository exposes no GitHub Releases or version tags. The default dev branch moves quickly, while main is described as curated. For that reason, this guide does not claim a latest version number, file size, binary installer, or permanent direct download URL.

Before updating, note your branch, back up deployment data and .env, read upstream changes, pull the selected branch, then rebuild or reinstall dependencies. Do not switch from main to dev during an unrelated maintenance window without reviewing the difference. After the update, repeat the login, model, and network checks instead of assuming a successful pull means a healthy application.

git status --short
git branch --show-current
git pull --ff-only
# Docker path
docker compose up -d --build

Odysseus AI Linux troubleshooting table

Troubleshoot one layer at a time: process, port, login, model endpoint, then optional services. Mixing all five produces misleading fixes.