Guides

Installer Hermes Agent sur Mac avec Docker

18 mai 2026

Ce guide explique comment exécuter Hermes Agent sur Mac avec Docker Desktop. L’idée est simple: Docker fournit l’environnement d’exécution, tandis que les données importantes restent dans un dossier persistant sur votre Mac.

Hermes Agent peut utiliser des clés API, mais ce guide privilégie le provider OpenAI Codex avec ChatGPT OAuth. L’ordre recommandé est le suivant: installer Docker Desktop, lancer setup, configurer le provider, démarrer Hermes Agent, puis vérifier le dashboard local sur localhost:9119.

Résumé rapide

Installez et lancez Docker Desktop pour Mac.
Utilisez l’image officielle nousresearch/hermes-agent.
Montez ~/.hermes vers /opt/data pour conserver réglages, OAuth, sessions, skills et logs.
Exécutez d’abord setup, puis choisissez OpenAI Codex via hermes model.
Avec le dashboard activé, http://localhost:9119 doit être accessible dans le navigateur.

Prérequis

Élément	Rôle
Mac	Apple Silicon ou Intel; choisissez le bon installateur Docker Desktop.
Docker Desktop	Nécessaire pour lancer le conteneur Hermes Agent.
Terminal	Sert à exécuter Docker, setup, OAuth, logs et vérifications.
Compte ChatGPT	Utilisé pour connecter OpenAI Codex avec ChatGPT OAuth.
Connexion Internet	Nécessaire pour télécharger l’image et terminer l’authentification.

Schéma montrant un Mac, Docker Desktop, un conteneur Hermes Agent et un volume persistant — Docker exécute Hermes Agent; `~/.hermes` conserve les données côté Mac.

Ce que Docker apporte

Hermes Agent est un runtime d’AI agent publié par NousResearch. La documentation officielle décrit plusieurs modes d’utilisation, dont l’installation locale, l’exécution Docker et l’usage comme Docker terminal backend. Ce guide se concentre sur l’exécution de Hermes Agent lui-même dans un conteneur Docker.

L’avantage est de garder l’environnement plus isolé. Vous n’avez pas besoin d’installer Python, Node.js, les dépendances de browser automation et les outils associés directement dans macOS. En contrepartie, Docker Desktop doit être lancé, et l’accès aux fichiers passe par les dossiers que vous montez explicitement.

Hermes Agent utilise /opt/data comme emplacement de données dans le conteneur. C’est pourquoi ce guide relie ~/.hermes sur le Mac à /opt/data.

Installer Docker Desktop

Téléchargez Docker Desktop depuis la documentation officielle Docker pour Mac. Prenez la version Apple Silicon pour les Mac M1 ou plus récents, et la version Intel pour les anciens modèles.

Le flux d’installation est simple:

Téléchargez Docker Desktop depuis la page officielle pour Mac.
Ouvrez Docker.dmg et déplacez Docker dans le dossier Applications.
Lancez Docker Desktop depuis Applications.
Vérifiez les demandes de permission et l’écran de conditions initiales.
Attendez que l’icône Docker soit stable dans la barre de menus.

Vérifiez ensuite le CLI:

docker --version

Si la commande est introuvable, Docker Desktop n’est peut-être pas lancé ou l’intégration CLI n’est pas encore prête.

Flux montrant l'installation de Docker Desktop puis la vérification avec docker version — Vérifiez Docker Desktop avant de lancer l'image Hermes Agent.

Pourquoi monter `~/.hermes`

Le volume mount est essentiel. Sans lui, la configuration et les informations d’authentification peuvent disparaître lorsque le conteneur est supprimé.

Utilisez le même mount pour toutes les commandes Hermes:

-v ~/.hermes:/opt/data

Schéma montrant le dossier ~/.hermes du Mac relié à /opt/data dans le conteneur Docker — Le mount `~/.hermes:/opt/data` conserve réglages, sessions, OAuth, skills et logs.

Premier lancement: setup wizard

Créez le dossier de données et lancez le setup officiel:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Le conteneur temporaire disparaît à la fin grâce à --rm, mais les fichiers créés dans /opt/data restent dans ~/.hermes.

Selon la version, le setup wizard peut créer ou mettre à jour ces éléments:

Emplacement	Usage
`~/.hermes/.env`	Stocke les secrets des providers à clé API si vous en utilisez.
`~/.hermes/config.yaml`	Stocke les réglages de modèle, backend, gateway et outils.
`~/.hermes/SOUL.md`	Décrit le comportement de base de l’agent.
`~/.hermes/sessions/`	Garde l’historique des sessions.
`~/.hermes/memories/`	Peut contenir la mémoire longue durée.
`~/.hermes/skills/`	Contient les skills installés.
`~/.hermes/logs/`	Contient les logs d’exécution.

Les prompts exacts peuvent changer selon la version de Hermes Agent, mais cette règle pratique fonctionne bien:

Prompt de setup	Choix pratique
Model provider	Choisir `OpenAI Codex` ou une option `Codex`. Si elle n’apparaît pas, terminer le setup puis lancer `hermes model`.
Authentication method	Les providers à clé API stockent leurs valeurs dans `.env`. ChatGPT OAuth stocke les tokens dans un magasin d’authentification comme `auth.json`.
Chat system ou gateway integration	Telegram, Discord ou Slack peuvent être configurés plus tard si vous ne les utilisez pas tout de suite. Pour un gateway permanent, les régler ici peut être pratique.
Defaults incertains	Garder les valeurs par défaut, puis ajuster `config.yaml` après confirmation du fonctionnement.

En pratique, laissez setup créer les fichiers de base, puis rouvrez le choix de modèle avec hermes model si la sélection du provider n’était pas claire.

Vérifiez ensuite le dossier:

ls -la ~/.hermes

Vérifiez aussi que config.yaml existe. Ne publiez pas tout le fichier; regarder le début localement suffit.

sed -n '1,80p' ~/.hermes/config.yaml

Évitez d’afficher ou de partager .env, car il peut contenir des secrets. Pour vérifier seulement son existence:

ls -la ~/.hermes/.env

Si setup se termine mais que ~/.hermes/config.yaml manque ou que le dossier est vide, vérifiez d’abord le volume mount. La commande doit contenir -v ~/.hermes:/opt/data.

Configurer ChatGPT OAuth

Si le provider n’a pas été configuré pendant le setup, ouvrez le sélecteur de modèle:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent model

Choisissez OpenAI Codex ou l’entrée Codex la plus proche. Si Hermes Agent affiche une URL ou un device code, ouvrez-le dans le navigateur du Mac et connectez-vous avec ChatGPT.

Certaines versions permettent aussi cette commande:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth add openai-codex --type oauth

Le token OAuth ne doit pas rester uniquement dans un conteneur jetable. Il est conservé dans le dossier monté ~/.hermes, par exemple dans un magasin comme auth.json. Vous pouvez ainsi recréer le conteneur sans refaire toute la configuration provider.

Schéma montrant une connexion ChatGPT OAuth dans le navigateur reliée au conteneur Docker Hermes Agent — ChatGPT OAuth connecte OpenAI Codex sans coller de clé OpenAI API dans la commande.

Lancer Hermes Agent

Une fois setup et provider configurés, lancez Hermes Agent en mode interactif:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent

Si la session interactive s’ouvre, l’installation de base fonctionne. Continuez à utiliser le même volume mount pour chaque commande.

Les options importantes signifient:

Option	Signification
`docker run`	Démarre un nouveau conteneur.
`-it`	Ouvre une session terminal interactive.
`--rm`	Supprime le conteneur temporaire après sa fermeture.
`-v ~/.hermes:/opt/data`	Relie le dossier Mac `~/.hermes` à `/opt/data` dans le conteneur.
`nousresearch/hermes-agent`	Utilise l’image Docker officielle de Hermes Agent.

Vérifier le dashboard sur `localhost:9119`

Après le setup, la configuration provider et le lancement interactif, vérifiez l’image et la version:

docker pull nousresearch/hermes-agent:latest
docker run -it --rm nousresearch/hermes-agent:latest version

Pour vérifier l’état OAuth, utilisez le même dossier de données:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth list

Pour lancer gateway et dashboard en arrière-plan, exposez les deux ports:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Ouvrez ensuite http://localhost:9119 dans le navigateur. http://127.0.0.1:9119 doit également fonctionner. Le dashboard est une interface locale pour réglages, sessions, logs et skills.

En cas de problème:

curl -I http://127.0.0.1:9119

Les logs donnent les détails d’exécution:

docker logs --tail 50 hermes

Les lignes du dashboard peuvent être préfixées par [dashboard].

Pour arrêter et supprimer le conteneur en arrière-plan:

docker stop hermes
docker rm hermes

Problèmes fréquents

Symptôme	À vérifier
`Cannot connect to the Docker daemon`	Docker Desktop n’est pas lancé.
`docker: command not found`	Le CLI Docker n’est pas disponible dans Terminal.
L’URL OAuth ne s’ouvre pas	Copiez l’URL ou le device code dans le navigateur du Mac.
Le provider OpenAI Codex n’apparaît pas	Tirez la dernière image Hermes Agent et vérifiez à nouveau le menu `hermes model`.
Les réglages disparaissent	Le mount `-v ~/.hermes:/opt/data` manque ou change.
Permission error	Vérifiez que l’utilisateur macOS actuel peut écrire dans `~/.hermes`.
Le dashboard ne s’ouvre pas	Vérifiez `-p 9119:9119`, `-e HERMES_DASHBOARD=1` et les logs `[dashboard]`.
Conflit de port	Un autre processus utilise déjà `8642` ou `9119`.

Sur les Mac Apple Silicon, Docker Desktop gère généralement les différences d’architecture si vous ne forcez pas une image Intel-only. Commencez par l’image officielle latest et une version récente de Docker Desktop.

Flux montrant les contrôles Docker, OAuth, volume, logs et dashboard — Vérifiez Docker, OAuth, le volume, les logs puis le port du dashboard.

Mettre à jour ou supprimer

Pour mettre à jour, récupérez la dernière image et recréez le conteneur en gardant ~/.hermes:

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Pour retirer conteneur et image:

docker rm -f hermes
docker rmi nousresearch/hermes-agent:latest

Supprimez ~/.hermes uniquement si vous voulez aussi effacer réglages, tokens OAuth, sessions, skills et logs.

rm -rf ~/.hermes

À retenir

La séquence fiable est: Docker Desktop, setup, OpenAI Codex avec ChatGPT OAuth, mount ~/.hermes:/opt/data, puis vérification de http://localhost:9119 en mode gateway.