Odysseus en conditions réelles : monter un poste de travail IA auto-hébergé en 30 minutes

Brève présentation : Et si vous pouviez « sortir » de l’interface web de ChatGPT / Claude et installer tout un poste de travail IA sur votre propre machine ? Cet article vous guide pour faire tourner Odysseus — une alternative à ChatGPT auto-hébergée, locale d’abord, axée sur la confidentialité.

Présentation du projet

Odysseus est un poste de travail IA auto-hébergé (Self-hosted AI Workspace), issu de GitHub par l’utilisateur pewdiepie-archdaemon et publié en open source sous licence MIT. Son objectif : vous offrir, sur votre propre machine, l’expérience d’interface de ChatGPT / Claude, tout en gardant toutes les données, toutes les conversations et tous les appels d’outils… en local.

Par rapport aux applications classiques de type ChatGPT, les différences sont très nettes :

• Chat : prenez en charge n’importe quel modèle local ou distant (vLLM / llama.cpp / Ollama / OpenRouter / OpenAI / GitHub Copilot)
• Agent : de véritables agents qui peuvent « faire », avec MCP / Web / fichiers / Shell / Skills / mémoire (basé sur opencode)
• Cookbook : analyse automatique du matériel de votre machine, recommandation des modèles capables de tourner, téléchargement + lancement en un clic (basé sur llmfit, VRAM-aware)
• Deep Research : recherche multi-étapes, extraction + lecture + synthèse, production de rapports visuels (dérivé de Tongyi DeepResearch)
• Compare : mise en concurrence de plusieurs modèles à l’aveugle, sans biais, pour sélectionner le véritable meilleur
• Documents : vous écrivez du texte, l’IA vous assiste à côté — pas l’inverse
• Memory / Skills : mémoire à long terme + système de compétences, l’agent vous « comprend » de mieux en mieux (ChromaDB + fastembed ONNX)
• Email : boîte de réception IMAP/SMTP, tri automatique, résumés, brouillons de réponse, anti-spam
• Notes & Tasks / Calendar : notes + tâches + calendrier, synchronisation CalDAV avec Radicale / Nextcloud / Apple / Fastmail
• Support PWA : une expérience mobile qui ne perd pas face au desktop, avec possibilité d’ajout à l’écran d’accueil

En une phrase : ce n’est pas juste une fenêtre de chat — c’est tout un environnement IA, chez vous, sur votre machine, sans passer par le cloud.

Difficulté / durée / bénéfices

• Difficulté : ⭐⭐⭐ (niveau moyen : nécessite de comprendre les bases de Docker et de Python)
• Durée : 30–45 minutes (parcours via Docker) ; 1 heure (installation native + raccord d’un modèle local)
• Bénéfices :
  • Mettre en place un poste IA auto-hébergé complet, avec toutes les fonctions
  • Comprendre l’architecture typique des applications IA « locales d’abord » (FastAPI + ChromaDB + SearXNG + ntfy)
  • Raccorder les API compatibles Ollama / vLLM / OpenAI dans une même interface
  • Apprendre les capacités « long tail » mais vraiment plaisantes : sélection automatique des modèles, transparence GPU, système de mémoire

Profil des lecteurs ciblés

• Vous n’avez plus envie de payer ChatGPT Plus / Claude Pro, et vous voulez garder les données IA en local
• Sur un NUC / poste de travail / serveur avec 8G / 16G / 24G de VRAM, vous voulez faire tourner des modèles open source, avec une interface unifiée
• Développeurs full-stack / indépendants, vous souhaitez regrouper chat / email / calendrier / tâches d’Agent dans un seul panneau
• Vous êtes intéressé par l’« auto-hébergement » : vous êtes plutôt ops / ingénierie plateforme, et vous voulez voir un modèle d’ingénierie « niveau production » avec FastAPI
• Vous avez déjà payé pour des LLM côté cloud et vous cherchez une façon de faire qui fait moins mal à la facture

Si vous cherchez juste une interface de chat légère, Odysseus n’est peut-être pas fait pour vous : il a beaucoup de fonctions, et l’onboarding est un peu plus complexe qu’Open WebUI, mais en échange vous obtenez toute la suite : email, mémoire, Cookbook, Agent.

Dépendances clés et environnement

Configuration minimale :

Dépendances optionnelles / améliorations :

Arbre complet de la structure du projet

odysseus/
├── app.py                    # Point d’entrée FastAPI
├── setup.py                  # Script d’initialisation (crée admin / base de données / dossiers)
├── requirements.txt          # Dépendances Python principales
├── requirements-optional.txt # Dépendances optionnelles (PDF/Office/voix/STT)
├── docker-compose.yml        # Orchestration par défaut (CPU)
├── docker-compose.gpu-nvidia.yml  # Override GPU NVIDIA
├── docker-compose.gpu-amd.yml     # Override GPU AMD ROCm
├── Dockerfile
├── core/                     # Couche d’infrastructure
│   ├── auth.py               # Authentification / sessions
│   ├── database.py           # Initialisation SQLAlchemy
│   ├── middleware.py
│   ├── constants.py
│   └── atomic_io.py
├── src/                      # Couche de logique métier
│   ├── llm_core.py           # Abstraction du grand modèle
│   ├── agent_loop.py         # Boucle de l’Agent
│   ├── agent_tools.py        # Outils de l’Agent
│   ├── chat_processor.py     # Traitement du chat
│   ├── cookbook_serve_lifecycle.py  # Cycle de vie du service Cookbook
│   ├── memory_vector.py      # Mémoire long terme ChromaDB
│   ├── deep_research.py      # Recherche approfondie
│   └── ...
├── routes/                   # Routes FastAPI (40+ modules)
│   ├── chat_routes.py
│   ├── agent_routes.py
│   ├── cookbook_routes.py    # Recommandation / téléchargement de modèles
│   ├── memory_routes.py
│   ├── email_routes.py
│   ├── calendar_routes.py
│   └── ...
├── services/                 # Services en arrière-plan
│   ├── docs/                 # Traitement des documents
│   ├── hwfit/                # Scan matériel (Cookbook)
│   ├── memory/               # Service mémoire
│   ├── research/             # Service de recherche
│   ├── search/               # Recherche
│   ├── stt/ tts/             # Reconnaissance vocale (STT) / synthèse vocale (TTS)
│   └── shell/                # Outil Shell
├── static/                   # Frontend (index.html + JS/CSS)
├── docs/                     # Site docs + captures + démo
├── config/                   # Config de sous-services comme SearXNG
├── companion/                # Compagnon desktop (macOS)
└── data/                     # Données utilisateur (gitignored, générées à l’exécution)
    ├── app.db                # SQLite
    ├── chroma/               # Base vectorielle
    ├── uploads/
    ├── personal_docs/
    └── huggingface/          # Cache des modèles

Dans le dossier, vous n’avez qu’à vous soucier de app.py / docker-compose.yml / .env ; tout le reste est géré par Docker.

Étapes pas à pas

Étape 1 : Cloner le dépôt

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

Étape 2 : Préparer .env (optionnel, mais recommandé)

cp .env.example .env

Le .env minimal utilisable ressemble à ça :

# === Points d’entrée LLM ===
LLM_HOST=localhost
# Si vous utilisez une API cloud, accédez à votre Ollama local depuis le conteneur via host.docker.internal
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1

# === Ports et binding ===
APP_BIND=127.0.0.1
APP_PORT=7000

# === Sécurité (crucial !) ===
AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=false   # mettre true uniquement si vous reverse-proxy en HTTPS
ODYSSEUS_ADMIN_USER=admin
# ODYSSEUS_ADMIN_PASSWORD=  # si laissé vide, le mot de passe est généré aléatoirement à la première fois et affiché

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

OLLAMA_HOST=0.0.0.0:11434 ollama serve

Étape 3 : Démarrage express Docker (recommandé)

docker compose up -d --build

La construction va tirer les images de base + installer les dépendances Python. La première fois : environ 3–5 minutes. Quand les quatre conteneurs odysseus / chromadb / searxng / ntfy sont healthy / running, c’est bon.

docker compose ps

Ouvrez http://localhost:7000 : la première page est l’écran de connexion. Le mot de passe admin initial est dans les logs du terminal :

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

Vous devriez voir quelque chose comme :

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

Étape 4 : Vérifier que tous les services sont sains

# 1. Statut des conteneurs
docker compose ps

# 2. Logs d’Odysseus (attention : au premier démarrage, le téléchargement des modèles peut provoquer un délai)
docker compose logs --tail=120 odysseus

# 3. ChromaDB est-il vraiment opérationnel (pas une dégradation HTTP)
docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore|DEGRADED"

Si vous voyez DEGRADED, c’est très probablement un conflit entre chromadb-client et chromadb. Le diagnostic est détaillé plus bas dans la section « Questions fréquentes ».

Étape 5 : Brancher votre premier modèle

Allez dans Settings → Models / Providers, puis choisissez un chemin selon votre configuration :

Chemin A : Ollama tourne déjà (le plus simple)

Base URL:  http://host.docker.internal:11434/v1
API Key:   (laissez vide)
Model:     qwen2.5:7b (ou n’importe quel modèle que vous avez localement)

Chemin B : utiliser Cookbook pour télécharger + lancer automatiquement

Entrez dans Cookbook : il scanne votre VRAM, recommande des modèles open source capables de tourner, vous donne une note (fit score). Cliquez sur « Download » : il passe huggingface-cli pour télécharger le modèle dans ./data/huggingface/, puis lance directement un service avec llama.cpp / vLLM.

Chemin C : utiliser une API cloud — c’est ce qu’on va détailler aujourd’hui

La configuration des Providers d’Odysseus est pilotée par le protocole : autrement dit, tout service capable de répondre correctement aux endpoints v1/chat/completions ou v1/messages, peut être branché via Base URL — OpenAI, Anthropic officiels, gateway perso, relais tiers… tout suit ce même schéma.

Dans mon déploiement, pour « l’Agent au quotidien (exécuter du code / longs documents) », je passe par l’API cloud, pour deux raisons :

1. En local, avec une carte 24G, faire tourner un modèle 70B quantifié est déjà bien exigeant ; en lançant en plus des appels multi-tours d’Agent, on finit souvent par un OOM.
2. Des modèles de pointe comme Claude / GPT sont encore nettement meilleurs que Qwen2.5-Coder sur la réflexion complexe.

Le souci, c’est que — les API officielles sont trop chères. Le relevé de Claude Opus dépasse facilement la barre de 100 dollars par semaine : en pratique, c’est payer pour Anyscale.

Ma solution actuelle consiste à utiliser Defapi, en utilisant l’endpoint compatible v1/messages :

# Odysseus Settings → Custom Anthropic Provider
Base URL:  https://api.defapi.org
API Key:   sk-xxxxx                    # à récupérer dans le backend de defapi.org
Model:     anthropic/claude-sonnet-4.5 # ou haiku-4.5 / opus-4.6

Exemples de config : Defapi Claude Sonnet 4.5 (grosse charge pour la programmation / longs documents), Claude Haiku 4.5 (choix recommandé pour les appels d’Agent au quotidien, moins cher).

En pratique, pour le même volume de conversations/tâches, la facture mensuelle baisse de plus de moitié par rapport à un branchement Anthropic officiel. Et pourtant — les capacités du modèle, les appels d’outils d’Agent, et les formats de prompt — aucune différence : c’est une délégation au niveau protocole, le modèle de base reste le même. Cette approche « pilotée par protocole » d’Odysseus colle naturellement très bien.

Chemin D : connecter GitHub Copilot / OpenRouter, etc.

Ces deux options sont aussi compatibles avec le protocole OpenAI : renseignez simplement la Base URL à https://api.githubcopilot.com / https://openrouter.ai/api/v1 respectivement, et c’est tout — pas besoin d’aller plus loin.

Étape 6 : Premier chat + première tâche d’Agent

Retournez sur l’interface principale : choisissez un modèle, envoyez un prompt simple pour vérifier la connectivité :

Présentez-vous en trois phrases, puis donnez-moi une checklist de diagnostic des performances Linux à utiliser aujourd’hui.

Si ça passe, cela confirme que la connexion au modèle LLM est OK.

Ensuite, testez le mode Agent : créez une nouvelle session, passez en « Agent », puis saisissez :

Donnez-moi le nombre de lignes de tous les fichiers .py dans le répertoire courant, puis dites-moi quel fichier mérite le plus une refonte.

L’Agent va planifier tout seul :

1. Appeler l’outil shell pour exécuter find . -name "*.py" | xargs wc -l
2. Récupérer le résultat et l’analyser
3. Proposer une recommandation

C’est la différence fondamentale entre un Agent « local-first » et ChatGPT via le web : il peut réellement « agir », et il a accès à votre code, vos fichiers et votre terminal.

Étape 7 (optionnel) : activer le GPU

Cette étape ne sert que si vous voulez exécuter une inférence locale « lourde » type vLLM / SGLang / llama.cpp CUDA. Si vous utilisez seulement Ollama ou une API cloud, vous pouvez passer.

NVIDIA :

# Diagnostic rapide
scripts/check-docker-gpu.sh

# Installer NVIDIA Container Toolkit (Ubuntu/Debian, nécessite sudo)
scripts/check-docker-gpu.sh --install-nvidia-toolkit

# Activer l’overlay seulement après validation du GPU en passthrough
scripts/check-docker-gpu.sh --enable-nvidia-overlay

# Vérifier
docker compose exec odysseus nvidia-smi -L

Dans .env, ça ajoute :

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

AMD ROCm :

scripts/check-docker-amd-gpu.sh
# Écrire le RENDER_GID issu de la sortie dans .env

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

Étape 8 (optionnel) : activer Playwright MCP (proxy navigateur)

Odysseus inclut déjà quelques serveurs MCP, mais celui côté navigateur nécessite de faire un npx au préalable :

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

Redémarrez le conteneur Odysseus : dans Agent, vous pourrez utiliser MCP du navigateur (capture d’écran, navigation, remplissage de formulaires) :

Ouvrez https://news.ycombinator.com, récupérez les 10 premiers titres et leurs liens, puis résumez-les en 5 sujets essentiels.

Étape 9 (optionnel) : exécuter en natif sous Windows

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

Le script crée automatiquement un venv → installe les dépendances → lance setup → démarre uvicorn. Ouvrez http://localhost:7000.

Étape 10 (optionnel) : permettre l’accès depuis le téléphone

Si Tailscale est déjà connecté :

ODYSSEUS_HOST=0.0.0.0 docker compose up -d
# ou dans .env
APP_BIND=0.0.0.0

Mais exposer en HTTP brut sur le LAN / Tailscale n’est pas sûr : je recommande fortement d’ajouter HTTPS via mkcert :

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

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

Sur le téléphone : accéder à https://<ip-tailscale>:7000 ; installez la PWA sur l’écran d’accueil, et l’expérience sera presque identique à celle d’une application native.

Dépannage des questions fréquentes

Q1 : le port 7000 est déjà pris (souvent sur macOS)

Sur macOS, AirPlay prend par défaut 7000. Deux solutions :

# Méthode 1 : changer de port dans .env
APP_PORT=7001
docker compose up -d
# Navigateur : ouvrir http://localhost:7001

# Méthode 2 : menu Pomme → Réglages système → Général → Récepteur AirPlay → désactiver

Q2 : ChromaDB démarre, mais les logs indiquent DEGRADED

En général : chromadb-client et chromadb sont installés en même temps, et on tombe silencieusement en mode HTTP-only, ce qui fait perdre les capacités vectorielles. Correctif :

# Dans le conteneur en cours d’exécution (ou dans votre venv local)
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb
docker compose restart odysseus

Vérifier la réparation : docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore", vous devriez voir une initialisation réussie, sans DEGRADED.

Q3 : Cookbook ne voit pas mon GPU, je ne vois que iGPU ou CPU

Par défaut, Docker expose tous les GPU de la machine hôte, mais s’il n’est que iGPU ou une autre carte est montée, c’est quasiment toujours parce que NVIDIA Container Toolkit n’est pas installé / pas configuré :

nvidia-ctk runtime configure --runtime=docker:

# Diagnostic
scripts/check-docker-gpu.sh
# Regardez la sortie : elle vous dira à quelle étape ça manque

# Installer + config en une fois (Ubuntu/Debian)
scripts/check-docker-gpu.sh --install-nvidia-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Q4 : le passthrough GPU marche, mais les logs llama.cpp disent Unable to find cudart

Le device n’est pas le problème : il manque le CUDA runtime. Docker ne peut pas résoudre cette couche. Allez dans Cookbook → Dependencies et réinstallez une build CUDA de llama-cpp-python :

Ouvrez Cookbook → Dependencies → trouvez llama-cpp-python → Reinstall (build CUDA)

Il va faire pip install --no-cache-dir llama-cpp-python[cuda], environ 2–3 minutes.

Q5 : boîte mail Outlook / Office 365 inaccessible

Le module email d’Odysseus ne supporte pour l’instant que l’authentification IMAP + nom d’utilisateur / mot de passe. Microsoft a largement désactivé la connexion par mot de passe « classique » après 2024 : il faut OAuth. C’est pour l’instant une contrainte connue.

Plan temporaire : utiliser Gmail / Fastmail / un email auto-hébergé, ou activer un Microsoft App Password (comptes avec 2FA) pour simuler une connexion par mot de passe.

Q6 : accéder depuis l’Internet — comment le faire de façon sûre ?

Exposer directement APP_BIND=0.0.0.0 à l’Internet = catastrophe. LOCALHOST_BYPASS contourne l’authentification, et l’Agent a aussi des outils shell : Shodan scanne et trouve en 24h plein d’instances « ouvertes au public ».

La bonne approche :

[Internet] → Cloudflare Access / Tailscale / WireGuard
            → Caddy / Nginx / Traefik (fin de TLS)
            → http://127.0.0.1:7000 (Odysseus, garder le binding localhost)

Et dans .env :

AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=true

Q7 : comment contrôler les dépenses des API cloud ?

On va détailler ici le problème du chemin C de l’étape 5.

En jouant en solo, il y a trois manières, du plus cher au moins cher :

1. Brancher l’API officielle — l’expérience la plus complète, mais la facture la plus élevée. Claude Opus + appels fréquents d’Agent : normal de dépasser 100 dollars par semaine.
2. Brancher une couche de relais compatible protocole (j’utilise Defapi) — mêmes modèles Claude / GPT / Gemini, facture mensuelle plus basse d’un cran (je n’ai pas calculé au centime près, mais l’idée est que de « 100 dollars par semaine » on passe à « 100 dollars par mois » dans l’ordre de grandeur). Avantage : compatibilité totale au niveau protocole, côté Odysseus vous gardez la configuration, pas besoin de modifier prompt / code d’Agent.
3. Modèles quantifiés en local — dans Cookbook, télécharger un GGUF de Q4_K_M, avec 16G de VRAM vous pouvez faire tourner des modèles autour de 30B : coût API nul, mais l’inférence est plus lente que le cloud, et la qualité sur des tâches complexes est un cran en dessous.

Mon assemblage concret : chat + Deep Research passent par Defapi avec Claude Sonnet 4.5, Agent exécute des appels d’outils via Claude Haiku 4.5 (moins cher), et les tâches simples de classification/résumé passent par une version quantifiée locale de Qwen2.5. Les trois Providers sont facturés séparément, ils ne se gênent pas, et au final le mois reste à deux chiffres en RMB.

Lecture complémentaire / directions avancées

• Écosystème MCP : les MCP intégrés qu’Odysseus enregistre automatiquement incluent playwright (navigateur) / filesystem / shell. Vous pouvez écrire votre propre serveur MCP, l’enregistrer dans mcp_servers/, et le rendre disponible pour l’Agent.
• Système de Skills : routes/skills_routes.py gère des « morceaux de compétences » réutilisables, similaire à la classe Skills d’OpenClaw — vous écrivez une fois, puis n’importe quelle session peut les appeler.
• Tailscale + HTTPS mkcert : la section précédente a déjà montré le flux de base ; en avancé vous pouvez ajouter un renouvellement automatique + challenge DNS-01.
• Combinaison reverse proxy : avec Caddy (HTTPS) + proxy Cloudflare, vous pouvez obtenir un accès Internet public « zéro maintenance ».
• Synchronisation CalDAV : déployez Radicale (un service CalDAV léger) et le calendrier d’Odysseus peut synchroniser bidirectionnellement avec le calendrier du téléphone.
• Email AI : tri automatique en bacs : une fois l’IMAP branché, après un certain temps il classe automatiquement en « urgent / normal / spam », les brouillons sont préparés à l’avance, vous n’avez plus qu’à cliquer pour envoyer.
• Cookbook pour serveurs distants : Cookbook → Settings → Servers permet de configurer une machine distante GPU : exécuter/récupérer les modèles passe par SSH — petit hôte, GPU distant, configuration propre et élégante.
• Deep Research : rapports multi-étapes : modifié à partir du Tongyi DeepResearch d’Alibaba, avec SearXNG pour récupérer plusieurs sources → résumer → synthétiser, idéal pour la veille concurrentielle / recherche sectorielle.
• Routes multi-Providers : dans Odysseus, attribuez des Providers différents à chat/Agent/Research — l’Ollama local gère 80% des conversations du quotidien, les problèmes complexes passent par le cloud : vous obtenez un bon équilibre entre coûts et expérience.

Dépôt GitHub : pewdiepie-archdaemon/odysseus. Les docs sont dans le dossier docs/, la feuille de route est dans ROADMAP.md. Pour contribuer, voir CONTRIBUTING.md.