Installer Odysseus AI sur un serveur VPS Linux
Dans ce guide, nous allons installer Odysseus AI sur un serveur VPS Linux avec Docker Compose, puis le rendre accessible proprement derrière un reverse proxy HTTPS. L’objectif est d’obtenir un workspace IA privé, auto-hébergé, capable de centraliser chat, agents, documents, mémoire, recherche web, notes, tâches, calendrier, emails et outils locaux.
Odysseus est un projet open source qui se présente comme un workspace IA self-hosted, local-first et privacy-first. Il peut discuter avec des modèles locaux ou des APIs compatibles, utiliser des outils d’agent, s’appuyer sur ChromaDB pour la mémoire, lancer SearXNG pour la recherche web, et se connecter à Ollama, vLLM, llama.cpp, OpenRouter, OpenAI ou d’autres endpoints. Si vous avez suivi notre tutoriel sur Hermes Agent, voyez Odysseus comme une approche plus orientée interface web et workspace complet, alors que Hermes vise plutôt l’agent autonome joignable par terminal ou messagerie.
Odysseus est encore jeune. Le dépôt officiel indique que la branche dev contient les changements les plus récents mais peut être instable, tandis que main est la branche plus stable. Pour un VPS que vous voulez garder propre, nous allons donc installer main par défaut.
1. Ce que vous allez obtenir
À la fin de ce tutoriel, vous aurez :
- Une instance Odysseus lancée avec Docker Compose.
- Une interface web protégée par authentification.
- ChromaDB, SearXNG et ntfy lancés avec la stack officielle.
- Un accès HTTPS via NGINX, sans exposer directement les ports internes.
- Une base pour connecter Ollama, une API OpenAI-compatible ou un serveur de modèles distant.
- Des commandes de sauvegarde, mise à jour, dépannage et durcissement.
Odysseus écoute par défaut sur le port applicatif 7000. La stack Docker expose aussi des services internes comme SearXNG, ChromaDB et ntfy. Le point important est de ne pas ouvrir tous ces ports au public : l’interface Odysseus doit être le seul point d’entrée utilisateur, idéalement derrière HTTPS.
2. Prérequis recommandés
Avant de commencer, prévoyez :
- Un VPS Linux avec accès SSH et droits sudo.
- Ubuntu 22.04, Ubuntu 24.04 ou Debian 12 pour suivre les commandes telles quelles.
- Au moins 2 Go de RAM pour tester l’interface avec des modèles via API.
- Plutôt 4 Go à 8 Go de RAM si vous voulez aussi lancer des composants de recherche, documents et quelques traitements locaux.
- Plus de RAM et éventuellement un GPU si vous voulez servir de vrais modèles locaux sur le même VPS.
- Un nom de domaine ou sous-domaine, par exemple
odysseus.example.com, si vous voulez un accès HTTPS propre.
Si vous utilisez un petit VPS sans GPU, ce n’est pas bloquant. Odysseus peut très bien servir d’interface privée connectée à un fournisseur externe ou à un serveur de modèles distant. Le GPU devient surtout utile si vous voulez télécharger et servir des modèles localement via Cookbook, llama.cpp, vLLM ou un runtime équivalent.
Mettez d’abord votre système à jour :
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git ca-certificates gnupg openssl ufw
3. Installer Docker sur le VPS
Odysseus recommande Docker pour l’installation serveur. Si Docker est déjà utilisé en production sur votre VPS, vérifiez d’abord l’impact avant de remplacer des paquets existants. Sur une machine neuve, utilisez la séquence suivante.
sudo apt remove -y $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc 2>/dev/null | cut -f1)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl enable --now docker
Vérifiez que Docker et Docker Compose sont disponibles :
docker --version
docker compose version
Si vous voulez plus de détails sur Docker, nous avons un guide dédié : Installer Docker sur Linux, guide pratique pour bien démarrer.
4. Télécharger les fichiers de déploiement Odysseus
L’installation officielle d’Odysseus repose sur le dépôt Git du projet. Ce dépôt contient le docker-compose.yml complet, la configuration SearXNG, les scripts GPU et les fichiers nécessaires pour lancer les services associés à Odysseus.
Installez ces fichiers dans /opt/odysseus, puis redonnez la propriété du dossier à votre utilisateur courant pour éviter de tout gérer en root.
sudo apt update
sudo apt install -y git openssl
cd /opt
sudo git clone --branch main https://github.com/pewdiepie-archdaemon/odysseus.git
sudo chown -R "$USER:$USER" /opt/odysseus
cd /opt/odysseus
Pour ce tutoriel VPS, restez sur main. Le tag dev existe aussi, mais il suit la branche de développement et peut changer plus vite.
5. Préparer le fichier .env
Copiez le fichier d’exemple :
cp .env.example .env
Ajoutez ensuite une configuration explicite pour un premier déploiement local derrière reverse proxy. Le port Odysseus restera lié à 127.0.0.1, donc non exposé directement sur Internet.
ADMIN_PASSWORD=$(openssl rand -hex 24)
SECRET_KEY=$(openssl rand -hex 32)
cat <<EOF >> .env
APP_BIND=127.0.0.1
APP_PORT=7000
AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=false
ODYSSEUS_ADMIN_USER=admin
ODYSSEUS_ADMIN_PASSWORD=$ADMIN_PASSWORD
SECRET_KEY=$SECRET_KEY
ALLOWED_ORIGINS=http://localhost:7000,http://127.0.0.1:7000
FASTEMBED_CACHE_PATH=/app/data/fastembed_cache
EOF
printf 'Mot de passe admin initial : %s\n' "$ADMIN_PASSWORD"
Conservez le mot de passe affiché dans un gestionnaire de mots de passe. Vous pourrez le changer ensuite dans l’interface Odysseus.
Points importants :
AUTH_ENABLED=truegarde la page protégée par login.LOCALHOST_BYPASS=falseévite un contournement prévu uniquement pour le développement local.APP_BIND=127.0.0.1empêche l’exposition directe du port applicatif au réseau public.SECURE_COOKIES=falseest temporaire tant que vous n’avez pas encore activé HTTPS.FASTEMBED_CACHE_PATH=/app/data/fastembed_cachegarde le cache FastEmbed dans le volume persistantdata/. Sans ce chemin explicite, Odysseus peut afficher des erreursNo embedding lanes availableau démarrage de la mémoire, du RAG et de l’index d’outils.
6. Lancer Odysseus avec Docker Compose
Lancez la stack officielle. Au premier démarrage, Docker construit l’image Odysseus depuis les sources, puis démarre aussi ChromaDB, SearXNG et ntfy.
docker compose up -d --build
Cette première exécution peut prendre plusieurs minutes, surtout sur un petit VPS. Les démarrages suivants seront plus rapides, car Docker réutilise les couches déjà construites.
Vérifiez l’état des conteneurs :
docker compose ps
Consultez les logs de l’application :
docker compose logs --tail=120 odysseus
Si vous n’avez pas défini ODYSSEUS_ADMIN_PASSWORD, Odysseus génère un mot de passe temporaire au premier lancement. Vous pouvez le retrouver avec :
docker compose logs odysseus | grep -Ei 'password|admin'
À ce stade, l’interface doit répondre localement depuis le VPS :
curl -I http://127.0.0.1:7000
Vous pouvez aussi tester un tunnel SSH depuis votre ordinateur :
ssh -L 7000:127.0.0.1:7000 utilisateur@adresse-du-vps
Puis ouvrez http://localhost:7000 dans votre navigateur local. Cette méthode est pratique pour un test rapide sans exposer l’application.
Une fois le service démarré, la page de connexion s’affiche avec l’utilisateur admin créé au premier démarrage.
7. Mettre Odysseus derrière NGINX et HTTPS
Pour un accès web propre, utilisez un sous-domaine et un reverse proxy. Dans les exemples, remplacez odysseus.example.com par votre vrai domaine. Avant de lancer Certbot, assurez-vous que le DNS du sous-domaine pointe déjà vers l’adresse IP du VPS et que le port 80 est accessible depuis Internet.
Installez NGINX et Certbot :
sudo apt install -y nginx certbot python3-certbot-nginx
Créez la configuration NGINX :
sudo tee /etc/nginx/sites-available/odysseus.conf > /dev/null <<'EOF'
server {
listen 80;
server_name odysseus.example.com;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:7000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600;
proxy_send_timeout 3600;
}
}
EOF
Activez le site, vérifiez la syntaxe, puis rechargez NGINX :
sudo ln -s /etc/nginx/sites-available/odysseus.conf /etc/nginx/sites-enabled/odysseus.conf
sudo nginx -t
sudo systemctl reload nginx
Générez le certificat HTTPS :
sudo certbot --nginx -d odysseus.example.com
Une fois HTTPS actif, mettez à jour .env pour activer les cookies sécurisés et autoriser l’origine publique :
cd /opt/odysseus
sed -i '/^SECURE_COOKIES=/d;/^ALLOWED_ORIGINS=/d' .env
cat <<'EOF' >> .env
SECURE_COOKIES=true
ALLOWED_ORIGINS=https://odysseus.example.com,http://localhost:7000,http://127.0.0.1:7000
EOF
docker compose up -d
Ouvrez ensuite https://odysseus.example.com et connectez-vous avec l’utilisateur admin et le mot de passe généré plus haut.
8. Configurer le pare-feu du VPS
Avant d’activer ou de modifier UFW, vérifiez toujours son état pour éviter de vous couper l’accès SSH :
sudo ufw status
Autorisez SSH pour garder votre accès d’administration, puis ouvrez le web :
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
La règle OpenSSH sert uniquement à conserver votre accès SSH d’administration ou à maintenir le tunnel SSH utilisé pour les tests dans ce tutoriel, et n’est pas requise pour le fonctionnement d’Odysseus lui-même.
Si UFW n’est pas encore actif, activez-le seulement après avoir bien ajouté la règle SSH :
sudo ufw enable
sudo ufw status verbose
Si votre système n’utilise pas UFW, vous pouvez configurer l’équivalent minimal avec iptables. Cette règle SSH sert également à conserver votre accès d’administration ou le tunnel de ce tutoriel (notez que le port par défaut 22 doit être adapté si votre service SSH écoute sur un autre port) :
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
Ne publiez pas directement les ports internes 7000, 8080, 8091, 8100, 11434 ou 8000-8020 sur Internet. Gardez-les en localhost, derrière Docker, un VPN, Tailscale, ou un reverse proxy contrôlé.
9. Premier parcours dans l’interface Odysseus
Après connexion, vous arrivez sur l’écran de chat. À ce stade, l’installation est bien démarrée, mais Odysseus ne pourra pas encore répondre tant qu’aucun fournisseur de modèle n’est configuré.
Prenez le temps de faire trois réglages avant de lancer un agent :
- Changez le mot de passe admin si vous avez utilisé une valeur temporaire.
- Vérifiez que l’inscription libre est désactivée si l’instance n’est pas destinée à plusieurs utilisateurs.
- Ajoutez votre premier fournisseur de modèle dans les paramètres.
L’écran d’accueil peut proposer de taper /setup, mais selon la version installée la commande seule peut répondre Unknown subcommand. Le raccourci utile est donc de commencer par l’aide ou par le gestionnaire d’endpoints :
/setup --help
/setup endpoint
Vous pouvez aussi passer directement par Settings > Add Models. C’est la méthode la plus claire pour un premier déploiement, car elle sépare les modèles locaux, les APIs externes et les tests de connexion.
Odysseus peut fonctionner de plusieurs façons :
- Avec une API compatible OpenAI, OpenRouter, DeepSeek, Anthropic, Groq, Gemini ou équivalent pour démarrer rapidement.
- Avec Ollama sur le même VPS ou sur une autre machine privée.
- Avec un endpoint vLLM, llama.cpp ou un autre serveur OpenAI-compatible.
- Avec Cookbook pour détecter le matériel, télécharger des modèles et préparer un runtime adapté.
Si vous configurez un serveur de modèle local depuis Docker, gardez en tête que localhost vu depuis le conteneur n’est pas forcément le VPS hôte. Pour Ollama installé sur le même VPS, utilisez plutôt http://host.docker.internal:11434/v1, comme détaillé dans la section suivante.
Les autres modules s’ouvrent déjà, même sur une instance fraîche. La Library sert à retrouver les documents, recherches et conversations archivées.
La zone Brain regroupe la mémoire longue durée et les skills. Elle devient réellement utile après configuration d’un modèle et d’un backend d’embeddings fonctionnel.
Deep Research prépare des recherches web multi-étapes, avec choix du moteur de recherche, du nombre de rounds, de l’endpoint et du modèle.
Odysseus propose aussi un panneau Compare pour envoyer le même prompt à plusieurs modèles et comparer les réponses, y compris en mode blind test quand plusieurs modèles sont disponibles.
La partie Calendar permet de gérer un calendrier local-first, avec vue semaine, mois, année ou agenda. Les synchronisations CalDAV se configurent ensuite dans les paramètres d’intégration.
Le module Tasks expose les tâches planifiées et les automatisations internes : tri des sessions, emails, mémoire, documents, recherches ou skills. C’est aussi là que l’on voit les jobs actifs ou en pause.
Le module Email fait aussi partie des fonctionnalités phares, mais il nécessite une configuration IMAP/SMTP dans Settings > Integrations avant de devenir utile. Sur une instance fraîche, il est normal qu’il n’affiche aucun courrier tant qu’aucun compte n’est connecté.
Pour un petit VPS, commencez avec un fournisseur externe ou un serveur de modèles distant. Pour une machine plus musclée hors offre VPS BoxToPlay, vous pourrez ensuite tester le téléchargement et le service de modèles locaux.
10. Connecter Ollama à Odysseus
Si Ollama tourne sur le même VPS que Docker, Odysseus doit pouvoir l’atteindre depuis le conteneur. Le dépôt recommande l’URL suivante côté Odysseus :
http://host.docker.internal:11434/v1
Ollama doit écouter ailleurs que sur son seul loopback interne. Sur un serveur systemd, vous pouvez créer un override :
sudo mkdir -p /etc/systemd/system/ollama.service.d
sudo tee /etc/systemd/system/ollama.service.d/override.conf > /dev/null <<'EOF'
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
EOF
sudo systemctl daemon-reload
sudo systemctl restart ollama
N’ouvrez pas le port 11434 dans le pare-feu public. L’objectif est seulement que le conteneur Odysseus puisse joindre Ollama via le réseau local Docker/host.
Vous pouvez aussi préconfigurer l’URL dans .env :
cd /opt/odysseus
sed -i '/^OLLAMA_BASE_URL=/d' .env
cat <<'EOF' >> .env
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
EOF
docker compose up -d
Ensuite, dans Odysseus, ajoutez ou vérifiez le provider correspondant depuis les paramètres de modèles.
11. Activer les options GPU si votre VPS le permet
Sur un VPS BoxToPlay, vous pouvez ignorer cette partie : nos offres VPS actuelles ne sont pas vendues avec GPU. Les options ci-dessous ne fonctionneront donc pas sur un VPS BoxToPlay standard. Elles concernent uniquement un serveur Linux qui dispose réellement d’un GPU NVIDIA ou AMD, avec le passthrough Docker compatible.
Sur un serveur Linux sans GPU, Cookbook peut quand même détecter la RAM, les cœurs CPU et proposer des modèles llama.cpp compatibles ou marginaux. C’est pratique pour estimer rapidement ce qui peut tourner localement avant de télécharger quoi que ce soit.
Pour NVIDIA, commencez par un diagnostic sans modification :
cd /opt/odysseus
scripts/check-docker-gpu.sh
Pour afficher les commandes d’installation nécessaires sans les exécuter :
scripts/check-docker-gpu.sh --print-install-commands
Pour installer le runtime NVIDIA et activer l’overlay après validation du passthrough :
sudo scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay
docker compose up -d --build
Pour AMD/ROCm, lancez le diagnostic :
cd /opt/odysseus
scripts/check-docker-amd-gpu.sh
Puis renseignez l’overlay et le GID du groupe render dans .env si le diagnostic vous le demande :
RENDER_GID=$(getent group render | cut -d: -f3)
sed -i '/^COMPOSE_FILE=/d;/^RENDER_GID=/d' .env
cat <<EOF >> .env
COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
RENDER_GID=$RENDER_GID
EOF
docker compose up -d --build
Un point important : voir le GPU dans le conteneur ne garantit pas que llama.cpp ou vLLM utilisera déjà CUDA ou ROCm. Le passthrough Docker et les dépendances du moteur de modèles sont deux sujets distincts.
12. Sauvegarder Odysseus proprement
Les données importantes sont dans le dossier data/, dans .env, et selon votre usage dans logs/. Avant une mise à jour ou une grosse modification, créez une archive.
cd /opt/odysseus
tar --exclude='data/huggingface' --exclude='data/local' -czf "$HOME/odysseus-backup-$(date +%F).tar.gz" .env data logs
Les dossiers data/huggingface et data/local peuvent devenir très volumineux si vous téléchargez des modèles ou installez des moteurs locaux. Sauvegardez-les séparément si vous voulez pouvoir restaurer aussi les modèles et dépendances lourdes.
Pour une sauvegarde distante, envoyez l’archive vers un autre serveur :
scp "$HOME/odysseus-backup-$(date +%F).tar.gz" [email protected]:/home/utilisateur/backups/
Ne partagez jamais publiquement .env, data/, les logs, les exports, les uploads ou les captures contenant des clés API.
13. Mettre à jour Odysseus
Avant de mettre à jour, faites une sauvegarde. Avec l’installation officielle depuis le dépôt Git, récupérez les derniers fichiers puis reconstruisez la stack :
cd /opt/odysseus
git checkout main
git pull --ff-only
docker compose up -d --build
docker compose logs --tail=120 odysseus
Vérifiez ensuite l’interface et les providers configurés. Si vous utilisez dev, attendez-vous à plus de changements et gardez une archive récente avant chaque mise à jour.
14. Dépannage courant
Si l’interface ne répond pas, vérifiez d’abord les conteneurs :
cd /opt/odysseus
docker compose ps
docker compose logs --tail=120 odysseus
Si le port 7000 est déjà pris, choisissez un autre port local :
cd /opt/odysseus
sed -i '/^APP_PORT=/d' .env
cat <<'EOF' >> .env
APP_PORT=7001
EOF
docker compose up -d
Pensez alors à adapter le proxy_pass NGINX vers http://127.0.0.1:7001.
Si SearXNG bloque le démarrage ou reste en erreur :
docker compose logs --tail=120 searxng
docker compose restart searxng odysseus
Si ChromaDB semble indisponible :
docker compose logs --tail=120 chromadb
docker compose restart chromadb odysseus
Si les logs Odysseus affichent FastEmbed init failed, No such file or directory: '' ou No embedding lanes available, vérifiez que le fichier .env contient bien le chemin de cache FastEmbed ajouté dans ce guide :
cd /opt/odysseus
grep '^FASTEMBED_CACHE_PATH=' .env
La valeur attendue est :
FASTEMBED_CACHE_PATH=/app/data/fastembed_cache
Relancez ensuite le conteneur :
docker compose up -d odysseus
docker compose logs --tail=120 odysseus
Au premier démarrage, FastEmbed peut télécharger un petit modèle ONNX depuis Hugging Face. Un avertissement sur les requêtes Hugging Face non authentifiées est normal si vous n’avez pas défini de HF_TOKEN.
Si vous avez perdu le mot de passe admin initial, le plus propre est de définir un nouveau ODYSSEUS_ADMIN_PASSWORD avant le premier vrai usage. Si l’instance contient déjà des utilisateurs et des données, traitez plutôt le sujet depuis l’interface d’administration ou la documentation du projet pour éviter d’écraser votre configuration.
Si vous perdez définitivement le mot de passe administrateur après la première configuration, vous pouvez réinitialiser l’authentification en arrêtant le service et en supprimant le fichier data/auth.json (ce qui réinitialisera le processus d’initialisation au prochain démarrage) :
cd /opt/odysseus
docker compose down
mv data/auth.json data/auth.json.bak
docker compose up -d
15. Bonnes pratiques de sécurité
Odysseus peut manipuler des outils puissants : shell, fichiers, documents, emails, calendrier, modèles, webhooks, tokens et MCP. Traitez-le comme une console d’administration.
- Gardez
AUTH_ENABLED=truedès que l’instance est accessible sur le réseau. - Gardez
LOCALHOST_BYPASS=falsehors développement local. - Activez
SECURE_COOKIES=truedès que l’accès passe par HTTPS. - N’exposez pas directement ChromaDB, SearXNG, ntfy, Ollama, vLLM, llama.cpp ou vos APIs de modèles.
- Limitez les comptes admin et vérifiez les privilèges des utilisateurs non admin.
- Activez la 2FA si votre version et votre configuration le permettent.
- Ne collez pas de clés API dans des captures, logs ou discussions partagées.
- Sauvegardez régulièrement
.envetdata/, puis stockez les archives hors du VPS.
Odysseus est conçu avec des privilèges locaux avancés (privileged local capabilities), ce qui lui permet d’interagir directement avec le système de fichiers et d’exécuter des commandes via son terminal intégré. Traitez cette interface comme une véritable console d’administration et n’accordez pas d’accès à des utilisateurs non approuvés.
Une fois cette base en place, Odysseus devient un workspace IA privé que vous pouvez faire évoluer progressivement : d’abord une interface connectée à un provider, puis un agent avec outils, puis éventuellement un vrai environnement local avec modèles, mémoire, recherche et automatisations.
Pour héberger ce type de workspace sur une machine stable, un serveur VPS reste une bonne base : accès root, services persistants, reverse proxy, sauvegardes et montée en puissance progressive. Chez BoxToPlay, vous pouvez lancer votre serveur VPS gratuitement et construire votre propre environnement IA self-hosted à votre rythme.