Hermes Agent Docker : déploiement sur VPS

Introduction

Un déploiement Hermes Agent Docker sur VPS devient utile lorsque votre agent doit répondre en continu, survivre aux déconnexions SSH et conserver ses sessions. Ce guide s’adresse aux builders ayant déjà validé Hermes localement et prêts à administrer un service exposé avec prudence. Vous allez préparer le volume /opt/data, lancer la gateway supervisée par s6, protéger le dashboard, puis tester redémarrage, sauvegarde et restauration. Si votre usage reste ponctuel, si vous ne savez pas maintenir Docker ou si aucune disponibilité 24/7 n’est requise, ce n’est pas le bon choix : une installation Hermes Agent locale reste plus simple et réduit la surface d’attaque.

Résumé rapide

1. Réservez un VPS Linux avec Docker Compose, 2 Go de RAM et un accès SSH par clé.
2. Montez un répertoire hôte sauvegardable sur /opt/data, seule source de vérité de Hermes.
3. Exécutez gateway run dans l’image officielle ; s6 supervise la gateway et le dashboard.
4. Publiez le dashboard uniquement sur 127.0.0.1, activez son authentification et utilisez un tunnel SSH.
5. Validez les données après un redémarrage, puis automatisez sauvegardes testées et mises à jour réversibles.

Comprendre l’architecture Hermes sur un VPS

Faire tourner Hermes dans Docker signifie que l’application, la gateway et ses outils vivent dans l’image nousresearch/hermes-agent. Ce n’est pas le « backend terminal Docker », où Hermes reste installé sur l’hôte mais envoie seulement ses commandes dans un bac à sable. Ici, l’image est remplaçable et son état durable est externalisé.

Le montage vers /opt/data est donc le contrat essentiel. Il contient notamment .env, config.yaml, SOUL.md, les sessions, mémoires, compétences, profils, tâches cron, hooks et logs. Le code installé sous /opt/hermes est immuable dans l’image publiée. Une recréation de conteneur ne doit rien faire perdre tant que le répertoire hôte monté sur /opt/data reste intact.

Dans l’image officielle actuelle, s6-overlay est PID 1. La commande gateway run enregistre une gateway supervisée : si son processus tombe, s6 le relance après un court délai sans attendre le redémarrage complet du conteneur. Avec HERMES_DASHBOARD=1, le dashboard rejoint le même arbre de supervision. Ne lancez donc pas un second conteneur dashboard isolé pour ce déploiement minimal.

Pour une petite équipe, partez sur un VPS Ubuntu ou Debian avec 2 vCPU, 2 à 4 Go de RAM et 2 Go de disque disponible pour les données. Un gigaoctet peut suffire sans navigateur, mais Chromium augmente nettement la consommation. Le cadre plus large pour déployer un agent IA en production reste applicable : moindre privilège, journalisation, budget, restauration et contrôle des accès comptent autant que le démarrage initial.

Le réseau minimal n’expose ni 8642 ni 9119 au public. Les connecteurs Telegram ou Discord établissent généralement des connexions sortantes. Le port 8642 n’est nécessaire que pour l’API compatible OpenAI ou un client externe ; son serveur doit alors être activé explicitement, recevoir une clé dédiée et rester derrière une politique réseau. Le dashboard écoute sur 9119, mais nous le publions seulement sur le loopback du VPS pour l’atteindre par tunnel SSH.

Déployer Hermes Agent avec Docker Compose

La procédure suivante suppose un utilisateur d’administration non-root membre du groupe Docker, un DNS non indispensable et un pare-feu qui autorise SSH. Connectez-vous avec un vrai client SSH plutôt qu’avec une console web : certaines consoles transmettent mal les caractères :, @ ou =, ce qui peut corrompre un montage ou un secret collé.

1. Vérifier le VPS et préparer les répertoires

Contrôlez les prérequis avant de créer quoi que ce soit :

docker --version
docker compose version
df -h /srv
free -h

Résultat attendu : Docker et le plugin Compose affichent une version, le disque possède plusieurs gigaoctets libres et la mémoire correspond au dimensionnement prévu. Installez Docker depuis son dépôt officiel si une commande manque.

Créez ensuite un dossier d’exploitation distinct du volume de données :

sudo install -d -m 0750 -o "$USER" -g "$USER" /srv/hermes
install -d -m 0700 /srv/hermes/data /srv/hermes/backups
cd /srv/hermes

/srv/hermes/data sera monté sur /opt/data. Ne le partagez jamais entre deux conteneurs gateway actifs : les sessions et mémoires ne sont pas conçues pour des écritures concurrentes.

2. Initialiser la configuration persistante

Lancez une fois l’assistant dans un conteneur éphémère :

docker run -it --rm \
  -v /srv/hermes/data:/opt/data \
  nousresearch/hermes-agent:latest setup

Saisissez les identifiants uniquement dans l’assistant. Ils sont écrits dans /srv/hermes/data/.env, jamais dans le fichier Compose. Si vous utilisez Nous Portal, la commande proposée par la documentation est hermes setup --portal; vous pouvez la lancer avec le même montage. À la fin :

find /srv/hermes/data -maxdepth 1 -printf '%f\n' | sort
sudo chmod 600 /srv/hermes/data/.env

Résultat attendu : config.yaml et .env existent. N’affichez pas le contenu de .env dans votre terminal partagé, vos logs CI ou une capture. Ce volume contient aussi les futurs historiques et compétences ; sa protection équivaut à celle du compte agent.

3. Créer les secrets du dashboard hors du dépôt

Depuis juin 2026, un dashboard lié à une adresse non-loopback dans le conteneur échoue fermé si aucun fournisseur d’authentification n’est configuré. HERMES_DASHBOARD_INSECURE=1 est désormais obsolète et ignoré. Pour ce VPS, utilisez l’authentification basique intégrée et limitez la publication Docker à l’adresse locale.

Créez un fichier d’environnement réservé à Compose sans recopier de clé de modèle :

umask 077
{
  printf 'HERMES_DASHBOARD_USER=admin\n'
  printf 'HERMES_DASHBOARD_PASSWORD=%s\n' "$(openssl rand -base64 36 | tr -d '\n')"
  printf 'HERMES_DASHBOARD_SECRET=%s\n' "$(openssl rand -hex 32)"
} > /srv/hermes/compose.env
chmod 600 /srv/hermes/compose.env

Le mot de passe protège la connexion ; le secret stabilise les sessions après redémarrage. Ne versionnez pas ce fichier. L’authentification basique convient ici parce que le navigateur passe dans un tunnel SSH chiffré, pas directement par Internet. Pour une exposition publique derrière HTTPS, préférez OAuth Nous Portal ou votre fournisseur OIDC, avec un reverse proxy correctement déclaré.

4. Écrire un Compose minimal et sûr

Créez /srv/hermes/compose.yaml :

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    shm_size: "1gb"
    volumes:
      - /srv/hermes/data:/opt/data
    ports:
      - "127.0.0.1:9119:9119"
    environment:
      HERMES_DASHBOARD: "1"
      HERMES_DASHBOARD_BASIC_AUTH_USERNAME: "${HERMES_DASHBOARD_USER}"
      HERMES_DASHBOARD_BASIC_AUTH_PASSWORD: "${HERMES_DASHBOARD_PASSWORD}"
      HERMES_DASHBOARD_BASIC_AUTH_SECRET: "${HERMES_DASHBOARD_SECRET}"

shm_size évite un manque de mémoire partagée si vous activez les outils navigateur. Aucun port gateway 8642 n’est publié : le dashboard supervisé est colocalisé avec la gateway, et un bot de messagerie n’en a pas besoin. Si un client API l’exige plus tard, activez API_SERVER_ENABLED=true, définissez API_SERVER_HOST=0.0.0.0 et une API_SERVER_KEY d’au moins huit caractères, puis publiez d’abord 127.0.0.1:8642:8642, pas 8642:8642 sur toutes les interfaces.

Validez le rendu Compose sans imprimer les valeurs résolues :

cd /srv/hermes
docker compose --env-file compose.env config --quiet
docker compose --env-file compose.env pull
docker compose --env-file compose.env up -d
docker compose ps

Résultat attendu : le service hermes est Up. Le processus principal peut être un heartbeat sleep infinity : c’est normal avec s6, qui gère la vraie gateway. Consultez l’état autoritatif plutôt que de conclure depuis ps :

docker exec hermes hermes gateway status
docker exec hermes hermes status
docker exec hermes /command/s6-svstat /run/service/gateway-default
docker compose logs --tail 80 hermes

La sortie doit indiquer une gateway active et Manager: s6 (container supervisor). Les logs ne doivent montrer ni boucle de crash ni erreur d’authentification. Pour apprendre à distinguer signaux utiles et bruit, consultez le guide d’observabilité des agents IA.

5. Ouvrir le dashboard par tunnel SSH

Depuis votre ordinateur, et non depuis le VPS, exécutez :

ssh -N -L 9119:127.0.0.1:9119 utilisateur@adresse-du-vps

Gardez cette session ouverte, puis visitez http://127.0.0.1:9119. Le navigateur doit afficher l’écran de connexion ; utilisez l’utilisateur et le mot de passe conservés hors dépôt. Vérifiez aussi qu’une requête directe vers http://adresse-du-vps:9119 échoue depuis un autre réseau. Le tunnel chiffre le trajet et le bind Docker local empêche le port de répondre sur l’IP publique.

N’utilisez pas 0.0.0.0 --insecure comme raccourci : l’option ne désactive plus l’authentification, et publier une surface d’administration reste inutilement risqué. Les mêmes principes de sécurité des agents IA s’appliquent aux clés, sessions, outils et contenus visibles depuis ce dashboard.

6. Tester santé, persistance et reprise

Créez un marqueur non secret dans le volume, redémarrez, puis vérifiez les deux couches :

printf 'OC-246 persistence test\n' > /srv/hermes/data/persistence-check.txt
docker restart hermes
docker compose --env-file /srv/hermes/compose.env -f /srv/hermes/compose.yaml ps
docker exec hermes test -f /opt/data/persistence-check.txt
docker exec hermes hermes gateway status
docker exec hermes /command/s6-svstat /run/service/gateway-default

Résultat attendu : test retourne le code 0, le conteneur revient à l’état Up et la gateway est active sous s6. Ouvrez ensuite le dashboard via le tunnel : sa configuration et les sessions antérieures doivent toujours être présentes. Ce test sépare clairement persistance du conteneur, reprise du superviseur et accès réseau.

Les logs gateway persistants se trouvent sous /srv/hermes/data/logs/gateways/default/current; docker logs hermes montre les flux du conteneur courant. Le journal /srv/hermes/data/logs/container-boot.log indique les profils réconciliés au démarrage. Surveillez espace disque, mémoire, redémarrages et erreurs de fournisseur, mais n’expédiez jamais les secrets bruts vers un service de logs tiers.

7. Sauvegarder, mettre à jour et restaurer

Avant chaque mise à jour, arrêtez brièvement les écritures et archivez le volume avec ses permissions :

cd /srv/hermes
docker compose --env-file compose.env stop hermes
tar --numeric-owner -C /srv/hermes -czf \
  "/srv/hermes/backups/hermes-data-$(date -u +%Y%m%dT%H%M%SZ).tgz" data
docker compose --env-file compose.env start hermes

Chiffrez et exportez l’archive vers un autre système : une sauvegarde sur le même disque ne protège pas d’une panne VPS. Conservez séparément compose.yaml et compose.env dans un coffre adapté, ce dernier étant secret.

Mettez ensuite l’image à jour et recréez le service :

cd /srv/hermes
docker compose --env-file compose.env pull
docker compose --env-file compose.env up -d
docker exec hermes hermes gateway status
docker compose logs --tail 80 hermes

Au démarrage, l’image actuelle applique les migrations de configuration non interactives et crée des copies horodatées de .env et config.yaml lorsqu’une migration est nécessaire. N’activez HERMES_SKIP_CONFIG_MIGRATION=1 que pour examiner manuellement une migration bloquée.

Pour restaurer, arrêtez le service, déplacez le dossier défectueux sans le supprimer, extrayez une archive choisie, puis redémarrez :

cd /srv/hermes
docker compose --env-file compose.env stop hermes
mv data "data.failed-$(date -u +%Y%m%dT%H%M%SZ)"
tar -xzf /chemin/vers/hermes-data-YYYYmmddTHHMMSSZ.tgz -C /srv/hermes
docker compose --env-file compose.env up -d
docker exec hermes hermes gateway status

La restauration n’est validée qu’après connexion au dashboard, lecture d’une session connue et contrôle des logs. Testez ce parcours périodiquement sur une machine isolée ; une archive jamais restaurée reste une hypothèse, pas un plan de reprise.

Exemple concret : valider un bot persistant

Prenons un indépendant qui a déjà configuré Telegram localement et veut un Hermes Agent self hosted disponible après une maintenance du VPS. Il déploie le Compose précédent, ouvre le dashboard par tunnel SSH et crée dans Hermes une session nommée validation-vps. Il y envoie un message sans secret, par exemple « Réponds avec le marqueur VPS-OK et mémorise que ce test date du 4 septembre 2026 ».

Il note l’identifiant ou le titre de la session, puis lance le scénario d’acceptation :

cd /srv/hermes
docker compose --env-file compose.env ps
docker exec hermes hermes gateway status
printf 'before-restart\n' > data/persistence-check.txt
docker restart hermes
docker exec hermes test -s /opt/data/persistence-check.txt
docker exec hermes hermes gateway status
docker compose logs --tail 100 hermes

Après le redémarrage, il rouvre http://127.0.0.1:9119 par le tunnel, retrouve validation-vps et envoie un second message depuis Telegram. Le test passe si le fichier persiste, si s6 rapporte la gateway active, si la session est visible et si le bot répond sans reconnexion manuelle. Il vérifie enfin que le port 9119 n’est pas accessible depuis Internet.

Pour tester la sauvegarde sans risquer la production, il copie l’archive sur un second VPS, l’extrait sous /srv/hermes/data, fournit un nouveau compose.env depuis son coffre et démarre un unique conteneur, connecteurs externes temporairement désactivés. Il contrôle une session connue puis détruit l’environnement d’essai. Ce protocole prouve le redémarrage et la portabilité des données ; regarder seulement docker ps ne prouverait ni l’un ni l’autre.

Bonnes pratiques

• Épinglez un tag d’image testé en production plutôt que latest si vous exigez des déploiements reproductibles ; promouvez une version après validation sur une copie du volume.
• Gardez SSH par clé, désactivez le login root distant et limitez le pare-feu. Ni 9119 ni 8642 ne doivent écouter publiquement dans l’architecture proposée.
• Sauvegardez /opt/data chiffré hors du VPS et exercez une restauration. Protégez .env, compose.env, sessions et mémoires comme des secrets.
• Ne montez pas /var/run/docker.sock sauf besoin démontré : il confère au conteneur un contrôle puissant sur l’hôte.
• Posez des limites CPU et mémoire après avoir observé la charge réelle. Avec le navigateur, conservez shm_size: 1gb et surveillez les OOM.
• Lisez docker compose logs, les logs gateway persistants et container-boot.log; alertez sur les redémarrages répétés, l’espace disque bas et les erreurs d’API.
• N’exécutez jamais deux gateways contre le même volume. Pour plusieurs identités, utilisez les profils supervisés du même conteneur ou des volumes strictement distincts.

En pratique, la maintenance fiable repose sur trois tests courts : gateway active sous s6, session conservée après redémarrage, restauration réussie sur une cible isolée. Si personne ne peut assurer ces contrôles, restez sur une installation locale ou un service managé plutôt que d’accumuler une dette d’exploitation.

Comparez les offres VPS adaptées à un agent persistant, puis sécurisez votre gateway avant de connecter Telegram.

Questions fréquentes

Comment déployer Hermes Agent avec Docker sur un VPS ?

Installez Docker Compose, créez un répertoire hôte protégé, montez-le sur /opt/data, puis lancez l’image nousresearch/hermes-agent avec command: gateway run et restart: unless-stopped. Initialisez d’abord la configuration dans un conteneur éphémère. Après le démarrage, vérifiez la gateway avec docker exec hermes hermes gateway status et testez un redémarrage réel.

Où Hermes Agent Docker conserve-t-il ses données ?

Dans l’image officielle, toute donnée mutable doit vivre sous /opt/data : configuration, .env, profils, sessions, mémoires, compétences, cron et logs. Montez ce chemin sur un bind mount ou un volume durable du VPS. /opt/hermes contient l’application immuable ; le modifier dans le conteneur n’est pas une stratégie de persistance.

Comment sécuriser le dashboard Hermes Agent ?

Publiez le port uniquement sur 127.0.0.1, configurez l’authentification basique intégrée et rejoignez-le avec ssh -L 9119:127.0.0.1:9119. Pour une URL publique, utilisez HTTPS avec OAuth ou OIDC et un proxy de confiance précisément déclaré. HERMES_DASHBOARD_INSECURE ne désactive plus l’authentification et ne doit pas servir de contournement.

Comment mettre à jour Hermes Agent self hosted sans perdre les sessions ?

Arrêtez brièvement la gateway, sauvegardez le répertoire monté sur /opt/data, puis exécutez docker compose pull et docker compose up -d. Contrôlez ensuite la gateway, les logs et une session existante. Les données survivent parce qu’elles restent hors de l’image, mais seule une restauration testée protège contre une migration ou une archive défectueuse.

Articles liés

À retenir : Docker rend l’image Hermes remplaçable, mais la continuité dépend du volume /opt/data, d’un accès dashboard fermé par défaut et de tests de reprise. Cette architecture est adaptée à un agent réellement nécessaire 24/7 ; sinon, commencez localement. La prochaine étape logique consiste à consolider la sécurité et l’observabilité avant de connecter davantage de canaux.

• Hermes Agent : guide pour builders IA
• Installer Hermes Agent avant le passage sur VPS
• Diagnostiquer Hermes Agent par symptôme
• Sécurité des agents IA : réduire la surface d’attaque
• Observabilité des agents IA : logs et indicateurs