Tutorial 16: Distribuzione con Docker

Tutorial 16: Distribuzione con Docker

Bentornati, esploratori di Hermes! Nell’ultimo tutorial, abbiamo imparato a eseguire Hermes Agent direttamente sulle nostre macchine. Oggi passiamo al livello successivo: mettiamo Hermes dentro un container Docker. Questo cambia le regole del gioco per mantenere il tuo setup pulito, portabile e facile da aggiornare.

Due Modi in Cui Docker Incontra Hermes

Prima di immergerci, è importante capire che Docker e Hermes Agent possono lavorare insieme in due modi distinti:

1. Eseguire Hermes in Docker – L’agente stesso vive dentro un container. È su questo che ci concentreremo oggi.
2. Docker come backend di terminale – Hermes gira sul tuo host, ma ogni comando che esegue avviene dentro un sandbox Docker persistente. È ottimo per sicurezza e isolamento, ma è un argomento per un’altra volta.

Oggi ci concentriamo sull’opzione 1. La bellezza di questo approccio è che tutti i tuoi dati—configurazione, chiavi API, sessioni, skill e memorie—vivono in una singola directory sul tuo host, montata nel container su /opt/data. Il container stesso è stateless, quindi puoi scaricare una nuova versione e aggiornare senza perdere nulla.

Avvio Rapido: Il Tuo Primo Container

Se sei completamente nuovo a Hermes, il percorso più semplice è creare una directory dati ed eseguire la procedura guidata di configurazione in modo interattivo. Ti guiderà nell’inserimento delle tue chiavi API e le salverà in ~/.hermes/.env.

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Un avvertimento: evita le console VPS basate su browser (come quella di Hetzner Cloud) per questi comandi. Spesso alterano caratteri speciali come :, @ e =, che possono corrompere silenziosamente i tuoi argomenti docker run. Connettiti sempre via SSH (ssh root@<host>) per un inserimento sicuro con copia-incolla. Se devi assolutamente usare la console del browser, digita i comandi manualmente e ricontrolla ogni carattere.

Una volta nella procedura guidata, è altamente consigliato configurare un sistema di chat (Telegram, Discord, ecc.) così il tuo gateway ha un posto dove inviare i messaggi.

Esecuzione in Modalità Gateway

Una volta configurato, vorrai eseguire Hermes come gateway di background persistente. È così che si connette alle tue piattaforme di chat e resta attivo 24/7.

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

Il flag -p 8642:8642 espone il server API compatibile con OpenAI del gateway e l’endpoint di health. È opzionale se usi solo piattaforme di chat, ma è necessario se vuoi che la dashboard o strumenti esterni raggiungano il tuo gateway.

Ecco una nuova funzionalità interessante: dentro l’immagine Docker ufficiale, gateway run è ora automaticamente supervisionato da s6-overlay. Questo significa che se il processo del gateway va in crash, viene riavviato entro secondi senza perdere il container. Vedrai un breadcrumb in docker logs che conferma l’aggiornamento. Se vuoi il vecchio comportamento (dove il container esce quando il gateway esce), passa --no-supervise o imposta HERMES_GATEWAY_NO_SUPERVISE=1. Per la produzione, il default supervisionato è strettamente migliore.

Esporre il Server API

Di default, il server API è protetto da API_SERVER_ENABLED=true. Per esporlo oltre 127.0.0.1 dentro il container, dovrai impostare alcune variabili d’ambiente:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_HOST=0.0.0.0 \
  -e API_SERVER_KEY="$(openssl rand -hex 32)" \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

La API_SERVER_KEY deve essere di almeno 8 caratteri—generane una con openssl rand -hex 32. Importante: aprire qualsiasi porta su una macchina esposta a internet è un rischio per la sicurezza. Non farlo a meno che tu non comprenda appieno le implicazioni.

Eseguire la Dashboard

Vuoi una dashboard web per monitorare il tuo gateway? Imposta HERMES_DASHBOARD=1 ed esponi la porta 9119:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Anche la dashboard è supervisionata da s6, quindi si riavvia automaticamente se va in crash. Il suo output finisce in docker logs <container>.

Una Nota sui Limiti del Tool-Loop

Per i gateway senza supervisione, considera di abilitare arresti forzati per i limiti del tool-loop. Il default è false, che va bene per sessioni interattive dove un umano può vedere gli avvisi. Ma in un gateway senza supervisione, un agente bloccato in un loop potrebbe non fermarsi mai. Aggiungi questo al config.yaml del tuo profilo:

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

Conclusione

Questa è la storia della distribuzione con Docker! Ora hai un container stateless e aggiornabile con tutti i tuoi dati montati in sicurezza sull’host. Nel prossimo tutorial, esploreremo la dashboard in maggior dettaglio. Fino ad allora, buon containerizzare!