Odysseus Deployment in der Praxis: In 30 Minuten ein komplett selbst gehostetes KI-Workspace-Setup

Ein-Satz-Überblick: Willst du aus dem ChatGPT/Claude-Web heraus „ausbrechen“ und das komplette KI-Workspace-Setup auf deinem eigenen Rechner betreiben? Dieser Artikel führt dich Schritt für Schritt durch Odysseus — eine lokal-first, datenschutz-first Alternative, die ChatGPT selbst hostet.

Projektüberblick

Odysseus ist ein selbst gehostetes KI-Workspace (Self-hosted AI Workspace) des GitHub-Users pewdiepie-archdaemon, Open Source unter der MIT-Lizenz. Ziel ist es: Du sollst auf deinem eigenen Rechner die UI-Erfahrung von ChatGPT/Claude haben — aber alle Daten, alle Gespräche und alle Tool-Aufrufe bleiben lokal.

Im Vergleich zu klassischen ChatGPT-Apps ist der Unterschied klar:

• Chat: Übernimm beliebige lokale oder entfernte Modelle (vLLM / llama.cpp / Ollama / OpenRouter / OpenAI / GitHub Copilot)
• Agent: Wirklich „hands-on“ — ein Agent, der mit MCP / Web / Dateien / Shell / Skills / Memory arbeiten kann (basierend auf opencode)
• Cookbook: Scannt automatisch die Hardware deines Systems, empfiehlt Modelle, die laufen können, und bietet „One-Click Download + Service starten“ (basierend auf llmfit, VRAM-aware)
• Deep Research: Mehrstufige Recherche — abrufen + lesen + synthetisieren — mit Ausgabe als visueller Report (umgebaut aus Tongyi DeepResearch)
• Compare: Mehrere Modelle blind gegeneinander testen und das wirklich brauchbare, ohne Bias auswählen
• Documents: Du schreibst Text, die KI unterstützt daneben — nicht umgekehrt
• Memory / Skills: Langzeit-„Erinnerungen“ + Skills-System — der Agent versteht dich mit der Zeit immer besser (ChromaDB + fastembed ONNX)
• Email: IMAP/SMTP Posteingang — KI übernimmt Auto-Kategorisierung, Zusammenfassungen, Entwürfe für Antworten und Spam-Abwehr
• Notes & Tasks / Calendar: Notizen + Tasks + Kalender, Sync via CalDAV mit Radicale / Nextcloud / Apple / Fastmail
• PWA-Unterstützung: Zugriff vom Handy fühlt sich nicht schlechter an als am Desktop — und lässt sich aufs Homescreen „installieren“

Kurz gesagt: Das ist kein Chat-Fenster, sondern eine komplette KI-Umgebung — alles auf deinem Rechner, keine Cloud.

Schwierigkeit / Dauer / Nutzen

• Schwierigkeit: ⭐⭐⭐ (mittel; du solltest Docker- und Python-Grundlagen kennen)
• Dauer: 30–45 Minuten (Docker-Pfad); 1 Stunde (native Installation + Anbindung an ein lokales Modell)
• Nutzen:
  • Eine vollständig funktionsfähige selbst gehostete KI-Workspace-Lösung aufsetzen
  • Den typischen Architekturaufbau von „local-first“-KI verstehen (FastAPI + ChromaDB + SearXNG + ntfy)
  • Ollama / vLLM / OpenAI-kompatible APIs in ein gemeinsames UI integrieren
  • Verstehen, wie Cookbook Modelle automatisch auswählt, GPU durchreicht und ein Memory-System bereitstellt — „Long-Tail“-Fähigkeiten, die sich am Ende richtig gut anfühlen

Zielgruppen-Profil

• Wer nicht mehr für ChatGPT Plus / Claude Pro zahlen will und KI-Daten lieber lokal hält
• Wer Open-Source-Modelle auf NUCs/Workstations/Servern mit 8G/16G/24G VRAM laufen lassen möchte — aber ein einheitliches Interface haben will
• Full-Stack / Indie-Developer, die Chat / E-Mail / Kalender / Agent-Tasks in einem Panel bündeln wollen
• Interessierte DevOps-/Platform Engineers, die ein Engineering-Beispiel für eine „Production-grade“ FastAPI-App sehen wollen
• Leute, die bereits für Cloud-LLMs bezahlt haben und eine Lösung suchen, die weniger weh tut

Wenn du nur ein leichtgewichtiges Chat-UI suchst, ist Odysseus möglicherweise nicht das Richtige — es hat viele Funktionen und ist beim Einstieg etwas komplexer als Open WebUI, dafür bekommst du im Gegenzug das ganze Paket: E-Mail, Memory, Cookbook, Agent.

Core Dependencies und Umgebung

Minimalanforderungen:

Optional / Erweiterungen:

Vollständiger Projekt-Tree

odysseus/
├── app.py                    # FastAPI-Entry
├── setup.py                  # Initialisierungs-Skript (admin / DB / Verzeichnisse anlegen)
├── requirements.txt          # Kern-Python-Dependencies
├── requirements-optional.txt # optionale Dependencies (PDF/Office/Audio/STT)
├── docker-compose.yml        # Default-Orchestrierung (CPU)
├── docker-compose.gpu-nvidia.yml  # NVIDIA GPU Override
├── docker-compose.gpu-amd.yml     # AMD ROCm Override
├── Dockerfile
├── core/                     # Infrastruktur-Schicht
│   ├── auth.py               # Authentifizierung / Session
│   ├── database.py           # SQLAlchemy Initialisierung
│   ├── middleware.py
│   ├── constants.py
│   └── atomic_io.py
├── src/                      # Business-Logik-Schicht
│   ├── llm_core.py           # LLM-Abstraktion
│   ├── agent_loop.py         # Agent-Loop
│   ├── agent_tools.py        # Agent-Toolset
│   ├── chat_processor.py     # Chat-Verarbeitung
│   ├── cookbook_serve_lifecycle.py  # Cookbook Modell-Service-Lifecycle
│   ├── memory_vector.py      # ChromaDB Langzeit-„Memory“
│   ├── deep_research.py      # Deep Research
│   └── ...
├── routes/                   # FastAPI Routes (40+ Module)
│   ├── chat_routes.py
│   ├── agent_routes.py
│   ├── cookbook_routes.py    # Modell-Empfehlung/Download
│   ├── memory_routes.py
│   ├── email_routes.py
│   ├── calendar_routes.py
│   └── ...
├── services/                 # Hintergrund-Services
│   ├── docs/                 # Dokumentenverarbeitung
│   ├── hwfit/                # Hardware-Scan (Cookbook)
│   ├── memory/               # Memory-Service
│   ├── research/             # Research-Service
│   ├── search/               # Suche
│   ├── stt/ tts/             # Speech-to-Text / Text-to-Speech
│   └── shell/                # Shell-Tools
├── static/                   # Frontend (index.html + JS/CSS)
├── docs/                     # Doku-Seite + Screenshots + Demo
├── config/                   # Config für Subservices wie SearXNG
├── companion/                # Desktop Companion (macOS)
└── data/                     # Benutzerdaten (gitignored, Laufzeit generiert)
    ├── app.db                # SQLite
    ├── chroma/               # Vektorbibliothek
    ├── uploads/
    ├── personal_docs/
    └── huggingface/          # Modell-Cache

Im Verzeichnis musst du dich nur um app.py / docker-compose.yml / .env kümmern — der Rest wird von Docker für dich erledigt.

Schritt-für-Schritt

Schritt 1: Repository klonen

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

Schritt 2: .env vorbereiten (optional, aber empfohlen)

cp .env.example .env

Die minimal nutzbare .env sieht so aus:

# === LLM-Anbindung ===
LLM_HOST=localhost
# Wenn du Cloud-APIs nutzen willst, greife in dem Container über host.docker.internal auf deinen lokalen Ollama zu
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1

# === Ports und Bindings ===
APP_BIND=127.0.0.1
APP_PORT=7000

# === Sicherheit (kritisch!) ===
AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=false   # nur auf true stellen, wenn du HTTPS hinter einem Reverse Proxy nutzt
ODYSSEUS_ADMIN_USER=admin
# ODYSSEUS_ADMIN_PASSWORD=  # wenn leer gelassen, wird beim ersten Start zufällig generiert und ausgegeben

# === Suche (SearXNG) ===
SEARXNG_INSTANCE=http://searxng:8080

OLLAMA_HOST=0.0.0.0:11434 ollama serve

Schritt 3: Ein-Klick-Start mit Docker (empfohlener Pfad)

docker compose up -d --build

Beim Build werden Basis-Images geholt + Python-Dependencies installiert, das dauert beim ersten Mal etwa 3–5 Minuten. Wenn du siehst, dass die vier Container odysseus / chromadb / searxng / ntfy alle healthy / running sind, ist es geschafft:

docker compose ps

Öffne http://localhost:7000 — der erste Screen ist die Login-Seite. Das initiale Admin-Passwort steht in den Terminal-Logs:

docker compose logs --tail=200 odysseus | grep -i "temporary\|admin\|password"

Du solltest etwas Ähnliches sehen:

[odysseus] Created admin user 'admin' with temporary password: aB3x-9pQz-2vRt

Schritt 4: Prüfen, ob alle Services gesund sind

# 1. Container-Status
docker compose ps

# 2. Logs von Odysseus ansehen (Achtung: beim ersten Start kann das Laden von Modellen verzögert sein)
docker compose logs --tail=120 odysseus

# 3. Ob ChromaDB wirklich läuft (kein HTTP-Downgrade)
docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore|DEGRADED"

Wenn du DEGRADED siehst, liegt es sehr wahrscheinlich an einem Konflikt zwischen chromadb-client und chromadb. Die Diagnose findest du später im Abschnitt „Häufige Probleme“.

Schritt 5: Dein erstes Modell anbinden

Geh zu Settings → Models / Providers, wähle abhängig von deinem Setup einen Pfad:

Pfad A: Ollama läuft bereits (am einfachsten)

Base URL:  http://host.docker.internal:11434/v1
API Key:   (leer lassen)
Model:     qwen2.5:7b (oder jedes andere Modell, das du lokal hast)

Pfad B: Cookbook soll automatisch herunterladen + starten

Gehe in Cookbook: Es scannt deinen VRAM, empfiehlt laufbare Open-Source-Modelle und vergibt eine Bewertung (fit score). Klick auf „Download“, dann zieht es das Modell via huggingface-cli nach ./data/huggingface/ und startet es anschließend direkt mit llama.cpp / vLLM.

Pfad C: Cloud-API anbinden — genau darüber reden wir heute

Die Provider-Konfiguration von Odysseus ist protokollgetrieben: Das heißt, jede Service-Implementierung, die korrekt auf v1/chat/completions oder v1/messages reagiert, kann direkt eingetragen werden — nicht nur OpenAI/Anthropic offiziell, sondern auch selbst gebaute Gateways oder Drittanbieter-Forwarder.

In meinem Setup läuft die „Alltags-Agent“-Kategorie (Code ausführen / lange Dokumente) über Cloud-APIs — aus zwei Gründen:

1. Ein 24G-Setup und quantisierte 70B ist lokal schon grenzwertig; zusätzlich mehrere Agent-Runden führen in der Praxis häufig zu OOM
2. Claude/GPT-Modelle liegen bei komplexem Reasoning immer noch etwas vor Qwen2.5-Coder

Dann kommt aber das Problem — offizielle APIs sind teuer. Claude Opus: Eine Wochenrechnung knackt locker die 100-Dollar-Marke, das ist für private Nutzung im Grunde nur „für Anyscale arbeiten“.

Meine Lösung: Defapi. Dort nutze ich einen Endpoint, der kompatibel zu v1/messages ist:

# Odysseus Settings → Custom Anthropic Provider
Base URL:  https://api.defapi.org
API Key:   sk-xxxxx                    # im Defapi-Backend holen
Model:     anthropic/claude-sonnet-4.5 # oder haiku-4.5 / opus-4.6

Beispiel-Konfigurationen: Defapi Claude Sonnet 4.5 (für Programmierung/Langdokumente als Hauptarbeit), Claude Haiku 4.5 (für tägliche Agent-Aufrufe als bevorzugte, günstigere Option).

In der Praxis: Bei gleicher Gesprächs-/Task-Menge ist die monatliche Rechnung im Vergleich zu Anthropics offizieller API um mehr als die Hälfte niedriger. Und gleichzeitig gibt es keine echte Abweichung bei Modellfähigkeit, Agent-Tool-Calls oder Prompt-Formaten — denn das Ganze ist auf Protokollebene nur ein Proxy; das Modell selbst bleibt dasselbe. Dieses „protokollgetriebene“ Design passt perfekt zu Odysseus.

Pfad D: GitHub Copilot / OpenRouter etc. anbinden

Auch diese sind OpenAI-protokollkompatibel. Base URL entsprechend: https://api.githubcopilot.com / https://openrouter.ai/api/v1 — ohne weitere Ausführung.

Schritt 6: Erstes Chatten + erster Agent-Task

Zurück auf der Hauptseite: wähle ein Modell und wirf einen einfachen Prompt rein, um die Verbindung zu testen:

Stell dich mir in drei Sätzen vor, und gib mir dann eine Checkliste zur Performance-Diagnose für Linux, die ich heute nutzen kann.

Wenn das klappt, ist der LLM-Pfad durchgängig.

Als Nächstes testen wir Agent Mode: Erstelle eine neue Session, schalte auf „Agent“ und gib ein:

Liste die Zeilenzahlen aller .py-Dateien im aktuellen Verzeichnis auf und sag mir, welche Datei am ehesten refaktoriert werden sollte.

Der Agent plant selbst:

1. Rufe das shell-Tool auf und führe find . -name "*.py" | xargs wc -l aus
2. Entscheide nach dem Ergebnis
3. Gib Empfehlungen

Das ist der grundlegende Unterschied zwischen einem lokal-first Agent und dem ChatGPT-Web: Er kann wirklich „zupacken“, und deine Codes/Dateien/Terminal — er hat darauf Zugriff.

Schritt 7 (optional): GPU aktivieren

Dieser Schritt ist nur nötig, wenn du vLLM / SGLang / llama.cpp CUDA in der Art von „Heavyweight“-lokalem Inference nutzen willst. Wenn du nur Ollama oder Cloud-APIs verwendest, überspringe das.

NVIDIA:

# One-Click Diagnose
scripts/check-docker-gpu.sh

# NVIDIA Container Toolkit installieren (Ubuntu/Debian, braucht sudo)
scripts/check-docker-gpu.sh --install-nvidia-toolkit

# Nur nach erfolgreichem GPU-Passthrough Overlay aktivieren
scripts/check-docker-gpu.sh --enable-nvidia-overlay

# Verifizieren
docker compose exec odysseus nvidia-smi -L

In .env wird ergänzt:

COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml

AMD ROCm:

scripts/check-docker-amd-gpu.sh
# schreibe die ausgegebene RENDER_GID in die .env

COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
RENDER_GID=989

Schritt 8 (optional): Playwright MCP aktivieren (Browser-Agent)

Odysseus bringt ein paar MCP-Server mit, aber der Browser-Server muss erst per npx geholt werden:

npx -y @playwright/mcp@latest --version

Starte den Odysseus-Container neu: Im Agent kannst du dann Browser-MCP nutzen (Screenshots, Navigation, Formulare ausfüllen):

Öffne https://news.ycombinator.com, hole die ersten 10 Titel und Links, und fasse sie zu 5 zentralen Themen zusammen.

Schritt 9 (optional): Unter Windows nativ laufen lassen

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

Das Skript erstellt automatisch ein venv → installiert Dependencies → führt setup aus → startet uvicorn. Öffne dann http://localhost:7000.

Schritt 10 (optional): Auch vom Handy aus nutzen

Unter der Voraussetzung, dass Tailscale bereits verbunden ist:

ODYSSEUS_HOST=0.0.0.0 docker compose up -d
# oder in der .env eintragen
APP_BIND=0.0.0.0

Aber: Nacktes HTTP auf LAN / Tailscale auszusetzen ist nicht sicher — dringend empfohlen ist, HTTPS mit mkcert zu aktivieren:

mkcert -install
mkcert -cert-file cert.pem -key-file key.pem 100.x.y.z   # deine Tailscale-IP

python -m uvicorn app:app --host 0.0.0.0 --port 7000 \
  --ssl-certfile=cert.pem --ssl-keyfile=key.pem

Am Handy öffnest du https://<tailscale-ip>:7000. Dann PWA auf dem Homescreen installieren — das Erlebnis ist fast identisch mit einer nativen App.

Häufige Probleme

Q1: Port 7000 belegt (häufig auf macOS)

macOS AirPlay belegt standardmäßig 7000. Zwei Lösungen:

# Methode 1: Port in der .env ändern
APP_PORT=7001
docker compose up -d
# Browser auf http://localhost:7001

# Methode 2: Apple-Menü → Systemeinstellungen → Allgemein → AirPlay-Empfänger → aus

Q2: ChromaDB startet, aber Logs melden DEGRADED

Typisch, wenn chromadb-client und chromadb gleichzeitig installiert sind — dann fällt es oft still auf einen HTTP-only Modus zurück, wodurch die Vektor-Funktionalität ausfällt. Fix:

# Im laufenden Container (oder in deiner lokalen venv)
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb
docker compose restart odysseus

Validierung: docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore" — dann sollte die Initialisierung erfolgreich sein und kein DEGRADED mehr auftauchen.

Q3: Cookbook sieht meine GPU nicht — nur iGPU oder CPU

Docker exponiert standardmäßig alle GPUs des Hosts, aber wenn du nur die iGPU oder eine andere Karte mountest, liegt es meistens daran, dass entweder das NVIDIA Container Toolkit nicht installiert ist oder nicht korrekt konfiguriert wurde (z. B. fehlt nvidia-ctk runtime configure --runtime=docker):

# Diagnose
scripts/check-docker-gpu.sh
# anhand der Ausgabe siehst du, welcher Schritt fehlt

# Einmalig installieren + konfigurieren (Ubuntu/Debian)
scripts/check-docker-gpu.sh --install-nvidia-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Q4: GPU Passthrough klappt, aber llama.cpp-Logs sagen Unable to find cudart

Das Gerät ist nicht das Problem — es fehlt der CUDA-Runtime. Diese Schicht kann Docker für dich nicht beheben. Geh zu Cookbook → Dependencies und installiere den CUDA-Build von llama-cpp-python neu:

Cookbook öffnen → Dependencies → llama-cpp-python finden → Reinstall (CUDA build)

Dann führt es intern pip install --no-cache-dir llama-cpp-python[cuda] aus, in etwa 2–3 Minuten.

Q5: Outlook / Office 365 Postfach nicht erreichbar

Das Odysseus-E-Mail-Modul unterstützt derzeit nur IMAP mit Benutzername+Passwort. Microsoft hat nach 2024 die klassischen Passwort-Logins im Wesentlichen deaktiviert — OAuth ist nötig. Das ist aktuell eine bekannte Einschränkung.

Temporäre Workarounds: Nutze Gmail / Fastmail / ein selbst gehostetes Mailkonto oder verwende ein Microsoft App Password (für Accounts mit 2FA), um Passwort-Login zu simulieren.

Q6: Öffentlich ins Internet — wie macht man das sicher?

Direkt APP_BIND=0.0.0.0 ins öffentliche Netz zu hängen = Katastrophe. LOCALHOST_BYPASS umgeht Authentifizierung, und der Agent hat zusätzlich Shell-Tools — in Shodan werden innerhalb von 24 Stunden massenhaft nackte Instanzen gefunden.

Der richtige Weg:

[Internet] → Cloudflare Access / Tailscale / WireGuard
            → Caddy / Nginx / Traefik (HTTPS Termination)
            → http://127.0.0.1:7000 (Odysseus, localhost-Bind beibehalten)

Und in .env:

AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=true

Q7: Wie kontrolliert man die Cloud-API-Kosten?

Lass uns den Problem-Punkt aus Schritt 5 — Pfad C — kurz ausführen.

Wenn man das privat macht, ordne ich die drei Ansätze nach Kostenhöhe absteigend:

1. Offizielle API anbinden — bestes Erlebnis, aber am teuersten. Claude Opus + häufige Agent-Aufrufe: Eine Wochenrechnung über 100 Dollar ist völlig normal
2. Protokoll-kompatible Transaktions-/Proxy-Schicht (ich nutze Defapi) — gleiche Claude/GPT/Gemini-Modelle, monatliche Rechnung deutlich niedriger als bei der offiziellen API (um grob eine ganze Stufe). Der konkrete Unterschied hängt ab; vom wöchentlichen 100-Dollars-Niveau auf ein monatliches 100-Dollars-Niveau, also in genau dieser Größenordnung. Vorteil: Protokollebene ist komplett kompatibel — Odysseus bleibt bei der Konfiguration, du musst keine Prompt-/Agent-Codeänderungen machen
3. Lokale quantisierte Modelle — in Cookbook z. B. ein Q4_K_M GGUF nehmen, mit 16G VRAM laufen 30B grob im Rahmen, keine API-Kosten, aber deutlich langsamere Inferenz und bei komplexen Tasks eine Stufe schlechter in der Qualität

Meine Praxis-Kombi: Chat + Deep Research über Defapi Claude Sonnet 4.5, Agent Tool-Calls über Claude Haiku 4.5 (günstig), einfache Klassifikations-/Zusammenfassungs-Tasks über lokal quantisiertes Qwen2.5. Drei Provider werden jeweils separat abgerechnet, sie stören sich nicht — nach einem Monat landet man bei zweistelligen RMB-Beträgen.

Weiterführende Lektüre / Richtung für Fortgeschrittene

• MCP-Ökosystem: Die von Odysseus automatisch registrierten eingebauten MCPs enthalten playwright (Browser) / filesystem / shell. Du kannst auch eigene MCP-Server schreiben, sie in mcp_servers/ registrieren und dem Agent verfügbar machen
• Skills-System: routes/skills_routes.py verwaltet wiederverwendbare „Skill“-Snippets — ähnlich wie OpenClaw Skills: einmal schreiben, dann in jeder Session abrufen
• Tailscale + mkcert HTTPS: In der letzten Sektion wurde der Basis-Flow gezeigt; als Upgrade könntest du automatische Erneuerung und DNS-01-Challenges hinzufügen
• Reverse-Proxy-Kombination: Caddy mit HTTPS + Cloudflare Proxy, damit bekommst du praktisch „Public Internet ohne Wartung“
• CalDAV-Sync: Selbst gehostetes Radicale (ein schlanker CalDAV-Service) — Odysseus Kalender lässt sich bidirektional mit dem Smartphone-Kalender synchronisieren
• E-Mail AI: automatisch in Buckets einsortieren: Wenn du IMAP angebunden hast, trainiere für eine Weile — dann klassifiziert es automatisch „dringend / normal / Spam“, Entwürfe werden vorab geschrieben, du musst nur noch „Senden“ klicken
• Cookbook Remote-Server: Cookbook → Settings → Servers kannst du eine entfernte GPU-Maschine konfigurieren. Modelle laufen/werden über SSH geholt — Host klein, GPU weit weg, sieht sauber aus
• Deep Research: mehrstufige Reports: Umbau aus Ali Tongyi DeepResearch — über SearXNG viele Quellen holen → zusammenfassen → synthetisieren — geeignet für Wettbewerbs-/Industrie-Recherche
• Routing für mehrere Provider: In Odysseus unterschiedliche Provider für Chat/Agent/Research konfigurieren — lokal Ollama erledigt 80% Alltagsgespräche, komplexe Fragen gehen in die Cloud; Kosten und Experience stimmen zusammen

GitHub-Repository: pewdiepie-archdaemon/odysseus. Doku liegt im docs/-Ordner, Roadmap in ROADMAP.md. Wenn du beitragen willst, schau in CONTRIBUTING.md.