Agente Hermes: configurazione di server headless e desktop remoto

L’esecuzione di Hermes Agent su un server headless, connesso da un client desktop su un’altra macchina, richiede due processi sul server e una singola connessione client.

L’architettura separa il backend di Hermes in due processi lato server e un’interfaccia lato client. Il backend hermes serve gestisce le connessioni API e della dashboard, mentre il processo hermes gateway run gestisce in modo indipendente i canali di messaggistica. Il client desktop si connette al backend serve, non al gateway.

Due processi sul server, un’applicazione sul client. Entrambi i processi del server condividono la stessa configurazione ~/.hermes/, le competenze (skills), la memoria e le sessioni. I job Cron vengono eseguiti sul server dove è in esecuzione il gateway.

Per l’installazione, la configurazione del provider e la configurazione iniziale, iniziare con Hermes AI Assistant — Installazione, Configurazione, Flusso di Lavoro e Risoluzione dei Problemi.

Configurare il server headless

1. Configurare l’autenticazione

L’autenticazione di base (basic auth) offre una protezione sufficiente per una LAN fidata. Aggiungere le credenziali al file di ambiente:

cat >> ~/.hermes/.env << 'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=scegli-una-password-forte
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

Il file .env risiede accanto a config.yaml nella directory ~/.hermes/. Hermes risolve la configurazione con le sovrascritture della riga di comando per prime, poi config.yaml, poi .env e infine i valori predefiniti integrati. I segreti (secrets) devono essere salvati in .env.

2. Avviare il backend

Eseguire il backend serve su tutte le interfacce:

hermes serve --host 0.0.0.0 --port 9119

Il backend ascolta sulla porta 9119 e accetta connessioni WebSocket dal client desktop. Verificare che sia in esecuzione con un rapido controllo dello stato:

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'
# Risultato atteso: true  "basic"

3. Eseguire come servizio systemd

Per un server persistente che sopravviva ai riavvii, installare un servizio systemd a livello utente. Creare il file unit in /etc/systemd/user/hermes-serve.service:

[Unit]
Description=Hermes Agent Serve Backend

[Service]
EnvironmentFile=%h/.hermes/.env
ExecStart=/home/rg/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main serve --host 0.0.0.0 --port 9119
Restart=on-failure

[Install]
WantedBy=default.target

Ricaricare il demone, abilitare il servizio e avviarlo:

systemctl --user daemon-reload
systemctl --user enable hermes-serve
systemctl --user start hermes-serve

Controllare lo stato del servizio:

systemctl --user status hermes-serve

4. Avviare il gateway

Il gateway è un processo separato che gestisce i canali di messaggistica — Telegram, Discord, Slack e altri. Avviarlo in modo indipendente:

hermes gateway run

Il gateway e il backend serve sono due processi separati. Il gateway gestisce le sessioni, esegue i job cron e instrada i messaggi. Il backend serve fornisce l’interfaccia API per le connessioni desktop e della dashboard web. Condividono la stessa directory home ma funzionano in modo indipendente.

Per l’elenco completo dei comandi e delle sottocomandi del gateway, vedere il Foglio di riferimento della CLI di Hermes Agent. Se l’interfaccia principale è il messaggistica mobile, abbinare questa configurazione con Controllo Vocale Hermes dal Telefono per flussi di lavoro incentrati sulla voce sopra lo stesso processo gateway.

5. Verificare il backend

Confermare che il backend risponda e che l’autenticazione sia attiva:

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'

Output atteso:

true
"basic"

Se l’autenticazione non è abilitata, la risposta mostrerà false per auth_required. Verificare che il file .env contenga le variabili corrette e che il servizio sia stato riavviato dopo le modifiche alla configurazione.

Connettersi dal client desktop

Opzione A: App Hermes Desktop

Installare Hermes Desktop dal sito ufficiale. Avviare l’app, navigare verso Impostazioni → Gateway → Gateway remoto e inserire l’indirizzo del server:

http://<ip-server>:9119

Accedere con il nome utente e la password configurati sul server.

In alternativa, impostare l’URL remoto tramite variabile d’ambiente:

HERMES_DESKTOP_REMOTE_URL=http://<ip-server>:9119 hermes desktop

Opzione B: Dashboard web

Aprire http://<ip-server>:9119 in un browser e accedere con le credenziali di autenticazione di base. La dashboard web fornisce un’interfaccia basata sul browser al backend di Hermes senza richiedere l’installazione del desktop.

Opzione C: CLI

Dal terminale del PC desktop, configurare l’URL remoto tramite le impostazioni dell’app desktop o la variabile d’ambiente HERMES_DESKTOP_REMOTE_URL. La superficie CLI si connette attraverso lo stesso canale WebSocket dell’app desktop.

Considerazioni su rete e sicurezza

Per una rete locale fidata, l’autenticazione di base su 0.0.0.0 è sufficiente. Se il server è esposto a Internet, utilizzare Tailscale per collegarsi all’IP di Tailscale invece di 0.0.0.0, o configurare un provider OAuth per un’autenticazione più forte. Aprire sempre la porta 9119 TCP nel firewall del server quando il backend deve accettare connessioni esterne.

Importanti distinzioni tra i processi

Comprendere la separazione tra i due processi del server previene errori di configurazione comuni:

• hermes serve — Il backend a cui si connettono l’app desktop e la dashboard web. Gestisce l’interfaccia API e le connessioni WebSocket.
• hermes gateway run — Il processo che gestisce Telegram, Discord, Slack e altri canali di messaggistica. Gestisce le sessioni, esegue i job cron e instrada i messaggi.
• Questi sono due processi separati sul server. Condividono la configurazione ~/.hermes/, le competenze, la memoria e le sessioni, ma funzionano in modo indipendente.
• I job Cron vengono eseguiti sul server dove è in esecuzione il gateway.
• Profili, competenze e memoria sono configurati lato server. Il client si connette al backend già configurato.

Per una configurazione incentrata sui profili e competenze ottimizzate per diversi ruoli di produzione, vedere Competenze di Hermes AI Assistant per Configurazioni di Produzione Reali.

Risoluzione dei problemi

Il desktop non riesce a connettersi al server

1. Verificare che il backend sia in esecuzione: systemctl --user status hermes-serve
2. Controllare che la porta sia aperta: ss -tlnp | grep 9119
3. Testare dal server: curl -s http://localhost:9119/api/status
4. Testare dalla macchina client: curl -s http://<ip-server>:9119/api/status
5. Se il test dal client fallisce, controllare le regole del firewall: sudo ufw status o sudo iptables -L

Autenticazione non riuscita

1. Confermare che il file .env abbia i permessi corretti: ls -la ~/.hermes/.env (dovrebbe essere 600)
2. Verificare che il segreto sia stato generato: grep HERMES_DASHBOARD_BASIC_AUTH_SECRET ~/.hermes/.env
3. Riavviare il servizio dopo le modifiche alla configurazione: systemctl --user restart hermes-serve

Il gateway non risponde ai messaggi

Il gateway è un processo separato dal backend. Se il desktop si connette ma le piattaforme di messaggistica non funzionano:

1. Controllare lo stato del gateway: hermes gateway status
2. Avviare il gateway se è fermo: hermes gateway start
3. Rivedere i log: hermes logs gateway -f

Riferimenti

• Documentazione dell’App Desktop Hermes Agent
• Guida alla Configurazione di Hermes Agent
• Gateway di Messaggistica di Hermes Agent
• Hermes AI Assistant — Installazione, Configurazione, Flusso di Lavoro e Risoluzione dei Problemi
• Foglio di riferimento della CLI di Hermes Agent — comandi, flag e scorciatoie slash
• Competenze di Hermes AI Assistant per Configurazioni di Produzione Reali

Questo articolo fa parte del cluster Sistemi AI, che copre assistenti self-hosted, architettura di recupero, infrastruttura LLM locale e osservabilità.