Comment Configurer Hermes Agent avec Docker

Ça fait quelques semaines que je bidouille l’agent Hermes de NousResearch. Pour ceux qui ont déjà joué avec des agents IA autonomes, vous connaissez le frisson : c’est ultra puissant, mais quand l’agent commence à écrire des scripts Python et à vouloir exécuter des commandes bash en local, on a vite de légères sueurs froides (surtout quand on l’entend taper frénétiquement sur le clavier virtuel sans trop savoir ce qu’il fabrique).

Pour dormir sur mes deux oreilles, j’ai passé pas mal de temps à isoler tout ça avec Docker. Il y a principalement deux manières de s’y prendre selon votre cas d’usage : soit vous faites tourner l’intégralité de l’agent dans un conteneur (top pour un VPS ou un serveur), soit vous gardez l’agent en natif sur votre machine mais vous utilisez Docker uniquement comme un sandbox (bac à sable) sécurisé pour exécuter son code (le meilleur des mondes pour le desktop).

Voici mon retour d’expérience et les configurations qui marchent chez moi, histoire de vous éviter quelques heures de galère avec les permissions.

Option 1 : Faire tourner tout l’agent dans Docker (Idéal pour le Cloud / VPS)

Si vous voulez un isolement complet ou que vous déployez ça sur un VPS à distance, c’est l’option la plus propre.

La méthode rapide (Direct Docker Run)

Si vous voulez juste tester rapidement la passerelle sans vous prendre la tête, vous pouvez initialiser le conteneur avec cette commande simple :

# On crée le dossier local pour les données persistantes
mkdir -p ~/.hermes

# On lance le conteneur
docker run -d \
  --name hermes-agent \
  --restart unless-stopped \
  -p 8642:8642 \
  -v ~/.hermes:/home/node/.hermes \
  -e HERMES_AUTH_TOKEN=votre-token-secret \
  -e OPENROUTER_API_KEY=sk-or-... \
  ghcr.io/nousresearch/hermes-agent:latest

La méthode propre (Docker Compose pour la prod)

Pour une installation plus pérenne avec le dashboard et la persistance des données, le multi-conteneur avec Compose est indispensable. J’utilise un fichier docker-compose.yml qui ressemble à ça :

version: '3.8'

services:
  hermes-agent:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes_core_stack
    restart: unless-stopped
    ports:
      - "8642:8642"   # Port de l'API Gateway et du Dashboard
      - "8000:8000"   # Port d'écoute optionnel pour les webhooks
    volumes:
      - hermes_data:/root/.hermes
      - /var/run/docker.sock:/var/run/docker.sock # Permet l'exécution imbriquée (nested sandbox) si besoin
    environment:
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - ALLOWED_TELEGRAM_USERS=${ALLOWED_TELEGRAM_USERS}
      - HERMES_AUTH_TOKEN=${HERMES_AUTH_TOKEN}
    stdin_open: true
    tty: true
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  hermes_data:
    name: hermes_agent_data
    driver: local

Pour que ça fonctionne, créez un fichier .env dans le même dossier pour stocker vos clés API en toute sécurité :

# Clés API pour les LLM
OPENROUTER_API_KEY=sk-or-v1-xxxxxx...
ANTHROPIC_API_KEY=sk-ant-xxxxxx...
OPENAI_API_KEY=sk-proj-xxxxxx...

# Token de sécurité pour l'endpoint 8642
HERMES_AUTH_TOKEN=choisissez_un_mot_de_passe_tres_long

# Optionnel : Intégration Telegram (recommandé pour interagir avec l'agent)
TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ
ALLOWED_TELEGRAM_USERS=987654321,112233445

Une fois le fichier .env configuré, lancez la bête en arrière-plan :

docker compose up -d

L’étape cruciale à ne pas manquer : comme l’agent tourne de manière isolée, vous devez lancer le script de configuration interactif à l’intérieur du conteneur pour définir sa personnalité et ses outils :

docker compose exec -it hermes-agent hermes setup

Vous pouvez ensuite suivre les logs en temps réel pour vérifier que la connexion avec votre fournisseur de LLM s’établit bien :

docker compose logs -f hermes-agent

Note sur la persistance des données

Grâce au volume nommé hermes_data lié à /root/.hermes, toutes les bases de données vectorielles (la mémoire épisodique de votre agent), ses profils et ses tokens d’autorisation sont conservés même si vous recréez le conteneur. Pratique pour ne pas lui faire perdre la mémoire à chaque mise à jour.

Option 2 : Docker comme Sandbox pour le Terminal (Le top sur PC de bureau)

Si vous faites tourner l’agent entièrement dans Docker sur votre propre PC, vous risquez d’avoir des soucis d’intégration (comme l’impossibilité d’ouvrir un navigateur web natif ou des conflits d’accès).

La solution idéale ? Installer Hermes de manière native sur votre machine, mais lui dire d’exécuter toutes les commandes terminal et le code dans un conteneur Docker éphémère.

Honnêtement, c’est de loin ma configuration préférée. Dès que l’agent veut compiler un script ou tester du code, il démarre silencieusement un conteneur jetable, fait son affaire, récupère le résultat et détruit le conteneur. Rien ne pollue votre système.

Configuration de la Sandbox :

1. Assurez-vous que Docker Desktop (Mac/Windows) est bien lancé. Sur Linux, vérifiez que votre utilisateur est bien dans le groupe Docker pour éviter de requérir sudo :

   sudo usermod -aG docker $USER
   # Pensez à redémarrer votre terminal après ça

2. Sur votre terminal hôte, dites à l’agent d’utiliser le backend Docker :

   hermes config set terminal.backend docker

3. (Optionnel) Si vos scripts ont besoin d’outils spécifiques (comme des bibliothèques scientifiques Python ou Node.js), vous pouvez changer l’image par défaut du sandbox :

   hermes config set terminal.docker.image python:3.11-slim

Comment ça marche en coulisses ?

Quand vous lancez l’agent en local via hermes terminal, demandez-lui : “Exécute une commande pour me donner le nom de l’OS du système, puis crée un fichier texte de test nommé sandbox_check.txt à la racine.”

Vous verrez qu’il va renvoyer les infos d’un système Linux Alpine ou Ubuntu (et non pas celles de votre macOS ou Windows hôte). De plus, le fichier sandbox_check.txt créé à la racine du conteneur disparaît instantanément dès que l’exécution se termine, protégeant ainsi votre disque dur.

Bonus : Configurer l’accès via Telegram

Pour ma part, j’adore pouvoir envoyer des requêtes à mon agent depuis mon téléphone. Pour lier votre instance Docker à Telegram :

1. Allez sur Telegram et lancez une conversation avec @BotFather. Envoyez la commande /newbot et notez précieusement le token HTTP API obtenu.
2. Écrivez ensuite à @userinfobot pour obtenir votre ID utilisateur numérique personnel (cela évite que n’importe qui sur Internet vienne utiliser votre agent à vos frais).
3. Renseignez ces paramètres dans vos variables d’environnement (.env) ou durant l’assistant hermes setup.
4. Pour lancer l’écoute, exécutez simplement hermes gateway run à l’intérieur de votre environnement.

---

Résolution des galères courantes (Permissions & Paths)

Si vous vous lancez là-dedans, vous allez probablement buter sur l’un de ces trois problèmes. Voici comment je m’en suis sorti :

Erreur 1 : “Permission denied” avec le socket Docker (/var/run/docker.sock)

• La cause : Votre agent n’a pas les droits pour parler au démon Docker de votre machine.
• Le fix (Linux) : Ajoutez votre utilisateur au groupe Docker (sudo usermod -aG docker $USER) et déconnectez-vous/reconnectez-vous de votre session utilisateur.
• Le fix (macOS/Windows) : Dans les paramètres avancés de Docker Desktop, vérifiez bien que l’option “Allow the default Docker socket to be used” est cochée.

Erreur 2 : Fichiers créés dans le workspace impossibles à modifier (Permission Error 13)

• La cause : Par défaut, les fichiers générés par le sandbox appartiennent à l’utilisateur root (ou UID 10000) du conteneur, rendant votre utilisateur hôte incapable de les modifier ou de les supprimer.
• Le fix : On va forcer Docker à s’aligner sur votre identité locale. Ouvrez votre fichier de configuration global (généralement dans ~/.hermes/config.yaml) et modifiez ces lignes :

  terminal:
    backend: docker
    docker_run_as_host_user: true   # Aligne l'UID/GID du conteneur sur le vôtre
    container_persistent: true      # Permet de garder le workspace intact entre les appels

Alternativement, vous pouvez exporter votre identité via votre profil de terminal de cette façon :

  export TERMINAL_DOCKER_EXTRA_ARGS='["--user=1000:1000"]'
  # Remplacez 1000:1000 par le résultat des commandes `id -u` et `id -g` sur votre machine

Erreur 3 : Les fichiers modifiés par l’agent n’apparaissent pas sur mon ordinateur

• La cause : L’agent écrit ses modifications dans l’environnement virtuel isolé de la sandbox plutôt que de cibler le dossier partagé avec votre machine hôte.
• Le fix : Forcez le montage de votre répertoire de travail actuel dans la configuration :

  terminal:
    backend: docker
    docker_mount_cwd_to_workspace: true  # Monte le dossier actuel dans /workspace
    docker_volumes:
      - "/chemin/vers/mon-projet:/workspace/project" # Bind direct si besoin

Voilà pour le tour d’horizon ! Si vous utilisez d’autres stacks d’agents ou si vous avez des astuces sur l’allocation des ressources (GPU notamment) pour faire tourner Hermes en local avec Docker, je suis preneur de vos retours en commentaires.