Tutorial 4: Aggiornare e Disinstallare Hermes

Bentornati alla nostra serie di tutorial su Hermes Agent! In questa puntata parleremo di qualcosa che prima o poi ogni utente deve sapere: come mantenere Hermes aggiornato e come salutarlo quando arriva il momento. Non preoccupatevi — è molto più semplice di quanto sembri.

Aggiornare Hermes: Basta un Comando

Il modo più semplice per aggiornare Hermes è con un singolo comando:

hermes update

Tutto qui. Questo comando fa tutto il lavoro pesante per voi. Scarica l’ultimo codice dal branch main, aggiorna le dipendenze e vi chiede persino informazioni sulle nuove opzioni di configurazione aggiunte dall’ultimo aggiornamento. Carino, vero?

Cosa Succede Realmente Durante un Aggiornamento?

Potreste chiedervi cosa succede dietro le quinte. Ecco il dettaglio:

Snapshot pre-aggiornamento — Prima che qualsiasi cosa cambi, Hermes salva uno snapshot leggero dei vostri file di stato importanti (dati di associazione, cron job, config.yaml, .env e altro). I file oltre 1 GiB vengono saltati, così un database enorme non rallenta le cose. Questo snapshot viene creato per ogni profilo nella vostra installazione, ciascuno archiviato nella propria directory state-snapshots/.
Git pull — Hermes scarica l’ultimo codice dal branch main e aggiorna i sottomoduli.
Validazione sintattica post-pull + rollback automatico — Dopo il pull, Hermes verifica i nove file critici che ogni comando richiede all’avvio. Se uno di questi non viene parsato correttamente (come un marcatore di conflitto di merge rimasto lì per sbaglio), Hermes esegue automaticamente il rollback alla versione precedente, così la vostra shell rimane avviabile. Potete semplicemente rieseguire hermes update una volta che la correzione arriva upstream.
Installazione dipendenze — Esegue uv pip install -e ".[all]" per recuperare eventuali dipendenze nuove o modificate.
Migrazione configurazione — Rileva nuove opzioni di configurazione e vi chiede di impostarle.
Riavvio automatico del gateway — I gateway in esecuzione vengono aggiornati così il nuovo codice ha effetto immediatamente. I gateway gestiti dal servizio (systemd su Linux, launchd su macOS) vengono riavviati tramite il gestore dei servizi, mentre i gateway manuali vengono rilanciati automaticamente.

Hai Saltato la Richiesta di Configurazione? Nessun Problema!

Se avete saltato la richiesta di configurazione durante un aggiornamento, potete recuperare in seguito:

hermes config check    # vedere cosa manca
hermes config migrate  # aggiungerle in modo interattivo

Aggiornare da un Branch Diverso

Di default, hermes update tiene traccia di origin/main. Ma cosa fare se volete testare una release candidate o un branch di funzionalità? Usate il flag --branch:

hermes update --branch release-candidate
hermes update --check --branch experimental   # solo per vedere quanto siete indietro

Se il vostro checkout locale è su un branch diverso, Hermes mette automaticamente da parte (stash) qualsiasi lavoro non committato, passa al branch di destinazione e fa il pull. I branch che non esistono localmente vengono tracciati automaticamente da origin/<nome>. Se un branch non esiste da nessuna parte, il comando fallisce in modo pulito e ripristina le modifiche messe da parte.

E i Branch “Parcheggiati”?

Se il vostro checkout si trova su un branch di funzionalità, hermes update lo gestisce in modo intelligente:

Branch completamente mergiato — Hermes vi dice che è stato completamente mergiato e torna su main.
Commit non mergiati, albero pulito — Hermes passa comunque a main così l’aggiornamento procede (importante per chiamanti non interattivi come l’app desktop o i cron job). I vostri commit restano intatti e Hermes stampa un avviso ben visibile con il nome del branch e come tornarci.

Se deliberatamente mantenete patch personalizzate su un branch, impostate questo in config.yaml:

updates:
  parked_branch_strategy: update_in_place

Questo merge origin/main dentro il vostro branch invece di cambiare branch. Fast-forward quando possibile; in caso di divergenza, crea un tag di sicurezza e si ferma in modo pulito in caso di conflitto.

Modifiche Locali Durante Aggiornamenti Non Interattivi

Quando eseguite hermes update in un terminale, Hermes mette da parte le modifiche non committate, fa il pull e poi vi chiede se ripristinarle. Ma quando l’aggiornamento viene eseguito senza terminale (come dall’app desktop), Hermes salta l’aggiornamento se l’albero è sporco — con un avviso ben visibile che indica il branch e quanto è indietro. Niente finte di aggiornamento riuscito!

Disinstallare Hermes

Quando è il momento di separarsi, la disinstallazione è semplice. Assicuratevi di controllare la documentazione specifica della vostra piattaforma per i passaggi esatti di rimozione, ma in generale dovrete rimuovere il binario di Hermes e pulire le directory di configurazione che ha creato.

Conclusioni

Mantenere Hermes aggiornato è un gioco da ragazzi con hermes update. Le reti di sicurezza integrate — snapshot, rollback automatico e gestione dei branch — significano che potete aggiornare con fiducia. E se mai avete bisogno di allontanarvi, la disinstallazione è altrettanto semplice.

Restate sintonizzati per il prossimo tutorial della nostra serie!