Leçon 001 · Stratégie de mise à jour

Mettre à jour Hermes sans casser la prod

Ta règle : si la nouvelle install ne marche pas, tu veux pouvoir revenir en arrière sans toucher à l'ancienne. Voici la stratégie qui rend ça possible.

La phrase à retenir : on ne met pas à jour une installation — on installe à côté et on bascule. L'ancienne reste intacte, fonctionnelle, et devient ton filet de sécurité.

Pourquoi hermes update est risqué chez toi

Trois faits mesurés sur ta machine (pas de la théorie) :

1,1 Go

Taille de state.db, ta base de sessions/messages. C'est 40 % de ton ~/.hermes (2,7 Go au total).

5 fichiers

Modifiés localement dans le code de Hermes, non commités. Un git pull les écrase ou fait claquer.

47 823

Commits de retard sur origin/main. Ton origin/main local était périmé avant même le fetch.

Les 5 fichiers modifiés — à décider AVANT toute mise à jour
 M agent/tool_guardrails.py
 M package-lock.json
 M plugins/platforms/telegram/adapter.py
?? adapter.py.bak-20260929-223843
?? plugins/platforms/telegram/adapter.py.bak-manual-20260929-224500

Le adapter.py Telegram patché à la main est le plus sensible : c'est là que se joue allow_bots, group_allow_from, group_allowed_chats. Si la version cible corrige déjà le bug, le patch devient du code mort.

Le vrai piège : le rollback, c'est restaurer l'état

Ton intuition « je remets l'ancien chemin et c'est reparti » est fausse, et c'est le point le plus important de cette leçon.

Les deux installations partagent le même ~/.hermes. Dès que le gateway de la version neuve a écrit une seule fois dans state.db, l'ancien code refuse de démarrer dessus : une version plus ancienne ne peut pas tourner sur une base que le runtime a déjà écrite.

SituationCe que « rollback » veut vraiment direDurée
Le nouveau code n'a rien écrit (fenêtre de test)Remettre l'ancien chemin dans systemd~30 s
Le nouveau code a démarré et écrit (bascule réelle)Restaurer la sauvegarde — pas un retour de code~2 min
À écrire noir sur blanc

« Le rollback, c'est restaurer l'état. » Annoncer « on remet l'ancien chemin en 30 s » sans restaurer la base, c'est vendre une sécurité qui n'existe pas.

La stratégie : « je ne migre pas, je change de dossier »

C'est exactement ton intuition, et elle est la bonne. Voici les 7 étapes, dans l'ordre, avec ce qui est mesuré.

Dans l'étape « sauvegarde », pourquoi faire un test de restauration dans un home jetable plutôt que se contenter de vérifier que l'archive existe ?

Les 7 étapes

#ÉtapePourquoi elle est indispensable
1Choisir la version cible (intersection git ∩ Docker)Un tag git seul ne suffit pas si l'autre machine tourne en Docker. v0.21.1 n'existait sur aucun canal ; v0.21.6 sur les deux.
2Inventaire des patchs locauxDécider garder / jeter fichier par fichier. Coller le .diff dans le wiki : un nom de fichier ne permet pas de restaurer un patch à la main.
3Sauvegarde chronométrée2,7 Go → ~830 Mo. Mesuré : 116 s puis 136 s.
4Test de restauration réelDans un HERMES_HOME jetable. Mesuré : 22 s, integrity_check: ok, 717 sessions / 85 396 messages identiques.
5Arrêt explicite du gatewayEn 0.17.0, hermes update n'arrête le service que sous Windows. Sous Linux, rien ne l'arrête : gateway qui tourne + venv qui se réinstalle = version mélangée en mémoire.
6Clone propre + venv dédiéL'ancien dossier reste intact et fonctionnel. C'est ton filet.
7Bascule systemd = 2 lignesSeuls ExecStart et PATH/VIRTUAL_ENV portent le chemin. WorkingDirectory, HERMES_HOME et EnvironmentFile sont déjà hors install.
Le compteurs de contrôle — ta preuve, pas « ça a l'air de sto »

Avant migration : SELECT COUNT(*) FROM sessions; SELECT COUNT(*) FROM messages; → 717 / 85 396 (valeur de l'audit du 19/10).

Après bascule : les mêmes deux chiffres. S'ils diffèrent, tu as perdu des données — et tu le sauras, pas moi.

Le piège silencieux : les dépendances installées à la main

Les scripts cron vivent dans ~/.hermes/scripts/ (hors install → jamais écrasés) et sont lancés par le scheduler avec sys.executable : ils suivent le nouveau venv automatiquement, mais pas leurs dépendances.

Un paquet installé à la main et absent de pyproject.toml n'existera pas dans le venv neuf → le script meurt sans erreur visible. Vécu : telethon a cassé le cron « Veille TG » de 9h en silence.

Les suspects sur ta machine

Les paquets installés récemment dans le venv : yt_dlp, olefile, aiohttp_socks, mautrix, asyncpg, python_socks, python_olm, aiosqlite.

Ta .env est en 24 Ko et ton venv a des deps comme ça → à reinstaller nommément dans le venv neuf, puis lancer chaque script cron à la main une fois avant la bascule.

Ton plan « deux utilisateurs système »

Ta stratégie : créer un compte utilisateur, faire une installation propre, et mettre à jour sur ce nouveau compte. C'est la variante **Docker** de KomputerMechanic, et elle est solide.

Ta prod actuelle (hôte)Le nouveau compte / setup
Code/usr/local/lib/hermes-agent (git + venv + systemd)Install parallèle, dossier à côté
DuréeEn service, ne pas toucherChronométrée : le clone + venv ≈ quelques minutes
Génération du codeCommit local, 5 fichiers modifiésAucun patch : on part du tag cible
Mémoire41 Mo (basestate.db du profil dev)400 Mo par setup Docker
FiletInstall intacte, on rebasculeOn garde l'ancienne au moins 1 semaine
La règle KomputerMechanic qui sauve la mémoire

Quand tu recrées le setup après un docker pull, tu dois garder exactement le même nom de volume :

docker pull nousresearch/hermes-agent
docker rm -f ton-setup
docker run -d \
  --name ton-setup \
  --restart unless-stopped \
  -v ton-setup:/opt/data \
  nousresearch/hermes-agent gateway run

Un nom différent → le setup repart vide, comme neuf. C'est l'erreur la plus fréquente, et elle est irréversible.

Et le conteneur MCT5 ?

Ton conteneur MCT5 est en nousresearch/hermes-agent:latest, image créée le 08/09/2026, digest sha256:a331dad8…. Il tourne Hermes 0.21.1.

Problème : :latest est un tag flottant. Au prochain docker pull, il peut sauter de version sans décision, sans sauvegarde, sans point de retour nommé.

Le correctif : épingler par digest
image: nousresearch/hermes-agent@sha256:a331dad885ca106052feda64ad49938e95aabd4ed28a019ecb7782cf7f903165

Le :latest reste en commentaire. Rollback = changer le digest = 30 s, zéro téléchargement.

Les drapeaux à vérifier avant de les utiliser

La doc de la branche main décrit le dépôt, pas ta version installée. Vérifie le flag réel :

Ce que hermes update --help dit vraiment en 0.17.0
usage: hermes update [-h] [--gateway] [--check] [--no-backup] [--backup]
                     [--yes] [--branch NAME] [--force]

Pas de --plan, pas de --keep-stash. Et surtout : --yes réapplique le stash → l'inventaire des patchs doit être terminé avant, pas pendant.

Tu lances hermes update --yes sur l'install actuelle. Que va-t-il se passer avec tes 5 fichiers modifiés localement ?

Ta checklist avant de lancer quoi que ce soit

La leçon suivante

La prochaine leçon attaque la configuration optimale : quelles clés de config.yaml changent vraiment le comportement de ton agent, lesquelles sont contre-productives dans ton cas (la compression à 50 %, la mémoire à 2 200 caractères, les toolsets par plateforme…), et comment les régler pour une vraie fluidité conversation ↔ mémoire ↔ outils ↔ skills.

Sources : skill hermes-install-migration (audit réel 0.17.0 → 0.21.6 du 19/10/2026) · KomputerMechanic — Multi Hermes on one VPS · doc officielle hermes-agent.nousresearch.com/docs