Installer Odysseus AI sur Linux : guide natif et Docker

Choisir Linux natif ou Docker avant l'installation

Docker est le choix par défaut pour obtenir la pile documentée, des conteneurs reproductibles et une séparation claire du système hôte. Le mode natif convient au développement, à l'observation directe de Python et Uvicorn ou à l'utilisation d'outils du système sans couche réseau de conteneur.

Un modèle local n'impose pas l'installation native. Odysseus peut joindre Ollama, vLLM, SGLang ou un endpoint compatible dans les deux modes. Docker ne garantit pas non plus le GPU : pilotes, runtime et overlay doivent exposer le bon périphérique.

Effectuer les vérifications Linux

Avant le clonage, confirmez la branche, Python, le port, le stockage et l'emplacement de l'inférence. dev est actuellement la branche par défaut pour les changements récents, tandis que main est décrite comme plus contrôlée. Il n'existe pas de Releases, tags ou binaires officiels versionnés ; ce guide n'invente donc ni numéro de version ni installateur.

La voie native exige Python 3.11 ou plus récent. Pour Docker, vérifiez Engine et le plugin Compose. Le port 7000 doit être libre sauf configuration d'APP_PORT. Pour les téléchargements et services de modèles en arrière-plan avec Cookbook natif, la documentation mentionne également tmux.

1. Choisir dev ou main

   dev reçoit les changements les plus récents ; main privilégie une sélection plus contrôlée.

2. Choisir l'emplacement du modèle

   Le modèle peut tourner ici, sur une autre machine ou via une API hébergée.

3. Contrôler le port

   Vérifiez 7000 ou définissez un autre APP_PORT.

4. Garder le premier lancement privé

   Utilisez 127.0.0.1 jusqu'au changement du mot de passe temporaire.

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

Installer Odysseus AI nativement sur Linux

Le mode natif crée un environnement virtuel, installe les dépendances, exécute la configuration du projet puis démarre l'application ASGI avec Uvicorn. Utilisez un compte normal dans un dossier maîtrisé. Évitez sudo pip, qui mélange les paquets du projet avec Python système et complique maintenance et suppression.

La commande initiale écoute uniquement sur loopback. C'est le bon réglage pour le premier test. N'ajoutez systemd ou un superviseur qu'après avoir validé démarrage interactif, connexion et modèle. Le service devra réutiliser le même dossier, l'interpréteur virtuel et les variables vérifiées.

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

Installer Odysseus AI avec Docker Compose

Le démarrage rapide officiel recommande Docker. Copier .env.example reste facultatif mais rend les valeurs de déploiement explicites. Construisez et lancez les conteneurs, attendez les contrôles de santé puis consultez les journaux Odysseus pour le mot de passe temporaire.

Compose lie l'interface à 127.0.0.1 par défaut. Si 7000 est pris, définissez APP_PORT=7001 ou un autre port libre puis recréez le conteneur. APP_BIND=0.0.0.0 ne corrige pas un conflit de port ; adresse et port sont deux réglages distincts.

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

Valider la première connexion avant d'ajouter des modèles

Ouvrez http://localhost:7000 depuis l'hôte Linux. La première configuration crée un compte administrateur et affiche un mot de passe temporaire dans le terminal ou les journaux. Connectez-vous, modifiez-le dans les paramètres et testez une nouvelle session avant l'accès distant.

Ajoutez ensuite un seul endpoint connu et envoyez une courte requête. Si l'interface fonctionne mais pas la réponse, l'installation est probablement correcte. Vérifiez URL, identifiants, nom du modèle, pare-feu et runtime plutôt que de tout réinstaller.

1. Ouvrir la page locale

   Vérifier la page de connexion sur localhost:7000.

2. Lire le mot de passe généré

   Utiliser le terminal ou les journaux, sans deviner.

3. Changer l'identifiant

   Le faire avant LAN, VPN ou proxy.

4. Tester un modèle

   Commencer par un endpoint connu et une requête courte.

Le GPU dépend surtout du runtime du modèle

L'espace Odysseus est relativement léger ; le GPU sert principalement à l'inférence locale. Le mode natif peut joindre Ollama sur l'hôte. Docker peut aussi utiliser un endpoint hôte ou distant sans monter le socket Docker.

Pour NVIDIA ou AMD en conteneur, validez d'abord les pilotes et le passthrough. Les scripts et overlays officiels aident au diagnostic. nvidia-smi dans le conteneur confirme l'accès au matériel, pas la présence des bibliothèques CUDA ou ROCm adaptées à llama.cpp, vLLM ou SGLang.

scripts/check-docker-gpu.sh

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

Connecter Odysseus à Tailscale sur Linux en sécurité

Similarweb a fait remonter connect odysseus to tailscale linux comme requête de soutien à faible difficulté. Elle doit être traitée dans ce guide, car l'accès distant ne commence qu'après une installation locale fonctionnelle ; elle ne justifie pas une page séparée et mince.

Liez volontairement l'application à 0.0.0.0 ou à l'interface appropriée, gardez l'authentification, limitez les appareils avec les règles Tailscale ou le pare-feu et utilisez HTTPS lorsque le navigateur exige une origine sûre. Ne redirigez jamais directement le port de l'application ou du modèle vers Internet.

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

APP_BIND=0.0.0.0
AUTH_ENABLED=true

Mettre à jour sans inventer une version

Au 30 juillet 2026, aucun Release ou tag officiel n'était disponible. dev évolue vite et main est plus contrôlée. Ce guide n'annonce donc ni dernière version, ni taille de fichier, ni installateur binaire ou lien direct permanent.

Avant la mise à jour, notez la branche, sauvegardez données et .env, lisez les changements et mettez à jour la même branche. Ne passez pas de main à dev pendant une maintenance sans rapport. Reconstruisez les conteneurs ou dépendances puis répétez les tests de connexion, modèle et réseau.

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

Tableau de dépannage Linux

Isolez successivement processus, port, connexion, endpoint du modèle et services optionnels. Modifier plusieurs couches simultanément masque la cause.