10 min de lecture 11 juin 2026

Installer Odysseus AI sur macOS : Apple Silicon, Docker et Ollama

Guide pratique pour Mac : chemin natif Apple Silicon, cas où Docker reste utile, connexion Ollama et contrôles avant toute exposition réseau.

Odysseus AI Wiki

Fan-made editorial notes based on public Odysseus AI documentation, GitHub setup discussions, and local self-hosting patterns.

Installer Odysseus AI sur macOS : Apple Silicon, Docker et Ollama

Réponse courte: Sur un Mac Apple Silicon, commencez par le chemin natif si vous voulez une accélération locale et moins de confusion réseau. Docker reste utile pour un test isolé, mais il n’est pas toujours le meilleur choix si Ollama tourne déjà sur le Mac.

Les utilisateurs Mac viennent souvent à Odysseus AI avec deux objectifs : lancer rapidement l’application, ou relier un workspace local à Ollama et aux modèles déjà présents sur un Mac M-series. Ce guide sépare ces objectifs avant de modifier ports, variables ou réglages de modèles.

Choisissez le chemin Mac selon ce que vous voulez vérifier

Si vous voulez seulement vérifier que le workspace Odysseus AI démarre, Docker est un chemin contrôlé qui isole les dépendances. Si votre objectif est d’utiliser des runtimes de modèles locaux sur un Mac Apple Silicon, le chemin natif est souvent le meilleur premier test.

Il ne s’agit pas de déclarer un chemin supérieur dans tous les cas. Docker répond à la question du lancement reproductible en conteneur. Le chemin natif répond à la question de l’intégration avec les modèles, fichiers et outils locaux du Mac.

Point de départ natif macOS

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

Chemin natif Apple Silicon : vérifiez l’environnement avant les modèles

Le chemin natif macOS compte parce que les utilisateurs Apple Silicon veulent souvent garder Ollama, les modèles locaux et les fichiers près du workspace. Vérifiez d’abord le dépôt, le bit d’exécution du script, les dépendances Python et le port local.

Un premier lancement propre doit afficher une interface locale accessible et demander la configuration ou la connexion. Les mots de passe générés et secrets locaux doivent rester des détails opérationnels temporaires.

1. Clonez le dépôt officiel

Utilisez le dépôt officiel comme source de vérité pour les scripts, issues et changements du README.

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

2. Lancez le script macOS et lisez la première erreur

La première erreur indique souvent permissions, Python, dépendances ou conflit de port.

chmod +x ./start-macos.sh
./start-macos.sh

3. Ouvrez l’UI locale et terminez la connexion

Si l’application démarre sur le port local documenté, ouvrez cette URL et remplacez toute clé temporaire.

http://127.0.0.1:7860

4. Configurez les modèles seulement ensuite

Une fois le workspace sain, connectez Ollama ou un autre fournisseur dans Settings.

http://127.0.0.1:11434/v1

Docker sur macOS : isolation utile, compromis réel

Docker reste pertinent pour un test jetable, une frontière de dépendances claire ou une exécution proche d’un serveur.

L’erreur fréquente consiste à mélanger les modèles réseau : localhost dans le conteneur désigne le conteneur, localhost sur l’hôte désigne le Mac.

Choix	Meilleur usage	À surveiller
Apple Silicon natif	Modèles locaux, moins de couches réseau et appairage Ollama plus simple	Gardez Python et les dépendances locales propres.
Docker sur macOS	Tests propres, dépendances isolées et validation proche du déploiement	Utilisez host.docker.internal pour joindre Ollama sur l’hôte.
Hôte Linux distant	Workspace permanent, GPU serveur ou accès d’équipe	N’exposez rien sans auth, firewall et proxy maîtrisés.

Ollama, accélération Metal et choix de l’endpoint

Ollama est normalement un serveur de modèles séparé. Sur Mac, cette séparation permet de garder Ollama dans son environnement local et de pointer Odysseus AI vers l’API compatible.

Utilisez 127.0.0.1 si Odysseus AI et Ollama tournent nativement sur le même Mac. Utilisez host.docker.internal si Odysseus AI est dans Docker et Ollama sur l’hôte.

Endpoint Odysseus AI natif vers Ollama local

http://127.0.0.1:11434/v1

Dépannage d’Odysseus AI sur macOS

Progressez du démarrage vers le réseau, puis vers le modèle. Si l’UI n’est pas saine, les erreurs de modèle sont souvent secondaires.

Symptôme	Cause probable	Correctif
Le script macOS ne démarre pas	Permission d’exécution, politique shell ou dépendance manquante.	Lancez chmod +x depuis la racine du dépôt et lisez la première erreur.
Le navigateur n’ouvre pas l’UI	L’app n’écoute pas encore ou le port est pris.	Vérifiez la sortie terminal et libérez le port.
Ollama marche dans Terminal mais pas dans Odysseus	L’endpoint ne correspond pas au mode natif ou Docker.	127.0.0.1 en natif, host.docker.internal depuis Docker.
Le premier prompt est lent	Le modèle charge ou dépasse la mémoire disponible.	Testez un petit modèle avant agents et documents.
Accès depuis un autre appareil	La liaison locale protège le service.	Planifiez auth, firewall et proxy avant d’ouvrir le réseau.

Checklist finale pour une installation Mac

Une installation Mac est prête quand le workspace, l’endpoint modèle et la frontière réseau sont clairs.

L’UI s’ouvre localement après un démarrage propre.
Le mode natif, Docker ou distant est identifié.
Ollama répond séparément avant Odysseus AI.
Un petit modèle fonctionne avant agents ou documents.
Le workspace n’est pas exposé sans règles réseau.

Gardez le premier essai local

Le choix sûr est de garder Odysseus AI et Ollama sur localhost pendant l’apprentissage du flux.