Come Eseguire Hermes Agent in Docker (Self-Hosted)

Perché Docker È il Modo Standard per Eseguire Hermes Agent

Hermes Agent viene distribuito come container Docker come target di distribuzione principale. L'immagine include il gateway, la dashboard, le dipendenze di runtime e una configurazione predefinita sensata, così non devi fare i conti con versioni di Python, librerie di sistema o problemi di PATH sull'host. Porti un host con Docker installato, un piccolo volume persistente per lo stato e la tua chiave API del provider. Il container fa il resto.

Una tipica configurazione self-hosted si presenta così:

• Un container gateway che espone la porta 8642 per l'API compatibile con OpenAI e l'endpoint di salute.
• Un volume con nome persistente per sessioni, memoria, skill apprese e configurazione.
• Un file .env con le chiavi del provider e le credenziali Telegram.
• Facoltativamente, un container dashboard sidecar che legge la stessa directory dati in modalità sola lettura.

Tutto il resto - aggiornamenti, riavvii, rotazione dei log - è gestito da Docker stesso. Questo articolo percorre quella configurazione dall'inizio alla fine, poi mostra il layout docker-compose pronto per la produzione e le insidie da conoscere prima di mettere l'agente su un host pubblico.

Se non hai ancora scelto tra ospitarlo tu stesso e una configurazione gestita, leggi prima self-hosting vs hosting gestito di Hermes Agent. Il resto di questa guida presuppone che tu abbia deciso di eseguire il container autonomamente.

Prerequisiti

Hai bisogno di:

• Un host con Docker 24+ installato (VPS Linux, macOS tramite Docker Desktop, o Windows tramite WSL2).
• Almeno 1 vCPU e 2 GB di RAM. La raccomandazione ufficiale è 2 vCPU e 8 GB per un uso concorrente comodo.
• Una chiave API del provider (OpenAI, Anthropic, OpenRouter, o qualsiasi endpoint compatibile con OpenAI).
• Circa 2 GB di spazio libero su disco per l'immagine, più spazio per la crescita del volume dati.

Un VPS da $5 di qualsiasi provider ragionevole soddisfa il minimo. L'agente è leggero in termini di I/O e CPU quando non sta elaborando attivamente - la maggior parte del tempo è inattivo in attesa di messaggi Telegram o attività pianificate.

Passo 1 - Crea la Directory dei Dati

Il container persiste tutto in /data all'interno dell'immagine. Sull'host, decidi dove risiede quella directory. La convenzione è ~/.hermes/data:

mkdir -p ~/.hermes/data

Questa singola directory contiene la cronologia delle sessioni, la memoria vettoriale, le skill apprese, i segreti cifrati e la configurazione utente. Esegui il backup di questa directory e avrai eseguito il backup dell'intero agente. Perdila e ricomincia da zero - il container stesso è effimero.

Passo 2 - Procedura Guidata di Configurazione al Primo Avvio

Esegui il container in modalità interattiva la prima volta, così può chiederti le chiavi e scriverle in ~/.hermes/.env:

docker run -it --rm \
  -v ~/.hermes:/root/.hermes \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest setup

La procedura guidata chiede:

• Il provider LLM predefinito (OpenAI, Anthropic, OpenRouter, personalizzato).
• La chiave API del provider.
• Token del bot Telegram facoltativo e lista degli utenti autorizzati.
• Chiavi del provider vocale facoltative (solo se intendi abilitare la modalità vocale).

I valori vengono scritti in ~/.hermes/.env sull'host. Tratta quel file come un segreto - chmod 600 ~/.hermes/.env e non fare mai il commit.

Passo 3 - Avvia il Gateway Persistente

Una volta completata la procedura guidata, la forma a esecuzione prolungata dello stesso container avvia il gateway:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -p 8642:8642 \
  --env-file ~/.hermes/.env \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest gateway

Spiegazione di ogni flag:

• -d esegue il container in background, staccato.
• --restart unless-stopped lo riavvia automaticamente dopo riavvii dell'host e crash.
• -p 8642:8642 espone l'API compatibile con OpenAI e l'endpoint /health.
• --env-file ~/.hermes/.env inietta le chiavi del provider senza incorporarle nell'immagine.
• -v ~/.hermes/data:/data è la riga della persistenza - rimuovi questa riga e l'agente dimentica tutto ad ogni riavvio.

Verifica che sia attivo:

curl http://localhost:8642/health
# {"status":"ok","gateway":"running"}

Se stai eseguendo su un VPS che vuoi raggiungere dal tuo laptop, non associare la porta a 0.0.0.0 direttamente. Metti un reverse proxy (Caddy, Nginx, Traefik) davanti con HTTPS, oppure esponi la porta solo tramite Tailscale o WireGuard. L'API compatibile con OpenAI non ha autenticazione di default - si fida della rete su cui si trova.

Passo 4 - Usa docker-compose per la Produzione

Per qualcosa al di là di un test rapido, passa a docker-compose.yaml. Rende la configurazione verificabile, riavviabile come unità e facile da estendere con il container dashboard sidecar opzionale:

services:
  gateway:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-gateway
    restart: unless-stopped
    command: gateway
    ports:
      - "127.0.0.1:8642:8642"
    env_file:
      - ./.env
    volumes:
      - hermes_data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8642/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 1G

  dashboard:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-dashboard
    restart: unless-stopped
    command: dashboard
    ports:
      - "127.0.0.1:8643:8643"
    volumes:
      - hermes_data:/data:ro
    depends_on:
      gateway:
        condition: service_healthy

volumes:
  hermes_data:

Alcuni dettagli da notare:

• Il container dashboard monta il volume dati in sola lettura (:ro). Legge solo sessioni e memoria per renderizzare l'interfaccia, senza mai scriverle. È questo che rende sicuro eseguirli entrambi.
• La porta del gateway è associata a 127.0.0.1 sull'host. L'esposizione pubblica è compito del reverse proxy, non di Docker.
• healthcheck permette a depends_on di attendere che il gateway sia pronto prima di avviare la dashboard.
• Un limite di memoria di 1 GB è comodo per la maggior parte dei carichi di lavoro su scala personale. Aumentalo per un uso ad alto traffico.

Avvia lo stack con docker compose up -d e segui i log con docker compose logs -f.

Passo 5 - Aggiornamenti

Il container è l'unità di aggiornamento. Per passare a una nuova versione:

docker compose pull
docker compose up -d

Compose ricrea il gateway con la nuova immagine mantenendo intatto il volume con nome. Memoria, skill e connessioni Telegram tornano esattamente come erano. Usa un tag specifico invece di latest per la produzione - ghcr.io/nousresearch/hermes-agent:0.42 invece di :latest - così gli aggiornamenti sono espliciti.

Prima di qualsiasi aggiornamento, crea uno snapshot del volume:

docker run --rm \
  -v hermes_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/hermes-$(date +%F).tar.gz -C /data .

Il ripristino è lo stesso comando al contrario. È più veloce e sicuro che fare il rollback della sola immagine.

Problemi Comuni

Due container gateway sullo stesso volume. I store di sessioni e memoria di Hermes assumono un singolo scrittore. Eseguire due container gateway contro gli stessi /data corromperà i file in pochi minuti. Il container dashboard sidecar va bene perché è in sola lettura.

--env-file mancante. Senza di esso, il container si avvia ma fallisce alla prima chiamata LLM con un 401. Controlla docker logs hermes se le risposte non arrivano mai.

Associazione a 0.0.0.0:8642 su un VPS pubblico. L'API non ha autenticazione integrata. Metti sempre un reverse proxy davanti che richieda HTTPS più autenticazione di base o una restrizione a livello di rete (Tailscale, regole del firewall).

Volumi anonimi. Se dimentichi la riga -v ~/.hermes/data:/data, Docker crea un volume anonimo. Sopravvive ai riavvii ma è difficile da trovare e facile da eliminare accidentalmente. Usa sempre un volume con nome o un bind sull'host.

Riconnessione del bot Telegram. Quando aggiorni, il bot si riconnette automaticamente. Se non lo fa, verifica che TELEGRAM_BOT_TOKEN sia ancora in .env e che il container abbia accesso a internet in uscita.

Per i problemi specifici di Telegram, risoluzione dei problemi di Hermes Agent su Telegram tratta il lato messaggistica in modo più approfondito.

Salta la Configurazione dei Container

Eseguire Hermes in Docker è semplice, ma sei tu a dover gestire l'host: backup, certificati TLS, rotazione dei log, aggiornamenti del sistema operativo e la cadenza degli aggiornamenti. Per un agente personale va bene - un pomeriggio di configurazione e forse dieci minuti al mese dopo.

Se preferisci evitare tutto questo, Hermify esegue il tuo agente Hermes in un container gestito isolato, con segreti cifrati a riposo, aggiornamenti automatici, snapshot giornalieri del volume e Telegram connesso tramite la dashboard in due tap. Tu porti una chiave del provider; la piattaforma gestisce tutto il resto.

Fonti

• Guida utente Docker di Hermes Agent
• Quickstart di Hermes Agent
• Guida alla distribuzione docker-compose di Hermes Agent
• Self-hosting di Hermes Agent su un VPS da $5
• Best practice per volumi e storage persistente Docker 2026
• Docker Compose per agenti AI