Hermes Agent Docker: guida completa alla distribuzione per il 2026

Two Docker Modes Explained: scegli prima di iniziare

La maggior parte delle guide salta completamente questa decisione e passa a docker run. Non. Le due modalità hanno profili di sicurezza e operativi significativamente diversi.

Mode 1 — Hermes che corre all'interno di un contenitore

Hermes e tutte le sue dipendenze vivono all'interno dell'immagine. Gestisci lo stato tramite volumi denominati. La politica di riavvio del contenitore lo mantiene attivo durante i riavvii. Questo è il modello di produzione più comune.

• Separazione pulita dall'host: nessuna scrittura accidentale sul tuo computer
• Portabilità completa; ridistribuirlo ovunque con lo stesso file di composizione
• Overhead leggermente più elevato rispetto alla versione nativa

Mode 2: Docker come sandbox backend del terminale

Qui, Hermes viene eseguito direttamente sull'host (o in un contenitore) e chiama il demone Docker per avviare contenitori temporanei per l'esecuzione della shell. Lo configuri impostando DOCKER_HOST in modo che Hermes possa raggiungere il demone:

export DOCKER_HOST=unix:///var/run/docker.sock   # Linux
export DOCKER_HOST=tcp://host.docker.internal:2375  # Windows/Mac (Docker Desktop)

Prerequisites and Environment Setup

Prima di estrarre qualsiasi immagine, conferma:

• Docker Engine 24+ O Docker Desktop 4.26+
• Una chiave API LLM pronta: OpenAI (OPENAI_API_KEY), Anthropic (ANTHROPIC_API_KEY) o un endpoint Ollama locale
• Accesso a Internet in uscita sulla porta 443 (per chiamate API LLM)
• Almeno 2 GB RAM allocato al contenitore (4 GB consigliati per le configurazioni supportate da Ollama)

Windows-Specific Setup (Docker Desktop + WSL2)

Windows è il luogo in cui la maggior parte delle distribuzioni Docker si interrompe silenziosamente. Fai attenzione a questi:

# Correct — Docker Desktop translates this automatically
volumes:
  - hermes_data:/root/.hermes

DOCKER_HOST=npipe:////./pipe/docker_engine

[wsl2]
memory=4GB
processors=2

Avvio rapido: esegui Hermes Agent con Docker in 5 minuti

Estrai l'immagine ufficiale ed esegui la procedura guidata di configurazione:

# Pull the latest image
docker pull nousresearch/hermes-agent:latest

# Run with a persistent volume for state
docker run -it \
  -v hermes_home:/root/.hermes \
  -e OPENAI_API_KEY=your_key_here \
  nousresearch/hermes-agent:latest

IL procedura guidata di configurazione si avvia alla prima esecuzione. Ti verrà richiesto di:

1. Seleziona il tuo provider LLM (OpenAI, Anthropic, Ollama o endpoint personalizzato)
2. Inserisci la chiave API o l'URL dell'endpoint
3. Configurare il backend del terminale (sandbox nativo o Docker)

Una volta completato, verifica che la sessione funzioni:

> hello

Production Deployment with Docker Compose

Il semplice comando docker run funziona per i test. Per qualsiasi cosa persistente, usa Compose.

Memorizza le tue chiavi API in un file .env (mai vincolato al controllo della versione):

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Preservare le competenze di Hermes nelle ricostruzioni dei container

Questa è la preoccupazione produttiva più trascurata. Hermes memorizza le competenze apprese separatamente dalla configurazione generale. Montare esplicitamente questi percorsi:

Quando aggiorni l'immagine:

docker compose pull
docker compose up -d   # Named volumes persist automatically

Advanced Topology: configurazione Host-Docker (contenitore gemellato).

Questa architettura viene utilizzata quando si desidera che Hermes orchestra i contenitori fratelli per l'esecuzione di codice isolato, ad esempio eseguendo in modo sicuro il codice inviato dall'utente.

┌─────────────────────────────────┐
│         Docker Host             │
│                                 │
│  ┌──────────────┐               │
│  │ hermes-agent │◄──socket──────┤── /var/run/docker.sock
│  │  container   │               │
│  └──────┬───────┘               │
│         │ docker run (sibling)  │
│  ┌──────▼───────┐               │
│  │  sandbox-1   │  (ephemeral)  │
│  └──────────────┘               │
└─────────────────────────────────┘

Componi la configurazione per questa topologia:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    restart: unless-stopped
    environment:
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      DOCKER_HOST: unix:///var/run/docker.sock
      HERMES_TERMINAL_BACKEND: docker
    volumes:
      - hermes_home:/root/.hermes
      - /var/run/docker.sock:/var/run/docker.sock  # Socket mount
    group_add:
      - "999"   # docker group GID — adjust to match your host

Connecting Hermes to Claude via Telegram Bot

La guida scritta di No attualmente copre questo argomento: viene mostrata solo in formato video. Ecco la configurazione completa.

/newbot
→ Name: Hermes Agent
→ Username: your_hermes_bot
→ Save the token: 123456:ABC-DEF...

environment:
  ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
  HERMES_LLM_PROVIDER: anthropic
  HERMES_TELEGRAM_TOKEN: ${TELEGRAM_BOT_TOKEN}
  HERMES_TELEGRAM_ALLOWED_USERS: "your_telegram_user_id"

docker compose up -d

Distribuzione multi-architettura (livello gratuito ARM64/Oracle/Raspberry Pi)

L'immagine nousresearch/hermes-agent viene fornita come manifest multi-arch. ARM64 è supportato: eseguilo esplicitamente sugli host ARM:

# Oracle Free Tier (Ampere A1) or Raspberry Pi 4/5
docker pull --platform linux/arm64 nousresearch/hermes-agent:latest

# Verify the architecture
docker inspect nousresearch/hermes-agent:latest | grep Architecture

Problemi noti specifici di ARM:

• Alcune quantizzazioni del modello Ollama (Q8) funzionano più lentamente su ARM; preferisci Q4_K_M per l'inferenza locale
• Se premi exec format error, conferma che stai utilizzando il flag --platform linux/arm64
• Docker Desktop su Apple Silicon gestisce ARM in modo nativo: non è necessario alcun flag di piattaforma

Risoluzione dei problemi comuni relativi agli errori Docker Hermes Agent

Una tabella di riferimento per gli errori che è più probabile riscontrare:

Frequently Asked Questions

Considerazioni finali: lista di controllo e passaggi successivi

Il ciclo di apprendimento è ciò che separa Hermes da ogni altro agente che hai eseguito in Docker. La configurazione di cui sopra garantisce effettivamente quel ciclo accumula - non si ripristina - ogni volta che invii un aggiornamento.

Prima di chiamare una distribuzione pronta per la produzione, conferma:

• ☐ Volumi denominati creati sia per hermes_home che per hermes_skills
• ☐ Chiavi API archiviate in .env, non hardcoded in composizione
• ☐ Criterio restart: unless-stopped attivo
• ☐ Superamento del controllo di integrità: docker inspect hermes-agent --format='{{.State.Health.Status}}'
• ☐ Rotazione log configurata (max-size, max-file)
• ☐ Limiti delle risorse impostati per prevenire l'esaurimento della memoria
• ☐ La procedura guidata di configurazione è stata completata e la prima sessione di chat è stata verificata
• ☐ (Se Mode 2) Montaggio socket Docker confermato e proxy socket considerato

Passaggi successivi per ottenere valore immediatamente:

1. Esegui alcune attività reali (riepilogo dei file, revisione del codice, ricerca sul web) per arricchire la libreria di competenze
2. Dopo 10-15 attività, esegui hermes skills list per vedere cosa è stato appreso
3. Consulta Nous Research GitHub per i documenti di configurazione dell'agente che coprono i modelli di competenze personalizzate e l'ottimizzazione della memoria
4. Se utilizzi il livello gratuito Oracle, configura un docker compose pull && docker compose up -d basato su cron per aggiornamenti delle immagini senza tempi di inattività preservando lo stato appreso