Odysseus AI unter Linux installieren: Anleitung für native Installation und Docker

Vor der Installation: nativ oder Docker?

Docker ist der sinnvolle Standard, wenn du den dokumentierten Mehrdienst-Stack, reproduzierbare Container und eine klare Trennung vom Host möchtest. Die native Installation ist passend, wenn du Python-Prozesse direkt untersuchen, am Repository entwickeln oder Host-Werkzeuge ohne Containergrenze einsetzen willst.

Ein lokales Modell ist kein Grund, automatisch nativ zu installieren. Der Workspace kann Ollama, vLLM, SGLang oder andere OpenAI-kompatible Endpunkte in beiden Betriebsarten ansprechen. Umgekehrt liefert Docker nicht automatisch GPU-Beschleunigung: Treiber, Container-Runtime und Compose-Overlay müssen zusammenpassen.

Linux-Vorprüfung vor dem Klonen

Prüfe Branch, Interpreter, freien Port, Speicher und Inferenzziel. Das offizielle Repository verwendet derzeit dev als Standardbranch mit den neuesten Änderungen; main wird als stärker kuratierter Branch beschrieben. Es gibt keine offiziellen GitHub Releases, Tags oder versionierten Binärdateien. Deshalb nennt diese Seite keine erfundene Versionsnummer und verlinkt auf das Repository.

Für die native Variante brauchst du Python 3.11 oder neuer. Für Docker müssen Docker Engine und das Compose-Plugin funktionieren. Port 7000 muss frei sein, sofern du APP_PORT nicht bewusst änderst. Für Hintergrund-Downloads und lokale Modellprozesse im Cookbook nennt die offizielle Anleitung unter nativem Linux außerdem tmux.

1. Branch auswählen

   dev bietet die neuesten Änderungen; main ist kuratierter und kann hinter dev liegen.

2. Modellstandort festlegen

   Entscheide, ob Inferenz lokal, auf einem anderen Rechner oder über eine API erfolgt.

3. Port prüfen

   Stelle sicher, dass Port 7000 frei ist, oder plane einen anderen APP_PORT.

4. Ersten Start privat halten

   Nutze 127.0.0.1, bis das temporäre Administratorkennwort geändert wurde.

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

Odysseus AI nativ unter Linux installieren

Der native Weg erstellt eine isolierte virtuelle Umgebung, installiert die vorgesehenen Abhängigkeiten, führt die Projekteinrichtung aus und startet die ASGI-Anwendung mit Uvicorn. Führe die Befehle als normaler Benutzer in einem eigenen Verzeichnis aus. sudo pip vermischt Projektpakete mit dem System-Python und erschwert Updates und Deinstallation.

Der Startbefehl bindet nur an die Loopback-Adresse. Das ist für den ersten Test richtig. Richte systemd oder einen anderen Prozessmanager erst ein, nachdem der interaktive Start, der Login und ein Modelltest funktionieren. Der Dienst muss dasselbe Arbeitsverzeichnis, denselben virtuellen Interpreter und dieselben Umgebungswerte verwenden.

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

Odysseus AI mit Docker Compose installieren

Der offizielle Schnellstart empfiehlt Docker. Das Kopieren von .env.example ist optional, macht die Bereitstellungswerte aber nachvollziehbar. Baue und starte die Container, warte auf die Healthchecks und lies anschließend das temporäre Administratorkennwort in den Odysseus-Logs.

Compose bindet die Weboberfläche standardmäßig an 127.0.0.1. Ist Port 7000 belegt, setze APP_PORT=7001 oder einen anderen freien Port in .env und erstelle den Container neu. APP_BIND=0.0.0.0 ist keine Lösung für einen Portkonflikt; Bind-Adresse und Port sind getrennte Einstellungen.

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

Ersten Login prüfen, bevor du Modelle hinzufügst

Öffne http://localhost:7000 auf dem Linux-Rechner. Die Ersteinrichtung erstellt ein Administratorkonto und gibt ein temporäres Kennwort aus. Melde dich an, ändere das Kennwort in den Einstellungen und teste eine neue Browsersitzung, bevor du den Dienst im Netzwerk freigibst.

Konfiguriere danach genau einen bekannten Modell- oder API-Endpunkt und sende eine kurze Testanfrage. Lädt die Oberfläche, aber die Anfrage scheitert, funktioniert die Installation meist bereits. Prüfe dann Modell-URL, Zugangsdaten, Modellnamen, Firewall und Modell-Laufzeit statt die gesamte Anwendung neu zu installieren.

1. Lokale Seite öffnen

   Prüfe Login-Seite und Weiterleitungen auf localhost:7000.

2. Generiertes Kennwort lesen

   Nutze Terminal oder Container-Logs und rate kein Standardkennwort.

3. Kennwort ändern

   Ersetze das temporäre Kennwort vor LAN-, VPN- oder Proxy-Zugriff.

4. Ein Modell testen

   Starte mit einem bekannten Endpunkt und einer kurzen Anfrage.

GPU-Unterstützung gehört zur Modell-Laufzeit

Der Workspace selbst ist relativ leicht. GPU-Bedarf entsteht vor allem durch lokale Inferenz. Eine native Installation kann direkt mit Host-Ollama oder einer anderen Laufzeit sprechen. Auch ein Docker-Workspace kann einen Host- oder Remote-Endpunkt verwenden, ohne den Docker-Socket einzubinden.

Für containerisierte NVIDIA- oder AMD-Nutzung prüfe zuerst Host-Treiber und Passthrough. Das offizielle Repository liefert Diagnose-Skripte und Overlays. Ein erfolgreiches nvidia-smi im Container bestätigt den Gerätezugriff, aber nicht automatisch eine passende CUDA- oder ROCm-Version der gewählten Modellsoftware.

scripts/check-docker-gpu.sh

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

Odysseus unter Linux sicher über Tailscale verbinden

Similarweb zeigte die Phrase connect odysseus to tailscale linux als niedrig schwierige unterstützende Suchanfrage. Sie gehört in diese Linux-Anleitung, weil der Fernzugriff erst nach einer funktionierenden lokalen Installation beginnt. Für eine eigene dünne Seite reicht die Nachfrage nicht aus.

Binde die Anwendung bewusst an 0.0.0.0 oder eine passende Schnittstelle, lasse die Authentifizierung aktiviert, beschränke den Zugriff über Tailscale-Regeln oder die Host-Firewall und nutze HTTPS, wenn Browserfunktionen einen sicheren Ursprung verlangen. Leite weder Anwendungs- noch Modellport direkt ins öffentliche Internet weiter.

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

APP_BIND=0.0.0.0
AUTH_ENABLED=true

Linux-Installation sicher aktualisieren

Am 30. Juli 2026 gab es keine offiziellen Releases oder Versions-Tags. dev bewegt sich schnell, main ist kuratierter. Diese Seite behauptet deshalb keine neueste Versionsnummer, Dateigröße oder dauerhafte Binärdatei.

Notiere vor dem Update den Branch, sichere Daten und .env, lies die Upstream-Änderungen und aktualisiere nur den gewählten Branch. Wechsle nicht nebenbei von main zu dev. Baue Container neu oder installiere geänderte Abhängigkeiten und wiederhole danach Login-, Modell- und Netzwerkprüfung.

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

Fehlerbehebung bei der Linux-Installation

Prüfe nacheinander Prozess, Port, Anmeldung, Modellendpunkt und optionale Dienste. Mehrere Ebenen gleichzeitig zu ändern verschleiert die Ursache.