Self-Hosted AI-Workspace mit Odysseus einrichten

Was ist Odysseus überhaupt?

Odysseus ist ein Open-Source, vollständig selbstgehosteter KI-Workspace, der vom YouTuber PewDiePie entwickelt wurde. Es ist als private, 100 % kontrollierbare Alternative zu kommerziellen Plattformen wie ChatGPT oder Claude konzipiert.

Die Idee dahinter: Statt für jede Aufgabe ein eigenes externes Tool zu nutzen und überall persönliche Daten zu hinterlassen, bündelt Odysseus Chat, Agenten, Deep Research sowie E-Mail und Kalender in einer einzigen Oberfläche auf Ihrem eigenen Server. So bleiben Ihre Daten an einem Ort, den Sie kontrollieren, und Sie springen nicht mehr zwischen einem Dutzend Diensten hin und her.

Warum gerade Odysseus? Das Projekt wurde am 31.05.2026 veröffentlicht und sammelte in weniger als zwei Wochen über 67.000 GitHub-Stars. Anders als reine Chat-Oberflächen vereint es Agent, Deep Research, E-Mail-Anbindung und eine eigene Modell-Verwaltung in einem Tool. Ein Hinweis vorweg: Im Windschatten des Hypes kursieren bereits Fake-Repositories (etwa pewdiepie-odysseus/odysseus). Nur das oben verlinkte Repo (pewdiepie-archdaemon/odysseus) ist das echte Projekt.

Bevor Sie loslegen: Eine Warnung

So vielversprechend der Workspace ist - bevor Sie ihn ernsthaft einsetzen, sollten Sie ein paar Dinge nüchtern einordnen. Das ist uns wichtig genug, um es vor die eigentliche Anleitung zu stellen:

• Odysseus ist nur das halbe Bild. Die Oberfläche samt Agenten-Framework bringt selbst keine „Intelligenz" mit - die liefert immer ein LLM, das Sie selbst bereitstellen. Dafür gibt es zwei Wege: Entweder Sie lassen ein Modell lokal auf Ihrem Server laufen (komfortabel über das integrierte Cookbook, dazu später mehr) oder Sie hinterlegen den API-Schlüssel eines externen Anbieters wie OpenAI oder Anthropic. Ohne mindestens eine dieser beiden Optionen fehlt dem Workspace das entscheidende Teil - um ihn so zu nutzen, wie PewDiePie es in seinem Video zeigt, brauchen Sie also zusätzlich ein LLM.
  

  

  
  Wichtig zur Datenhoheit: Diese beiden Wege unterscheiden sich grundlegend beim Datenschutz. Hinterlegen Sie den API-Schlüssel eines externen Anbieters, verlassen Ihre Chat-Inhalte - und alles, was ein Agent verarbeitet, also etwa Mails und Dokumente - Ihren Server und werden an den Provider des AI-Models (z.B. OpenAI oder Anthropic) gesendet. Das „datenschutzfreundlich" aus der Einleitung gilt uneingeschränkt nur beim lokalen Modell: Dann bleiben alle Inhalte auf Ihrem eigenen Server, ohne dass Texte an Dritte gehen.
• Sehr junges Projekt - kein Produktivsystem. Offiziell trägt Odysseus zwar die Version 1.0 (das README spricht von „vers. 1.0", src/constants.py meldet APP_VERSION = "1.0.0"), echte Releases oder Tags gibt es bislang aber keine. Dahinter steht ein erst am 31.05.2026 veröffentlichtes Projekt mit hoher Änderungsrate - Stand heute über 1.100 offene Issues - und reichlich Community-Kritik an der Code-Qualität (Stichwort „vibe-coded", siehe den HN-Thread zum Launch). Für private Experimente und interne Tools ist es sicherlich interessant - für geschäftskritische Produktivsysteme raten wir von einer Nutzung ab.
• Autonome Agenten sind mächtig - und riskant. Die KI kann echte Befehle auf Ihrem Server ausführen, im Web browsen und Dateien verändern. Ein starkes Admin-Passwort ist daher Pflicht. Für besonders sensible Setups sollten Sie den Zugriff zusätzlich auf ein privates VPN beschränken (siehe WireGuard VPN Guide).
• Vorsicht vor Prompt Injection. Fremde Inhalte, die der Agent verarbeitet - eingehende Mails, Webseiten, Kalender-Einträge - können versteckte Anweisungen enthalten, die der Agent als echte Befehle auffasst. Genau diese Kombination bewirbt der Guide (Mail-Anbindung + Web-Browsing + Agent), und das offizielle THREAT_MODEL.md nennt sie als Kernrisiko. Erschwerend kommt hinzu: Die Shell- und Dateisystem-Tools laufen ohne Sandbox - eine erfolgreiche Injection in einer Admin-Sitzung kann also reale Shell-Befehle auslösen. Odysseus härtet dagegen bislang nur auf Prompt-Ebene. Nutzen Sie automatische Aktionen daher nur mit einem Freigabe-Schritt und binden Sie dem Agenten kein Postfach mit sensiblen Daten an.

Was bietet Odysseus im Detail?

Damit Sie wissen, worauf Sie sich einlassen, hier ein Blick auf die wichtigsten Out-of-the-box-Funktionen:

• Autonome KI-Agenten: Ein starkes Framework, das direkt Code auf dem Server ausführt, im Web browsen und Dateien manipulieren kann.
• Lernt mit der Nutzung: Der Agent verfügt über ein persistentes Gedächtnis und sammelt wiederverwendbare Skills, die sich mit der Zeit verbessern - er versteht Sie und Ihre Aufgaben also Stück für Stück besser. (Ein automatisches Umschreiben der Instruktionen bei fehlgeschlagenen Tasks findet dabei nicht statt.)
• Lokales E-Mail-Management: Ein lokaler E-Mail-Client scannt Postfächer sicher im Hintergrund, kategorisiert Mails und flaggt dringende Nachrichten.
• Auto-Reply: Bei Standardfragen recherchiert die KI selbstständig und legt Ihnen im Dashboard einen fertigen Antwortentwurf zur Freigabe vor.
• Deep Research: Mehrstufige, tiefgehende Websuchen für komplexe Themen - inklusive übersichtlicher Visualisierung und einem Chat für gezielte Rückfragen.
• Interaktiver Dokumenten-Editor: Rendert Dokumente und Code in Echtzeit. Sie können manuell eingreifen oder die Formatierung per KI-Prompt anpassen lassen. (PDF-Rendering ist kein Standard-Feature, sondern ein optionales Extra: Es benötigt die Zusatz-Abhängigkeit PyMuPDF unter AGPL-Lizenz und muss beim Docker-Build explizit mit --build-arg INSTALL_OPTIONAL=true aktiviert werden.)
• Das „Cookbook“: Vereinfacht das Einrichten lokaler LLMs erheblich. Es prüft CPU, RAM und VRAM und ermittelt daraus direkt einen Kompatibilitäts-Score.
• One-Click-Modelle: Basierend auf Ihrem Hardware-Score laden Sie die passenden Modelle herunter. Die API-Orchestrierung startet vollautomatisch.

Voraussetzungen für die Installation

Getestet mit: Odysseus 1.0.0 (main-Branch, keine Releases/Tags vorhanden) auf Debian 13, Juni 2026. Das folgende Setup sollten Sie mindestens mitbringen:

Installation: Schritt für Schritt

1. Server-Vorbereitung

Loggen Sie sich zunächst auf Ihrem Server ein:

ssh root@<Ihre-Server-IP>

Bringen Sie das System auf den neuesten Stand und installieren Sie die benötigten Pakete, falls dies noch nicht geschehen ist:

apt update && apt upgrade -y
apt install git docker.io docker-compose -y

apt update && apt upgrade -y
apt install git docker.io docker-compose-v2 -y

# Unter Debian 12 ist das Distro-Paket "docker-compose" noch das veraltete v1,
# daher installieren wir Docker hier über das offizielle Docker-apt-Repository:
apt update && apt upgrade -y
apt install git ca-certificates curl -y
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian bookworm stable" > /etc/apt/sources.list.d/docker.list
apt update
apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

2. Repository klonen

Laden Sie sich den aktuellen Code vom offiziellen GitHub-Repository. Es wird empfohlen, das Ganze im Verzeichnis /opt abzulegen. Wir klonen gezielt den main-Branch: Der Standard-Branch des Repos ist dev und laut README potenziell instabil - main ist der kuratierte, stabilere Stand.

cd /opt
git clone -b main https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

Tipp - reproduzierbarer Stand: Da es keine Releases oder Tags gibt, entwickelt sich main laufend weiter. Für einen reproduzierbaren Stand können Sie nach dem Klonen einen konkreten Commit festschreiben (git checkout <commit-hash>); den aktuellen Hash zeigt git log -1 --format=%H. Dieser Guide wurde mit dem main-Stand von Anfang Juni 2026 getestet.

3. (Optional) Domain mit dem Server verbinden

Die Schritte 3 und 5 sind optional. Sie sorgen für den Zugriff über eine eigene Domain mit HTTPS-Verschlüsselung. Möchten Sie den Workspace zunächst nur intern oder zum Testen per IP nutzen, überspringen Sie beide Schritte – Sie erreichen ihn dann später über http://<Ihre-Server-IP>:7000.

Damit Ihr Workspace über eine eigene Domain statt einer IP-Adresse erreichbar ist (und ein SSL-Zertifikat bekommt), muss Ihre Domain auf den Server zeigen. Falls Sie noch keine passende Domain haben, finden Sie eine bei Avoro - unserem eigenen Domain-Angebot. Legen Sie anschließend bei Ihrem Domain-Anbieter einen A-Record an:

Prüfen Sie anschließend, ob die Zuordnung greift - der Befehl sollte Ihre Server-IP zurückgeben:

dig +short ai.example.com

Hinweis: Bis ein neuer DNS-Eintrag weltweit verfügbar ist, können einige Minuten (selten bis zu einer Stunde) vergehen. Warten Sie, bis dig die richtige IP zeigt, bevor Sie weitermachen.

4. Konfiguration anpassen

Odysseus läuft auch ohne .env mit Standardwerten - alle Variablen der Compose-Datei haben Defaults. Wir legen die Datei trotzdem an (im README ausdrücklich empfohlen), um Zugriff und HTTPS sauber zu konfigurieren. Wir kopieren zunächst die Vorlage:

cp .env.example .env

Die meisten Schlüssel in der Vorlage sind auskommentiert (aktiv sind lediglich LLM_HOST=localhost und SEARXNG_INSTANCE=..., wobei die Compose-Datei Letzteres ohnehin überschreibt). Standardmäßig bindet das Web-UI an 127.0.0.1 auf Port 7000 - es ist also ab Werk nur vom Server selbst erreichbar, nicht von außen. Wir setzen die relevanten Werte direkt per Befehl, so müssen Sie nichts von Hand in einem Editor suchen und ersetzen.

Zum Admin-Login: Sie müssen vorab kein Passwort setzen. Odysseus legt das Admin-Konto beim ersten Start selbst an und gibt dabei ein temporäres Passwort in den Logs aus - wie Sie es auslesen und sofort ändern, steht in Schritt 8.

Konfigurieren Sie nun den Zugriff passend zu Ihrem gewählten Weg:

# Web-UI von außen erreichbar machen:
sed -i "s|^# APP_BIND=.*|APP_BIND=0.0.0.0|" .env

# APP_BIND bleibt auf 127.0.0.1 - Caddy erreicht den Container
# über das interne Docker-Netz. Für HTTPS aktivieren wir nur sichere Cookies:
sed -i "s|^# SECURE_COOKIES=.*|SECURE_COOKIES=true|" .env

Prüfen Sie kurz, ob die Werte übernommen wurden:

grep -E "^(APP_BIND|SECURE_COOKIES)" .env

5. (Optional) Reverse Proxy mit HTTPS einrichten

Überspringen Sie diesen Schritt, wenn Sie ohne eigene Domain per http://<Ihre-Server-IP>:7000 zugreifen möchten. Er gehört mit Schritt 3 zusammen.

Statt den Workspace nackt auf einem hohen Port ins Internet zu hängen, stellen wir Caddy davor. Caddy ist ein schlanker Webserver, der sich vollautomatisch ein gültiges SSL-Zertifikat von Let's Encrypt holt und es selbstständig erneuert - um Zertifikate müssen Sie sich also nie wieder kümmern.

Wir fügen Caddy als zusätzlichen Dienst hinzu, ohne die mitgelieferte Compose-Datei anzufassen. Docker Compose liest eine optionale Datei namens docker-compose.override.yml automatisch mit ein. Legen Sie diese an:

cat > /opt/odysseus/docker-compose.override.yml <<'EOF'
services:
  caddy:
    image: caddy:2-alpine
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:
EOF

Jetzt noch die eigentliche Caddy-Konfiguration. Sie ist erfreulich kurz - eine Zeile für Ihre Domain, eine fürs Weiterleiten an den Odysseus-Container. Wir setzen die DOMAIN-Variable sicherheitshalber noch einmal (falls Sie sich zwischen den Schritten neu eingeloggt haben) - ersetzen Sie ai.example.com wieder durch Ihre Domain:

DOMAIN=ai.example.com
cat > /opt/odysseus/Caddyfile <<EOF
$DOMAIN {
    reverse_proxy odysseus:7000
}
EOF

So steht Ihre echte Domain automatisch in der Datei. Caddy leitet allen Verkehr an den Dienst odysseus auf dessen container-internen Port 7000 weiter; beide Container teilen sich dasselbe Docker-Netz, sobald sie über dieselbe Compose-Datei laufen. (Heißt der Hauptdienst in Ihrer Version anders, zeigt docker compose config --services die korrekten Namen.)

6. Container hochfahren

Jetzt starten wir alles auf einmal. Haben Sie Schritt 5 gemacht, bindet Docker Compose die Caddy-Override-Datei automatisch mit ein. Odysseus wird dabei aus dem Quellcode gebaut - das --build sorgt dafür, dass das passiert, und kann beim ersten Mal je nach Server einige Minuten dauern:

docker compose up -d --build

Falls Sie Caddy eingerichtet haben (Schritt 5), beantragt es jetzt im Hintergrund Ihr SSL-Zertifikat. Den Fortschritt verfolgen Sie mit:

docker compose logs -f caddy

Sobald Caddy certificate obtained successfully meldet, ist Ihre Domain per HTTPS erreichbar. Mit Ctrl+C verlassen Sie die Log-Ansicht wieder.

7. Prüfen, ob alles läuft

Bevor Sie in den Browser wechseln, ein kurzer Gesundheits-Check. Lassen Sie sich den Status aller Container anzeigen:

docker compose ps

Sie sehen hier mehrere Container: Neben odysseus selbst startet Compose auch chromadb (Vektor-Speicher für das Gedächtnis des Agenten), searxng (Metasuche für die Web-Recherche) und ntfy (Benachrichtigungen). Alle drei binden nur an 127.0.0.1, Sie müssen dafür also keinen zusätzlichen Port in der Firewall öffnen - die Firewall-Angaben aus den vorigen Schritten bleiben damit korrekt.

Alle Dienste sollten als running (bzw. healthy) gelistet sein. Sehen Sie stattdessen restarting oder exited, läuft etwas schief - werfen Sie dann einen Blick in die Logs des betroffenen Dienstes:

docker compose logs odysseus

8. Web-Interface aufrufen

Rufen Sie Ihren Workspace nun im Browser auf - je nachdem, welchen Weg Sie gewählt haben:

• Direktzugriff (ohne Schritt 3 + 5): http://<Ihre-Server-IP>:7000
• Mit eigener Domain (Schritt 3 + 5): https://ai.example.com (Ihre Domain)

Erster Login: Beim ersten Start legt Odysseus automatisch das Konto admin an und schreibt ein temporäres Passwort in die Logs. Lesen Sie es aus mit:

bash

Code kopieren

docker compose logs odysseus | grep -i password

Melden Sie sich damit an und ändern Sie das Passwort sofort in den Einstellungen. Aktivieren Sie dort gleich auch die Zwei-Faktor-Authentifizierung (TOTP), die Odysseus mitbringt - gerade beim Domain-Setup ist das der wirkungsvollste Härtungsschritt für Ihr Admin-Konto.

Hinweis zum Direktzugriff: Über http://…:7000 läuft die Verbindung unverschlüsselt - Anmeldedaten gehen im Klartext über die Leitung. Nutzen Sie diesen Weg nur intern oder zum Testen; für den dauerhaften Betrieb richten Sie Domain und HTTPS ein (Schritt 3 + 5).

Modelle via Cookbook einbinden

Der Workspace ist nun installiert, benötigt aber - wie eingangs erwähnt - noch eine „Intelligenz“, um funktionieren zu können. Wenn Sie ein lokales Modell betreiben möchten, nutzen wir dafür das integrierte Cookbook. (Alternativ hinterlegen Sie in den Einstellungen einfach den API-Schlüssel eines externen Anbieters.)

1. Melden Sie sich in Odysseus an und öffnen Sie das Cookbook im Menü.
2. Starten Sie den Hardware-Scan. Das System checkt jetzt Ihre Ressourcen durch.
3. Suchen Sie sich ein passendes Open-Source-Modell aus der vorgeschlagenen Liste aus - im Zweifel das mit dem besten Kompatibilitäts-Score (der Katalog ist aktuell stark von Qwen3-Modellen geprägt, z. B. ein kleines qwen3-4b).
4. Klicken Sie auf Download & Integrate. Mehr ist nicht nötig - Odysseus richtet den Inferenz-Endpunkt im Hintergrund für Sie ein.

Sobald der Download abgeschlossen ist, können Sie E-Mails anbinden, mit Agenten arbeiten oder die Deep-Research-Funktion nutzen.

Server absichern: die dataforest Cloud-Firewall

Sobald Ihr Workspace von außen erreichbar ist, sollte nur das Nötigste offen sein - und das ist hier besonders wichtig, weil die KI echte Befehle auf dem Server ausführen kann. Beachten Sie dabei die Design-Annahme des Projekts: Odysseus ist laut Threat Model für vertrauenswürdige Nutzer in einem privaten Netz gedacht, nicht für die offene Internet-Erreichbarkeit. Den Port 7000 (Direktzugriff) geben Sie daher ausschließlich für Ihre eigene IP frei - öffentlich erreichbar sollte der Workspace nur über den verschlüsselten HTTPS-Weg (Caddy auf Port 80/443) sein, idealerweise zusätzlich abgeschirmt per VPN.

Läuft Ihr Server als Seed in der dataforest Cloud, sichern Sie ihn am einfachsten mit unserer Cloud-Firewall ab. Sie arbeitet auf Netzwerkebene vor dem Seed: Konfiguriert wird komplett im Dashboard - ohne SSH-Login und ohne ein Paket wie ufw von Hand einzurichten. Standardmäßig blockiert sie sämtlichen Datenverkehr, der nicht ausdrücklich durch eine Regel erlaubt ist.

1. Öffnen Sie im dataforest Dashboard den Bereich Netzwerk → Firewalls und klicken Sie auf Firewall erstellen.
2. Jede neue Firewall bringt sinnvolle Standardregeln mit - eingehend sind bereits SSH (Port 22) und Ping erlaubt. Ergänzen Sie unter Eingehend die Regel, die zu Ihrem Zugriffsweg passt:

   Zugriffsweg	Protokoll	Port	Quelle
   Direktzugriff per IP	TCP	7000	Nur Ihre IP
   Mit Caddy/HTTPS (Schritt 5)	TCP	80 und 443	Alle IPv4 / Alle IPv6

3. Wechseln Sie zum Reiter Angewandte Ressourcen und weisen Sie die Firewall Ihrem Seed zu.
4. Speichern Sie. Sobald der Status auf Angewandt wechselt, greifen die Regeln.

Tipp: Geben Sie auch SSH (22) nur für Ihre eigene IP frei statt für Alle IPv4. So bleibt der Server für Sie erreichbar, aber nicht für das halbe Internet. Den Workspace-Port 7000 öffnen Sie ohnehin nie für Alle IPv4 (siehe oben).

Backup einrichten

Gerade weil das Projekt so jung ist und Sie vor jedem Update sichern sollten, lohnt sich ein automatisches Backup von Anfang an.

Kritische Daten identifizieren

Odysseus verteilt seine Daten auf zwei Orte:

• Bind Mount /opt/odysseus/data: Hier liegt der Großteil - Konfiguration, das Gedächtnis des Agenten, Sessions und installierte Skills. Direkt im Dateisystem einsehbar.
• Drei Named Volumes: searxng-data (Sucheinstellungen), chromadb-data (Vektor-Datenbank des Gedächtnisses) und ntfy-cache (Benachrichtigungen). Diese liegen in der Docker-Verwaltung und werden von einem simplen tar über das Projektverzeichnis nicht miterfasst - sie müssen separat gesichert werden.

Tägliches Backup

Das folgende Skript sichert beides - das Datenverzeichnis und die drei Named Volumes - in ein einziges Archiv pro Tag. Erstellen Sie /opt/odysseus/backup.sh:

#!/bin/bash
set -euo pipefail

BACKUP_DIR="/opt/backups/odysseus"
STAMP="$(date +%Y%m%d)"
BACKUP_FILE="${BACKUP_DIR}/odysseus-${STAMP}.tar.gz"
STAGING="$(mktemp -d)"

mkdir -p "$BACKUP_DIR"

# 1) Bind-Mount-Daten (Konfiguration, Gedächtnis, Sessions, Skills)
cp -a /opt/odysseus/data "${STAGING}/data"

# 2) Named Volumes über einen Hilfscontainer in das Staging-Verzeichnis kopieren.
#    docker volume ls findet sie unabhängig vom Projekt-Präfix (z. B. odysseus_chromadb-data).
for VOL in $(docker volume ls -q | grep -E '(^|_)(searxng-data|chromadb-data|ntfy-cache)$'); do
  mkdir -p "${STAGING}/volumes/${VOL}"
  docker run --rm -v "${VOL}:/src:ro" -v "${STAGING}/volumes/${VOL}:/dst" \
    alpine sh -c 'cp -a /src/. /dst/'
done

# 3) Alles in ein Archiv packen
tar -czf "$BACKUP_FILE" -C "$STAGING" .
rm -rf "$STAGING"

if [ -s "$BACKUP_FILE" ]; then
  echo "Backup erfolgreich: ${BACKUP_FILE}"
else
  echo "Backup fehlgeschlagen" >&2
  exit 1
fi

# Backups älter als 30 Tage löschen, mindestens 3 behalten
TOTAL=$(find "$BACKUP_DIR" -name "odysseus-*.tar.gz" | wc -l)
find "$BACKUP_DIR" -name "odysseus-*.tar.gz" -mtime +30 | while read OLD; do
  if [ "$TOTAL" -gt 3 ]; then
    rm "$OLD"
    TOTAL=$((TOTAL - 1))
  fi
done

chmod +x /opt/odysseus/backup.sh

Tipp für ein konsistentes Backup: Die Vektor-Datenbank (chromadb) wird im laufenden Betrieb beschrieben. Für einen garantiert konsistenten Stand können Sie den Stack vor dem Backup kurz stoppen (docker compose stop) und danach wieder starten (docker compose start) - für ein privates Setup reicht in der Regel aber das Hot-Backup oben.

Richten Sie einen Cronjob ein:

crontab -e

Fügen Sie folgende Zeile hinzu:

0 3 * * * /opt/odysseus/backup.sh

Das Backup wird täglich um 03:00 Uhr erstellt. 0 3 * * * bedeutet: Minute 0, Stunde 3, jeden Tag, jeden Monat, jeden Wochentag.

Server-Backup über dataforest Cloud

Die dataforest Cloud bietet automatische tägliche Offsite-Backups als zubuchbare Option. Damit lässt sich der gesamte Seed sichern und jederzeit wiederherstellen - inklusive Datenverzeichnis und Docker-Volumes. Backups sind nicht standardmäßig aktiv und müssen in der Cloud-Konsole aktiviert werden.

Updates einspielen

Da das Projekt sehr jung ist, erscheinen häufig neue Versionen. Erstellen Sie vor jedem Update ein Backup (siehe Backup-Skript oben) und holen Sie sich dann den aktuellen Stand:

cd /opt/odysseus
git pull
docker compose up -d --build

git pull holt den neuen Quellcode samt Compose-Datei und Skripten; up -d --build baut das Odysseus-Image neu und startet die Container in der neuen Version. (Ein docker compose pull reicht hier nicht, weil Odysseus lokal gebaut und nicht als fertiges Image bezogen wird.) Ihre Daten in den Volumes bleiben dabei erhalten.

Fehlerbehebung

Caddy bekommt kein SSL-Zertifikat (nur mit HTTPS-Setup): Fast immer ein DNS- oder Port-Problem. Prüfen Sie mit dig +short ai.example.com, ob der A-Record auf Ihre Server-IP zeigt, und stellen Sie sicher, dass die Ports 80 und 443 von außen erreichbar (in Ihrer Firewall bzw. beim Cloud-Anbieter freigegeben) sind. Details liefert docker compose logs caddy.

„502 Bad Gateway" (nur mit HTTPS-Setup): Caddy läuft, findet aber den Odysseus-Container nicht. Prüfen Sie mit docker compose ps, ob der Dienst läuft, und mit docker compose config --services, ob er wirklich odysseus heißt - andernfalls den Namen im Caddyfile anpassen und docker compose restart caddy ausführen.

Workspace per IP nicht erreichbar (Direktzugriff): Prüfen Sie mit docker compose ps, ob der Container läuft, ob in Ihrer .env APP_BIND=0.0.0.0 gesetzt ist (mit dem Standard 127.0.0.1 ist das UI nur vom Server selbst erreichbar - siehe Schritt 4) und ob Port 7000 in Ihrer Firewall (z. B. beim Cloud-Anbieter) freigegeben ist. Tippen Sie die Adresse als http://... (nicht https://), solange Sie keine Domain eingerichtet haben.

Die KI antwortet nicht: Meist fehlt das LLM. Stellen Sie sicher, dass Sie entweder im Cookbook ein Modell heruntergeladen oder in den Einstellungen einen gültigen API-Schlüssel hinterlegt haben. Bei lokalen Modellen lohnt ein Blick auf die Auslastung mit docker stats - läuft der RAM voll, wählen Sie ein kleineres Modell.

Ein Container startet nicht (restarting/exited): Die Ursache steht in den Logs: docker compose logs <dienstname>. Häufig ist ein belegter Port 80/443 schuld - mit ss -tlnp | grep -E ':80|:443' finden Sie den blockierenden Prozess.

Weitere Tipps für den Betrieb

• Mail-Konten anbinden: Tragen Sie Ihre IMAP/SMTP-Daten in den Einstellungen ein - nutzen Sie dafür unbedingt App-Passwörter statt Ihrer regulären Login-Daten. Beachten Sie: Odysseus unterstützt aktuell nur IMAP/SMTP mit Passwort-Authentifizierung, kein OAuth. Outlook bzw. Microsoft 365 funktioniert damit derzeit nicht. Ein App-Passwort setzt zudem aktivierte Zwei-Faktor-Authentifizierung beim Anbieter voraus (etwa bei Gmail).
• Lokal vs. API realistisch einschätzen: Die 4 GB RAM aus der Voraussetzungs-Tabelle gelten für die reine API-Nutzung. Lokale Inferenz braucht deutlich mehr - schon ein quantisiertes 8B-Modell belegt rund 5 bis 6 GB plus Kontext - und läuft auf reinen CPU-Seeds spürbar langsam. Für kleine Seeds ist der API-Weg daher meist die realistischere Wahl; auch das README empfiehlt: „small hosts can connect to API or remote model servers instead". Wenn Sie lokal testen möchten, starten Sie in der 4B-Klasse (z. B. qwen3-4b) und richten Sie sich nach dem Kompatibilitäts-Score des Cookbooks. Erst wenn RAM und VRAM nicht voll laufen, tasten Sie sich an größere Modelle heran.
• Kosten im Blick behalten: Externe APIs rechnen pro Token ab, lokale Modelle kosten Strom und Hardware. Behalten Sie bei autonomen Agenten den Verbrauch im Auge.
• Bugs melden: Falls etwas nicht funktioniert, lohnt ein Blick in die offiziellen GitHub Issues - oft gibt es dort schon einen Workaround.