Hermes Agent : l'agent IA autonome open source que tu héberges chez toi

Tu connais peut-être cette frustration : tu passes une heure à expliquer à ton assistant IA comment fonctionne ton projet, tes choix techniques et les bugs déjà résolus… puis, le lendemain, tout est à recommencer.

Les assistants IA classiques sont très bons pour une session de travail. Ils perdent toutefois souvent leur contexte quand le terminal se ferme : pas de continuité, pas de canal de discussion durable, et peu de mémoire réutilisable d'une session à l'autre.

Hermes Agent répond à un autre besoin : garder un agent disponible sur ta machine, avec une mémoire persistante, plusieurs profils et plusieurs points d'accès. Il peut tourner en continu dans Docker, mais ce fonctionnement dépend de ta configuration, de tes ressources et du fournisseur de modèle choisi.

Cet article explique ce que Hermes apporte réellement, ce que le boilerplate Docker ajoute, puis comment le déployer sans exposer inutilement tes clés ni tes interfaces d'administration.

---

Hermes en 30 secondes

Hermes Agent est un agent open source développé par Nous Research. Son point fort n'est pas de remplacer tous les assistants de code : c'est de fournir une base persistante, pilotable depuis plusieurs interfaces.

Concrètement, tu retrouves :

• une mémoire persistante bornée et organisée, injectée au démarrage des sessions ;
• une gateway et des outils pour le terminal, le web, les fichiers ou les tâches planifiées ;
• plusieurs points d'accès : CLI/TUI, dashboard local, API et canaux comme Telegram selon les plugins activés ;
• des profils séparés pour isoler configuration, clés, personnalité et contexte de travail.

---

Pourquoi Hermes fait une vraie différence

Fini la réexplication éternelle

Tu connais la routine : tu relances ton assistant, et c'est reparti pour 15 minutes de « comme je t'ai expliqué hier… ». Hermes réduit cette répétition en conservant des informations utiles dans sa mémoire et en permettant de retrouver ses sessions.

Cette mémoire n'est pas une copie infinie de toutes tes conversations. Elle repose sur des fichiers et des entrées gérées par l'agent, avec des limites de taille, puis est chargée au début d'une session. Il faut donc la considérer comme un carnet de contexte ciblé, pas comme une garantie de rappel parfait.

Ton assistant, où tu veux, comme tu veux

Hermes s'adapte à ton workflow de dev :

• Depuis ton téléphone via Telegram, pour des requêtes rapides ou de la veille.
• Depuis ton navigateur avec le dashboard natif (port 9119) ou le WebUI (port 8787).
• Depuis ton terminal en CLI classique via docker compose run --rm hermes.
• Depuis tes scripts personnels via son API REST sur le port 8642.

Un même environnement, plusieurs points d'entrée. Tu choisis le canal qui correspond à la tâche au lieu de recopier ton contexte partout.

Plusieurs agents, plusieurs vies

Besoin de séparer tes contextes de travail et de vie perso ? Les profils Hermes isolent notamment leur configuration, leurs clés, leur personnalité et leur mémoire :

• Un agent Work pour le code, les revues et la documentation.
• Un agent Veille pour résumer des flux RSS ou des articles.
• Un agent Perso pour tes idées de projets et ton organisation.
• Un agent DevOps pour la supervision, tes scripts d'infra et les alertes.

Chaque profil dispose de son propre espace. Évite toutefois de faire tourner plusieurs agents qui écrivent dans le même dossier Hermes : les mémoires et les sessions pourraient se mélanger.

Tes données, chez toi, sous contrôle

Le runtime, les fichiers de configuration et les sessions peuvent rester sur ta machine. Cela ne signifie pas que toutes les données restent locales : si tu utilises OpenRouter, Anthropic, OpenAI ou un autre fournisseur distant, tes requêtes et certains résultats lui sont transmis selon ses conditions.

Tu gardes la main sur les volumes Docker, les sauvegardes et les droits d'accès. Pour une confidentialité maximale, choisis un modèle local et protège les canaux externes ; pour un modèle cloud, vérifie les règles de conservation et d'utilisation des données du fournisseur.

---

Des cas d'usage concrets

Voici les scénarios où un agent persistant devient intéressant :

• POC rapides : lui demander d'explorer une architecture, de générer un premier squelette ou de préparer une documentation, puis relire et valider le résultat.
• Discussions d'architecture : reprendre une décision plusieurs jours plus tard sans repartir de zéro, à condition d'avoir conservé les bonnes notes dans la mémoire.
• Analyse de dépôts : cloner, lire et résumer un dépôt GitHub ou GitLab lorsque les accès et les outils nécessaires sont configurés.
• Veille d'issues : surveiller des tickets, les regrouper et préparer des propositions de correction, pas appliquer automatiquement des changements en production.
• Notifications et tâches planifiées : exécuter un script de contrôle et envoyer un rapport ou une alerte Telegram lorsqu'un service rencontre un problème.

---

Déployer Hermes avec le boilerplate Docker

Le dépôt benoitpetit/hermes-agent-docker contient une intégration prête à adapter : Docker Compose, image enrichie, WebUI séparé et scripts de maintenance.

Il contient le docker-compose.yml, le Dockerfile enrichi, la structure de configuration config/ et des scripts utilitaires.

Avant de commencer

Prévois Docker Compose v2, quelques gigaoctets de RAM pour les outils navigateur, un fournisseur de modèle (local ou distant) et, si tu veux le piloter par Telegram, un bot et une liste d'utilisateurs autorisés. Le dashboard Hermes et le WebUI restent liés à la machine par défaut ; ne publie pas leurs ports directement sur Internet.

Structure du projet

Copier
hermes-agent-docker/
├── docker-compose.yml      # Services Hermes + Hermes WebUI
├── Dockerfile              # Image enrichie (chromium, whisper, plugins...)
├── README.md               # Guide d'installation complet
├── scripts/
│   ├── hermes-cli          # CLI principale (contrôle, chat, setup, webui)
│   ├── sync-runtime-config.sh  # Synchronise config/ vers data_runtime/
│   ├── maintenance-data.sh # Rotation et backup des données de mémoire
│   └── ops-watchdog.sh     # Surveillance et auto-réparation
├── config/
│   ├── .env.example        # Template des variables d'environnement
│   ├── config.yaml         # Modèles, mémoire, paramètres non secrets
│   └── SOUL.md             # Personnalité de ton agent
└── data_runtime/           # Données persistantes (mémoire, logs, sessions)

L'image Docker enrichie

Le Dockerfile hérite de l'image officielle nousresearch/hermes-agent:latest et y ajoute des outils indispensables :

• Chromium + Chromium Driver : Permet à l'agent de naviguer sur le web pour lire des documentations ou tester une UI.
• Faster-Whisper : Pour la transcription de tes messages vocaux Telegram (Speech-to-Text).
• jq & curl : Pour faciliter l'exécution de scripts shell par l'agent.
• Un healthcheck automatique sur le port API 8642.

Configuration en 3 fichiers simples

Ne versionne jamais config/.env, les tokens Telegram ou les clés de fournisseur. Le fichier doit rester local et être couvert par ton .gitignore.

Le docker-compose.yml pré-paramétré

Copier
services:
  # ── Agent principal ──────────────────────────────────
  hermes:
    build: .
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "127.0.0.1:8642:8642"   # API REST
      - "127.0.0.1:9119:9119"   # Dashboard Web
    volumes:
      - ./data_runtime:/opt/data
      # IMPORTANT : Ne monte pas directement config.yaml et .env individuellement à la racine de /opt/data
      # Les paramètres de l'API et du dashboard sont écrits de manière atomique (fichier temporaire + renommage).
      # Monter un fichier individuel ferait échouer l'écriture avec une erreur EBUSY.
      # Utilise le volume data_runtime à la place et le script de synchronisation.
      - ./config/SOUL.md:/opt/data/SOUL.md:ro
      - hermes-agent-src:/opt/hermes   # Partagé avec le WebUI
    environment:
      - HERMES_DASHBOARD=1
      - HERMES_UID=1000
      - HERMES_GID=1000
      - HF_TOKEN=${HF_TOKEN:-}
      - PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
      - PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox,--disable-dev-shm-usage
    env_file:
      - ./config/.env
    shm_size: 1g
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

  # ── Interface Web (Hermes WebUI) ─────────────────────
  hermes-webui:
    image: ghcr.io/nesquena/hermes-webui:latest
    container_name: hermes-webui
    depends_on:
      - hermes
    ports:
      - "127.0.0.1:8787:8787"
    volumes:
      - ./data_runtime:/home/hermeswebui/.hermes          # Config, sessions, mémoire partagées
      - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent:ro  # Source agent (deps)
      - ${HERMES_WORKSPACE:-${HOME:-/root}/workspace}:/workspace       # Navigateur de fichiers
    environment:
      - HERMES_WEBUI_HOST=0.0.0.0
      - HERMES_WEBUI_PORT=8787
      - HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui
      - WANTED_UID=1000
      - WANTED_GID=1000
      - HERMES_SKIP_CHMOD=1
      # - HERMES_WEBUI_PASSWORD=${HERMES_WEBUI_PASSWORD:-}  # Décommente pour protéger l'accès
    restart: unless-stopped

volumes:
  hermes-agent-src:          # Volume partagé du code source de l'agent

---

Première installation

1. Clone et prépare l'environnement

Copier
git clone https://github.com/benoitpetit/hermes-agent-docker.git
cd hermes-agent-docker

# Crée tes fichiers de config locaux
cp config/.env.example config/.env
nano config/.env

2. Choisis ton modèle IA

Ouvre config/config.yaml et configure ton provider préféré (Ollama en local, OpenRouter pour le cloud, Anthropic, OpenAI, etc.). Les noms de modèles, leur disponibilité et leur prix changent régulièrement : considère l'exemple ci-dessous comme un point de départ, pas comme une valeur garantie.

Copier
model:
  provider: openrouter
  default: deepseek/deepseek-v4-flash:free # Exemple : vérifie le modèle disponible

3. Configure Telegram (recommandé)

1. Discute avec @BotFather sur Telegram pour créer un nouveau bot et obtenir ton token.
2. Copie le token dans la variable TELEGRAM_BOT_TOKEN de ton fichier .env.
3. Récupère ton ID Telegram personnel (via un bot comme @userinfobot) et ajoute-le dans TELEGRAM_ALLOWED_USERS pour sécuriser l'accès à ton bot.

4. Initialise et synchronise la configuration (Indispensable)

Comme expliqué plus haut, Hermes lit ses fichiers de configuration dynamiquement depuis le dossier de runtime monté (data_runtime/). Pour propager tes modifications du dossier config/ vers le runtime, tu dois exécuter le script de synchronisation fourni :

Copier
# Synchronise config.yaml et .env vers data_runtime/
./scripts/sync-runtime-config.sh

(Note : Si tu lances Hermes via le script interactif hermes-cli comme décrit plus bas, cette synchronisation est automatique !)

5. Lance le conteneur

Pour démarrer les conteneurs (l'agent + l'interface web WebUI), tu as deux méthodes :

Option A (Recommandée) : Via le script CLI unifié Le script gère la synchronisation de configuration automatiquement et démarre les services proprement :

Copier
./scripts/hermes-cli start

Option B : Via docker compose brut Si tu préfères la commande Docker classique (assure-toi d'avoir exécuté l'étape 4 de synchronisation au préalable) :

Copier
docker compose up -d

Tu peux vérifier que tout fonctionne correctement :

Copier
# Test de l'API healthcheck
curl http://localhost:8642/health

# Lecture des logs de démarrage
docker compose logs -f hermes hermes-webui

Rends-toi sur http://localhost:9119 pour accéder au dashboard web d'administration, ou sur http://localhost:8787 pour l'interface WebUI (Hermes WebUI).

6. Interagis avec ton agent

Copier
# Ouvre le menu interactif ou lance une conversation dans ton terminal
./scripts/hermes-cli

# Exécute un diagnostic système
./scripts/hermes-cli doctor

# Gérer l'interface WebUI (status, logs, restart)
./scripts/hermes-cli webui status
./scripts/hermes-cli webui logs
./scripts/hermes-cli webui restart

---

Dashboard Hermes et WebUI : deux interfaces différentes

Le boilerplate embarque aussi Hermes WebUI, une interface web sombre et légère pour discuter avec l'agent et parcourir ton workspace. Elle ne doit pas être confondue avec le dashboard Hermes natif :

• le dashboard Hermes sur le port 9119 sert à administrer l'installation, les sessions, les modèles et les paramètres ;
• le WebUI du boilerplate sur le port 8787 fournit une interface de chat et de navigation complémentaire ;
• le WebUI lance par défaut son propre agent in-process, ou peut être configuré pour passer par la gateway principale.

Les deux interfaces partagent certains volumes dans ce setup, mais elles ne garantissent pas automatiquement une session de chat unique. Vérifie le mode gateway si tu veux centraliser les conversations.

Architecture

• hermes : gateway + dashboard (inchangé)
• hermes-webui : interface web, démarre son propre agent in-process
• data_runtime/ : volume partagé (config, sessions, skills, mémoire)

Les deux conteneurs partagent data_runtime/ : les sessions créées depuis le WebUI apparaissent dans le gateway et vice-versa.

Accès rapide

Copier
# Tout est lancé d'un coup
docker compose up -d

# Ouvrir dans le navigateur
xdg-open http://localhost:8787

# Ou via le menu interactif (option 15)
./scripts/hermes-cli menu

Configuration

Le WebUI détecte automatiquement ta configuration Hermes existante (provider, modèle, skills). Quelques variables optionnelles dans config/.env :

Exemple avec mot de passe et workspace personnalisé :

Copier
echo "HERMES_WEBUI_PASSWORD=mon-super-mot-de-passe" >> config/.env
echo "HERMES_WORKSPACE=/home/ben/projets" >> config/.env
docker compose up -d --force-recreate hermes-webui

Mode gateway (chat back-end)

Par défaut, le WebUI lance son propre agent in-process. Tu peux le faire transiter par le gateway de l'agent principal pour partager la même session :

Copier
HERMES_WEBUI_CHAT_BACKEND=gateway \
HERMES_WEBUI_GATEWAY_BASE_URL=http://hermes:8642 \
HERMES_WEBUI_GATEWAY_API_KEY=ta-cle-api \
docker compose up -d --force-recreate hermes-webui

---

Limites et précautions à connaître

Hermes est une base intéressante, mais il ne devient pas un opérateur autonome infaillible pour autant :

• la mémoire est volontairement bornée et peut oublier un détail ;
• un modèle distant reçoit les données nécessaires à ses réponses ;
• les outils terminal, navigateur et fichiers peuvent modifier ton environnement ;
• les tâches planifiées et les canaux de messagerie élargissent la surface d'attaque ;
• la qualité, la latence et le coût dépendent du fournisseur et du modèle choisis.

Commence avec des permissions minimales, une liste explicite d'utilisateurs Telegram autorisés, des sauvegardes testées et un environnement de test séparé avant d'autoriser des opérations sensibles.

Pour aller plus loin

• Dépôt officiel du projet : github.com/NousResearch/hermes-agent
• Documentation officielle : hermes-agent.nousresearch.com/docs
• Hermes WebUI : github.com/nesquena/hermes-webui
• Créateur de bot Telegram : t.me/BotFather

---

Tu as déjà testé Hermes Agent ou tu as des idées de workflows à partager ? Viens en parler sur Mastodon ou sur Bluesky !

Article co-écrit avec l'IA · Images générées avec l'IA.