Docker + Hermes Agent: Due Modi per Giocare

Se ti sei mai chiesto come Docker si inserisce nel quadro di Hermes Agent, sei nel posto giusto. In realtà ci sono due modi distinti in cui questi due possono lavorare insieme, e vale la pena conoscere la differenza prima di iniziare a digitare docker run.

Le Due Modalità di Docker

Eseguire Hermes IN Docker — l’agente stesso vive all’interno di un container. Questo è il focus principale di questa guida.
Docker come backend di terminale — Hermes gira sulla tua macchina host, ma ogni comando che esegue avviene all’interno di un singolo sandbox Docker persistente. Quel sandbox sopravvive alle chiamate degli strumenti, a /new, e persino ai subagent finché il processo Hermes è attivo.

Questo articolo copre l’opzione 1. La cosa fondamentale da sapere: tutti i tuoi dati (config, chiavi API, sessioni, skill, memorie) vivono in una singola directory sul tuo host, montata su /opt/data all’interno del container. L’immagine stessa è stateless, quindi puoi scaricare una nuova versione in qualsiasi momento senza perdere la tua configurazione.

Avvio Rapido: Configurazione Iniziale

Se è la tua prima volta, crea una directory dati e avvia il container in modalità interattiva per eseguire la procedura guidata di configurazione:

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

Questo ti porta nella procedura guidata, che ti chiede le tue chiavi API e le scrive in ~/.hermes/.env. Devi farlo solo una volta. Già che ci sei, è un ottimo momento per configurare un sistema di chat (Telegram, Discord, ecc.) così il tuo gateway ha un posto dove parlare.

⚠️ Un avvertimento: Evita le console VPS basate su browser per questi comandi di installazione. Alcuni provider (come Hetzner) alterano i caratteri speciali — : può arrivare come ;, @ viene renderizzato male, e le chiavi API incollate possono essere corrotte silenziosamente. Connettiti sempre via SSH per un inserimento comandi sicuro da copia-incolla. Se devi usare la console del browser, digita i comandi manualmente e ricontrolla ogni :, @, = e /.

Consiglio da pro: All’interno del container, esegui hermes setup --portal una volta — il token di refresh persiste nel tuo volume montato ~/.hermes.

Esecuzione in Modalità Gateway

Una volta configurato, esegui il container in background come gateway persistente:

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

La porta 8642 espone il server API compatibile OpenAI del gateway e l’endpoint di health. È opzionale se usi solo piattaforme di chat, ma è richiesta se vuoi che la dashboard o strumenti esterni raggiungano il gateway.

Cosa C’è di Nuovo: Gateway Supervisionato

Ecco un grande cambiamento: all’interno dell’immagine Docker ufficiale, gateway run ora è automaticamente supervisionato da s6-overlay. Se il gateway si blocca, si riavvia entro secondi senza perdere il container. La dashboard (quando abilitata) è supervisionata insieme ad esso.

Vedrai una breadcrumb di una riga in docker logs che conferma l’aggiornamento. Per rinunciare e ottenere il vecchio comportamento (uscita dal container = uscita dal gateway), passa --no-supervise o imposta HERMES_GATEWAY_NO_SUPERVISE=1. Questo è utile per test di fumo CI; per la produzione, il default supervisionato è decisamente migliore.

Arresti Forzati del Tool-Loop

Un’impostazione importante per i gateway non presidiati: tool_loop_guardrails.hard_stop_enabled è impostato su false di default. Va bene per sessioni interattive dove un umano può vedere gli avvisi. Ma in deployment non presidiati, i soli avvisi potrebbero non fermare un agente bloccato in un loop. Se vuoi il comportamento da interruttore automatico, abilitalo nel config.yaml del tuo profilo:

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

Esporre il Server API

Il server API è limitato da API_SERVER_ENABLED=true. Per esporlo oltre 127.0.0.1 all’interno del container, imposta anche API_SERVER_HOST=0.0.0.0 e una API_SERVER_KEY (minimo 8 caratteri — generane una con openssl rand -hex 32):

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

Nota di sicurezza: Aprire qualsiasi porta su una macchina esposta a internet è un rischio. Non farlo a meno che tu non comprenda appieno le conseguenze.

Eseguire la Dashboard

La dashboard web integrata gira come servizio s6-rc supervisionato insieme al gateway nello stesso container. Basta impostare HERMES_DASHBOARD=1:

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

Se la dashboard si blocca, s6-supervise la riavvia automaticamente dopo un breve backoff. Il suo output va a docker logs <container>.

Dove Finiscono i Log

Per la mappa completa del routing (gateway per profilo, dashboard, boot reconciler e docker logs a livello di container), consulta la sezione dedicata nella documentazione. In breve: tutto finisce alla fine in docker logs, ma con prefissi chiari così puoi capire cosa è cosa.

Conclusioni

Docker ti offre un modo pulito e aggiornabile per eseguire Hermes Agent. Il container è stateless, i tuoi dati vivono in sicurezza sull’host, e la nuova supervisione s6 significa che il tuo gateway rimane attivo anche se si blocca. Che tu stia eseguendo una configurazione semplice o una combinazione completa dashboard + server API, i comandi sopra ti portano lì in pochi minuti.