Guide

Installare Hermes Agent su Mac con Docker

18 maggio 2026

Questa guida spiega come eseguire Hermes Agent su Mac usando Docker Desktop. Docker gestisce l’ambiente di esecuzione, mentre la cartella dati resta sul Mac e sopravvive ai riavvii del container.

Hermes Agent può usare provider con API key, ma qui usiamo OpenAI Codex con ChatGPT OAuth. Il percorso consigliato è: installare Docker Desktop, eseguire setup, scegliere il provider, avviare Hermes Agent e verificare la dashboard locale su localhost:9119.

Riepilogo rapido

Installa e avvia Docker Desktop per Mac.
Usa l’immagine ufficiale nousresearch/hermes-agent.
Monta ~/.hermes su /opt/data per mantenere configurazione, OAuth, sessioni, skills e log.
Esegui prima setup, poi scegli OpenAI Codex con hermes model.
Con la dashboard attiva, http://localhost:9119 deve aprirsi nel browser.

Requisiti

Requisito	Perché serve
Mac	Funziona con Apple Silicon e Intel; scegli l’installer Docker corretto.
Docker Desktop	Serve per eseguire il container Hermes Agent.
Terminale	Serve per comandi Docker, setup, OAuth e log.
Account ChatGPT	Serve per collegare OpenAI Codex con ChatGPT OAuth.
Connessione Internet	Serve per scaricare l’immagine e completare il login OAuth.

Diagramma con Mac, Docker Desktop, container Hermes Agent e volume persistente — Docker esegue Hermes Agent nel container, mentre `~/.hermes` conserva i dati sul Mac.

Cosa cambia con Docker

Hermes Agent è un runtime per AI agent di NousResearch. La documentazione ufficiale descrive più modalità d’uso, tra cui local installation, Docker execution e Docker terminal backend. Questa guida si concentra sull’esecuzione di Hermes Agent dentro un container Docker.

Il vantaggio è un ambiente più isolato. Non devi installare Python, Node.js, browser automation dependencies e strumenti collegati direttamente in macOS. In cambio, Docker Desktop deve essere avviato prima e l’accesso ai file va gestito tramite le cartelle che monti esplicitamente.

Hermes Agent usa /opt/data come posizione dati nel container. Per questo colleghiamo ~/.hermes sul Mac a /opt/data.

Installare Docker Desktop

Scarica Docker Desktop dalla documentazione ufficiale per Mac. Usa la versione Apple Silicon per i Mac M-series e la versione Intel per i Mac più vecchi.

Il flusso di installazione è questo:

Scarica Docker Desktop dalla pagina ufficiale per Mac.
Apri Docker.dmg e sposta Docker nella cartella Applicazioni.
Avvia Docker Desktop da Applicazioni.
Controlla le richieste iniziali di permesso e i termini.
Aspetta che l’icona Docker nella barra menu sia stabile.

Poi verifica:

docker --version

Se il comando non esiste, Docker Desktop potrebbe non essere ancora in esecuzione o il CLI non essere pronto.

Flusso di installazione Docker Desktop e verifica con docker version — Controlla Docker Desktop prima di avviare l'immagine Hermes Agent.

Perché montare `~/.hermes`

Il volume mount evita di perdere dati quando il container viene rimosso. Usalo in ogni comando Hermes:

-v ~/.hermes:/opt/data

Diagramma che collega la cartella ~/.hermes del Mac a /opt/data nel container Docker — Il mount `~/.hermes:/opt/data` conserva impostazioni, sessioni, OAuth, skills e log.

Primo avvio: setup wizard

Crea la cartella dati ed esegui il setup ufficiale:

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

--rm elimina il container temporaneo alla fine, ma i file in /opt/data restano in ~/.hermes.

Il setup wizard può creare o aggiornare:

Percorso	Funzione
`~/.hermes/.env`	Secret per provider basati su API key.
`~/.hermes/config.yaml`	Impostazioni di modello, backend, gateway e strumenti.
`~/.hermes/SOUL.md`	Comportamento e orientamento base dell’agent.
`~/.hermes/sessions/`	Cronologia delle sessioni.
`~/.hermes/memories/`	Memoria a lungo termine, se attiva.
`~/.hermes/skills/`	Skills installate.
`~/.hermes/logs/`	Log di esecuzione.

I prompt esatti possono cambiare in base alla versione di Hermes Agent, ma questa regola pratica è utile:

Prompt di setup	Scelta pratica
Model provider	Scegli `OpenAI Codex` o un’opzione `Codex`. Se non è visibile, completa setup e poi esegui `hermes model`.
Authentication method	I provider con API key salvano valori in `.env`. ChatGPT OAuth salva token in un auth store come `auth.json`.
Chat system o gateway integration	Telegram, Discord o Slack possono essere configurati dopo se non servono subito. Se userai gateway a lungo, configurarli qui può essere comodo.
Default poco chiari	Mantieni i default e modifica `config.yaml` dopo che l’installazione funziona.

In pratica, lascia che setup crei file e cartelle base; se la scelta del provider non è chiara, riapri poi la configurazione con hermes model.

Controlla poi:

ls -la ~/.hermes

Verifica anche che esista config.yaml. Non pubblicare il file completo; basta leggere localmente le prime righe.

sed -n '1,80p' ~/.hermes/config.yaml

Non stampare o condividere .env, perché può contenere secret. Per controllare solo che esista:

ls -la ~/.hermes/.env

Se setup finisce ma ~/.hermes/config.yaml manca o la cartella è vuota, controlla prima il volume mount. Il comando deve includere -v ~/.hermes:/opt/data.

Configurare ChatGPT OAuth

Se il provider non è ancora configurato, apri il selettore modello:

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

Scegli OpenAI Codex o la voce Codex più vicina. Se compare una URL o un device code, aprilo nel browser del Mac e accedi con ChatGPT.

Alcune versioni supportano anche:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth add openai-codex --type oauth

Il token OAuth non dovrebbe restare solo in un container temporaneo. Viene salvato nella cartella montata ~/.hermes, per esempio in un auth store come auth.json. Così puoi ricreare il container senza riconfigurare ogni volta il provider.

Diagramma del login ChatGPT OAuth collegato al container Docker Hermes Agent — ChatGPT OAuth collega OpenAI Codex senza incollare una OpenAI API key nel comando.

Avviare Hermes Agent

Avvia Hermes Agent in modalità interattiva:

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

Se la sessione si apre, l’installazione base funziona. Continua a usare lo stesso volume mount per ogni comando.

Le opzioni principali significano:

Option	Significato
`docker run`	Avvia un nuovo container.
`-it`	Apre una sessione terminale interattiva.
`--rm`	Rimuove il container temporaneo alla chiusura.
`-v ~/.hermes:/opt/data`	Collega la cartella Mac `~/.hermes` a `/opt/data` nel container.
`nousresearch/hermes-agent`	Usa l’immagine Docker ufficiale di Hermes Agent.

Verificare la dashboard su `localhost:9119`

Dopo setup, configurazione provider e avvio interattivo, controlla image e versione:

docker pull nousresearch/hermes-agent:latest
docker run -it --rm nousresearch/hermes-agent:latest version

Per controllare lo stato OAuth, usa la stessa cartella dati:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth list

Per gateway e dashboard in background:

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

Apri http://localhost:9119 o http://127.0.0.1:9119. La dashboard è un’interfaccia locale per impostazioni, sessioni, log e skills.

Se non si apre:

curl -I http://127.0.0.1:9119

I log mostrano i dettagli di runtime:

docker logs --tail 50 hermes

Le righe della dashboard possono iniziare con [dashboard].

Ferma e rimuovi il container in background così:

docker stop hermes
docker rm hermes

Problemi comuni

Sintomo	Controllo
`Cannot connect to the Docker daemon`	Docker Desktop non è avviato.
`docker: command not found`	Il CLI Docker non è disponibile nel Terminale.
URL OAuth non si apre	Copia URL o device code nel browser del Mac.
Provider OpenAI Codex non visibile	Scarica l’ultima immagine Hermes Agent e controlla di nuovo il menu `hermes model`.
Le impostazioni spariscono	Manca o cambia il mount `-v ~/.hermes:/opt/data`.
Permission error	Controlla che l’utente macOS corrente possa scrivere in `~/.hermes`.
Dashboard non si apre	Controlla `-p 9119:9119`, `-e HERMES_DASHBOARD=1` e log `[dashboard]`.
Conflitto porte	Un altro processo usa `8642` o `9119`.

Su Mac Apple Silicon, Docker Desktop di solito gestisce le differenze di architettura se non forzi un’immagine Intel-only. Parti dall’immagine ufficiale latest e da Docker Desktop aggiornato.

Flusso per controllare Docker, OAuth, volume mount, log e dashboard — Controlla Docker, OAuth, volume, log e porta dashboard in questo ordine.

Aggiornare o rimuovere

Per aggiornare:

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
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

Per rimuovere container e immagine:

docker rm -f hermes
docker rmi nousresearch/hermes-agent:latest

Elimina ~/.hermes solo se vuoi cancellare anche impostazioni, token OAuth, sessioni, skills e log.

rm -rf ~/.hermes

In sintesi

La sequenza affidabile è: Docker Desktop, setup, OpenAI Codex con ChatGPT OAuth, mount ~/.hermes:/opt/data e controllo di http://localhost:9119 in modalità gateway.