Lancer Hermes Agent dans Docker (auto-hébergé)

Pourquoi Docker est la façon par défaut de lancer Hermes Agent

Hermes Agent est livré comme conteneur Docker en cible de déploiement principale. L'image embarque le gateway, le dashboard, les dépendances d'exécution et une configuration par défaut raisonnable, vous évitant ainsi les batailles avec les versions de Python, les bibliothèques système ou les soucis de PATH sur l'hôte. Vous fournissez un hôte avec Docker installé, un petit volume persistant pour l'état et votre clé API du fournisseur. Le conteneur fait le reste.

Une installation auto-hébergée typique ressemble à ceci :

Un conteneur gateway qui expose le port 8642 pour l'API compatible OpenAI et l'endpoint de santé.
Un volume nommé persistant pour les sessions, la mémoire, les skills appris et la configuration.
Un fichier .env avec les clés du fournisseur et les identifiants Telegram.
Optionnellement, un conteneur dashboard sidecar qui lit le même répertoire de données en lecture seule.

Tout le reste - mises à jour, redémarrages, rotation des logs - est géré par Docker lui-même. Cet article parcourt cette installation de bout en bout, puis montre la disposition docker-compose prête pour la production et les détails à connaître avant de mettre l'agent sur un hôte public.

Si vous n'avez pas encore choisi entre l'auto-hébergement et une version managée, lisez d'abord auto-hébergé vs managé pour Hermes Agent. La suite de ce guide suppose que vous avez décidé de faire tourner le conteneur vous-même.

Prérequis

Il vous faut :

Un hôte avec Docker 24+ installé (VPS Linux, macOS via Docker Desktop ou Windows via WSL2).
Au moins 1 vCPU et 2 Go de RAM. La recommandation officielle est 2 vCPU et 8 Go pour un usage concurrent confortable.
Une clé API de fournisseur (OpenAI, Anthropic, OpenRouter ou n'importe quel endpoint compatible OpenAI).
Environ 2 Go d'espace disque libre pour l'image, plus une marge pour la croissance du volume de données.

Un VPS à 5 dollars chez n'importe quel fournisseur correct couvre le minimum. L'agent consomme peu de CPU et peu d'E/S quand il ne raisonne pas activement - il passe la plus grande partie de la journée inactif à attendre des messages Telegram ou des tâches planifiées.

Étape 1 - Créer le répertoire de données

Le conteneur persiste tout dans /data à l'intérieur de l'image. Sur l'hôte, choisissez où vit ce répertoire. La convention est ~/.hermes/data :

mkdir -p ~/.hermes/data

Ce seul répertoire contient l'historique des sessions, la mémoire vectorielle, les skills appris, les secrets chiffrés et la configuration utilisateur. Sauvegardez-le et vous avez sauvegardé l'agent en entier. Perdez-le et vous repartez de zéro - le conteneur en lui-même est éphémère.

Étape 2 - Assistant de configuration initiale

Lancez le conteneur en mode interactif la première fois pour qu'il puisse vous demander vos clés et les écrire dans ~/.hermes/.env :

docker run -it --rm \
  -v ~/.hermes:/root/.hermes \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest setup

L'assistant pose des questions sur :

Le fournisseur LLM par défaut (OpenAI, Anthropic, OpenRouter, custom).
La clé API du fournisseur.
Le token optionnel du bot Telegram et la liste des utilisateurs autorisés.
Les clés optionnelles du fournisseur de voix (uniquement si vous prévoyez d'activer le mode vocal).

Les valeurs sont écrites dans ~/.hermes/.env sur l'hôte. Traitez ce fichier comme un secret - chmod 600 ~/.hermes/.env et ne le committez jamais.

Un terminal montrant l'assistant de configuration Docker de Hermes Agent demandant une clé API OpenAI, avec le chemin du nouveau fichier .env visible en haut

Étape 3 - Lancer le gateway persistant

Une fois l'assistant terminé, la forme longue durée du même conteneur démarre le gateway :

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -p 8642:8642 \
  --env-file ~/.hermes/.env \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest gateway

Détail de chaque flag :

-d lance le conteneur en arrière-plan, en mode détaché.
--restart unless-stopped le ramène automatiquement après les redémarrages et les plantages de l'hôte.
-p 8642:8642 expose l'API compatible OpenAI et l'endpoint /health.
--env-file ~/.hermes/.env injecte les clés du fournisseur sans les inclure dans l'image.
-v ~/.hermes/data:/data est la ligne de la persistance - supprimez cette ligne et l'agent oublie tout à chaque redémarrage.

Vérifiez qu'il est en bonne santé :

curl http://localhost:8642/health
# {"status":"ok","gateway":"running"}

Si vous tournez sur un VPS auquel vous voulez accéder depuis votre portable, n'exposez pas le port directement sur 0.0.0.0. Mettez un reverse proxy (Caddy, Nginx, Traefik) devant avec HTTPS, ou n'exposez le port qu'à travers Tailscale ou WireGuard. L'API compatible OpenAI n'a pas d'authentification par défaut - elle fait confiance au réseau dans lequel elle est.

Étape 4 - Utiliser docker-compose en production

Pour tout ce qui dépasse un test rapide, passez à docker-compose.yaml. Cela rend la configuration relisible, redémarrable comme un tout et facile à étendre avec le sidecar dashboard optionnel :

services:
  gateway:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-gateway
    restart: unless-stopped
    command: gateway
    ports:
      - "127.0.0.1:8642:8642"
    env_file:
      - ./.env
    volumes:
      - hermes_data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8642/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 1G

  dashboard:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-dashboard
    restart: unless-stopped
    command: dashboard
    ports:
      - "127.0.0.1:8643:8643"
    volumes:
      - hermes_data:/data:ro
    depends_on:
      gateway:
        condition: service_healthy

volumes:
  hermes_data:

Quelques points à noter :

Le conteneur dashboard monte le volume de données en lecture seule (:ro). Il ne fait que lire les sessions et la mémoire pour afficher l'UI, jamais d'écriture. C'est ce qui permet de faire tourner les deux en sécurité.
Le port du gateway est lié à 127.0.0.1 sur l'hôte. L'exposition publique est le travail du reverse proxy, pas de Docker.
healthcheck permet à depends_on d'attendre le gateway avant de démarrer le dashboard.
Une limite mémoire de 1 Go est confortable pour des charges à l'échelle personnelle. Augmentez-la pour un trafic important.

Levez la stack avec docker compose up -d et suivez les logs avec docker compose logs -f.

Un schéma d'architecture simplifié montrant l'hôte Docker avec deux conteneurs, gateway et dashboard, partageant un seul volume nommé monté en lecture seule du côté du dashboard

Étape 5 - Mises à jour

Le conteneur est l'unité de mise à jour. Pour passer à une nouvelle version :

docker compose pull
docker compose up -d

Compose recrée le gateway avec la nouvelle image en gardant le volume nommé intact. Mémoire, skills et connexions Telegram reviennent exactement comme avant. Fixez un tag précis plutôt que latest en production - ghcr.io/nousresearch/hermes-agent:0.42 plutôt que :latest - pour que les mises à jour soient explicites.

Avant chaque mise à jour, faites un snapshot du volume :

docker run --rm \
  -v hermes_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/hermes-$(date +%F).tar.gz -C /data .

Restaurer est la même commande à l'envers. C'est plus rapide et plus sûr qu'un rollback de la seule image.

Pièges courants

Deux conteneurs gateway sur le même volume. Les magasins de session et de mémoire de Hermes supposent un seul écrivain. Faire tourner deux conteneurs gateway sur le même /data corrompt les fichiers en quelques minutes. Le sidecar dashboard est OK parce qu'il est en lecture seule.

--env-file manquant. Sans lui, le conteneur démarre mais le premier appel LLM échoue en 401. Vérifiez docker logs hermes si les réponses ne viennent jamais.

Bind sur 0.0.0.0:8642 sur un VPS public. L'API n'a pas d'authentification intégrée. Mettez toujours un reverse proxy devant qui exige du HTTPS plus de l'auth basique ou une restriction réseau (Tailscale, règles de firewall).

Volumes anonymes. Si vous oubliez la ligne -v ~/.hermes/data:/data, Docker crée un volume anonyme. Il survit aux redémarrages mais est difficile à retrouver et facile à pruner par accident. Utilisez toujours un volume nommé ou un bind sur l'hôte.

Reconnexion du bot Telegram. Quand vous mettez à jour, le bot se reconnecte automatiquement. S'il ne le fait pas, vérifiez que TELEGRAM_BOT_TOKEN est toujours dans .env et que le conteneur a une sortie internet.

Pour les problèmes spécifiques à Telegram, Dépannage de Hermes Agent sur Telegram couvre la partie messagerie plus en détail.

Sautez toute la plomberie de conteneurs

Lancer Hermes dans Docker est direct, mais l'hôte reste votre responsabilité : sauvegardes, certificats TLS, rotation des logs, patchs OS et cadence des mises à jour. Pour un agent personnel c'est très bien - un dimanche après-midi de setup et peut-être dix minutes par mois après.

Si vous préférez sauter tout cela, Hermify lance votre agent Hermes dans un conteneur managé isolé, avec secrets chiffrés au repos, mises à jour automatiques, snapshots quotidiens du volume et Telegram connecté depuis le dashboard en deux taps. Vous fournissez la clé du fournisseur ; la plateforme s'occupe de tout le reste.