Self-hosting Hermes Agent su VPS: guida passo passo

Hermes Agent gira in locale sulla maggior parte delle macchine di sviluppo. Ma locale significa offline quando il laptop va in sleep, niente accesso da telefono e nessun workspace persistente. Spostarlo su un VPS risolve tutti e tre i problemi: l'agent gira 24/7, puoi inviargli messaggi da Telegram e mantiene memoria e skill tra una sessione e l'altra.

Questa guida ti accompagna nel deploy di Hermes Agent su un VPS partendo da zero. Installerai il software, collegherai un provider LLM, eseguirai i comandi terminale in sandbox Docker, collegherai Telegram e farai girare il tutto come servizio systemd che sopravvive ai riavvii. Ogni comando e stato testato su un VPS Ubuntu 24.04 con 4 vCPU e 8 GB di RAM.

Self-hosting di agent AI su un VPS

Cos'e Hermes Agent e perche farne il self-hosting?

Hermes Agent e un agent AI open-source sviluppato da Nous Research. Si connette a provider LLM (OpenRouter, Anthropic, Ollama e altri), esegue comandi terminale, naviga il web e ricorda quello che impara tra le sessioni. Salva memorie persistenti, costruisce skill riutilizzabili dai task che completa e supporta gateway di messaggistica per comunicare via Telegram, Discord, Slack, WhatsApp o Signal.

Fare self-hosting significa che i tuoi prompt e dati restano sul tuo server. Nessuna piattaforma agent di terze parti vede le tue conversazioni. L'agent gira in modo continuo, costruisce contesto nel tempo e costa solo l'hosting del VPS piu le chiamate API LLM che fai. Su un VPS da 5-10 EUR/mese con OpenRouter, la maggior parte degli sviluppatori spende meno di 20 EUR/mese in totale.

Di cosa ha bisogno Hermes Agent per girare su un VPS?

Hermes Agent richiede un server Linux con almeno 2 GB di RAM, 10 GB di spazio disco libero e Git installato. Docker e necessario se vuoi l'esecuzione terminale in sandbox (e la vuoi). L'installer gestisce Python 3.11+ e Node.js automaticamente.

Requisito	Minimo	Consigliato
OS	Ubuntu 22.04 / Debian 12	Ubuntu 24.04
RAM	2 GB	4 GB+
Disco	10 GB liberi	20 GB+ (immagini Docker)
CPU	1 vCPU	2+ vCPU
Prerequisiti	Git	Git, Docker
Rete	HTTPS in uscita	HTTPS in uscita

L'agent in se e leggero. La maggior parte della RAM va ai container Docker durante l'esecuzione dei comandi. Se prevedi di eseguire sessioni concorrenti multiple attraverso il gateway di messaggistica, punta ad almeno 4 GB.

Prerequisiti

Prima di installare Hermes Agent, configura un utente non-root e un firewall di base. Se hai gia un VPS messo in sicurezza, vai direttamente alla sezione installazione.

Creare un utente dedicato

Connettiti al server via SSH come root e crea un utente per Hermes:

adduser hermes --disabled-password --gecos ""
usermod -aG sudo hermes

Assegna a questo utente sudo senza password (necessario per Docker e la gestione dei servizi):

echo "hermes ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/hermes
chmod 440 /etc/sudoers.d/hermes

Copia la tua chiave SSH per poter accedere con questo utente:

mkdir -p /home/hermes/.ssh
cp ~/.ssh/authorized_keys /home/hermes/.ssh/
chown -R hermes:hermes /home/hermes/.ssh
chmod 700 /home/hermes/.ssh
chmod 600 /home/hermes/.ssh/authorized_keys

Da questo momento, lavora come utente hermes:

su - hermes

Installare Docker

Hermes Agent usa Docker per isolare i comandi terminale in sandbox. Installalo dal repository ufficiale Docker:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin

Aggiungi l'utente hermes al gruppo docker per poter eseguire container senza sudo:

sudo usermod -aG docker hermes
newgrp docker

Verifica che Docker funzioni:

docker run --rm hello-world

Dovresti vedere "Hello from Docker!" nell'output. Questo conferma che Docker riesce a scaricare immagini e avviare container.

Configurare il firewall

Installa UFW e configuralo per permettere solo SSH e bloccare tutto il resto per default:

sudo apt-get install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw --force enable

Verifica le regole:

sudo ufw status verbose

L'output dovrebbe mostrare SSH consentito e tutto il resto del traffico in ingresso negato. Il gateway Hermes fa connessioni in uscita verso l'API di Telegram, quindi non serve aprire porte in ingresso per la messaggistica.

Come installare Hermes Agent su Ubuntu?

Hermes Agent si installa con un singolo comando che gestisce Python, Node.js e tutte le dipendenze. Eseguilo come utente hermes, non come root.

Prima, verifica lo script di installazione prima di passarlo a bash. Scaricalo, controllalo, poi eseguilo:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o /tmp/hermes-install.sh
less /tmp/hermes-install.sh

Esamina lo script. Installa Python 3.11+ via uv, Node.js e il CLI hermes. Quando sei soddisfatto:

bash /tmp/hermes-install.sh

Ricarica la shell per rendere disponibile il comando hermes:

source ~/.bashrc

Verifica l'installazione:

hermes --version

Dovresti vedere la versione e le informazioni sull'ambiente:

Hermes Agent v0.4.0 (2026.3.18)
Project: /home/hermes/.hermes/hermes-agent
Python: 3.11.15
...

Esegui lo strumento diagnostico per controllare le dipendenze mancanti:

hermes doctor

Cerca i segni di spunta verdi nell'output. Gli avvisi sulle chiavi API non configurate (OpenRouter, Browserbase, ecc.) sono normali a questo punto. Configurerai il provider LLM nel prossimo passo. Le voci rosse relative a Python, Git o Docker vanno risolte prima di continuare.

Come configurare il provider LLM?

Hermes Agent ha bisogno di un provider LLM per funzionare. Non include un modello. Colleghi un'API di un provider e paghi per token. OpenRouter ti da accesso a oltre 200 modelli con una singola chiave API ed e il modo piu veloce per iniziare.

Opzione 1: OpenRouter (consigliato per iniziare)

Crea un account su openrouter.ai e genera una chiave API.

L'installer ha creato ~/.hermes/.env con un template completo. Prima, restringi i permessi:

chmod 600 ~/.hermes/.env

Apri il file e imposta la tua chiave API sulla riga OPENROUTER_API_KEY=:

nano ~/.hermes/.env

Trova la riga OPENROUTER_API_KEY= e aggiungi la tua chiave dopo il segno =. Salva ed esci (Ctrl+X, poi Y, poi Enter).

Imposta il modello di default:

hermes config set model.provider openrouter
hermes config set model.default anthropic/claude-sonnet-4

Verifica che il file non sia leggibile da altri utenti:

ls -la ~/.hermes/.env

I permessi dovrebbero mostrare -rw------- (600). Solo l'utente hermes puo leggere questo file.

Opzione 2: Endpoint custom compatibile OpenAI

Se gestisci il tuo server di inferenza (Ollama, vLLM, llama.cpp) o usi un altro provider:

echo 'OPENAI_BASE_URL=http://localhost:11434/v1' >> ~/.hermes/.env
echo 'OPENAI_API_KEY=ollama' >> ~/.hermes/.env
echo 'LLM_MODEL=llama3.1:70b' >> ~/.hermes/.env

Confronto provider LLM

Provider	Variabile d'ambiente	Costo	Note
OpenRouter	`OPENROUTER_API_KEY`	Per-token, varia per modello	200+ modelli, singola chiave
Anthropic	`ANTHROPIC_API_KEY`	Per-token	Accesso diretto a Claude
Ollama (locale)	`OPENAI_BASE_URL` + `OPENAI_API_KEY`	Gratuito (self-hosted)	Serve un VPS con GPU per buone prestazioni
vLLM	`OPENAI_BASE_URL` + `OPENAI_API_KEY`	Gratuito (self-hosted)	GPU necessaria

Verifica che la connessione LLM funzioni:

hermes -m "What is 2+2? Reply with just the number."

Se ricevi una risposta, il provider e configurato correttamente. Se vedi un errore di autenticazione, ricontrolla la chiave API in ~/.hermes/.env.

Come isolare Hermes Agent con Docker?

Per default, Hermes Agent esegue i comandi terminale direttamente sull'host. Su un VPS, questo e un rischio di sicurezza. Se il LLM genera un comando distruttivo, viene eseguito sul tuo server reale. Il sandboxing Docker isola tutta l'esecuzione dei comandi dentro un container.

Imposta Docker come backend terminale:

hermes config set terminal.backend docker

Configura l'immagine Docker e i limiti di risorse in ~/.hermes/config.yaml:

hermes config set terminal.docker_image "nikolaik/python-nodejs:python3.11-nodejs20"
hermes config set terminal.container_cpu 1
hermes config set terminal.container_memory 2048
hermes config set terminal.container_persistent true

Cosa fanno queste impostazioni:

docker_image: L'immagine base per la sandbox. Questa include Python e Node.js, coprendo la maggior parte dei task da sviluppatore.
container_cpu: Limita il container a 1 core CPU. Impedisce a un processo fuori controllo di prosciugare il VPS.
container_memory: Limite di 2048 MB di RAM per il container. Aumenta se lavori con dataset di grandi dimensioni.
container_persistent: Mantiene il container tra un comando e l'altro. Esecuzione piu veloce perche salta l'avvio del container ogni volta.

Verifica che il backend sia impostato:

hermes config

Nella sezione Terminal, dovresti vedere Backend: docker.

Confronto backend terminale

Backend	Sicurezza	Velocita	Caso d'uso
`local`	Nessuna. I comandi girano sull'host	Piu veloce	Solo sviluppo locale. Mai su un VPS
`docker`	Isolamento container	Piccolo overhead di avvio	Deploy su VPS (consigliato)
`ssh`	Isolamento di rete	Latenza di rete	Esecuzione su un server diverso

Configurare la modalita di approvazione

Hermes Agent ha un sistema di approvazione integrato che chiede conferma prima di eseguire comandi potenzialmente pericolosi. Su un server, tienilo attivo:

hermes config set approval_mode ask

Le tre modalita:

ask: Chiede conferma prima di qualsiasi comando che modifica file, installa pacchetti o tocca la rete. Usa questa.
smart: Un modello AI valuta il rischio e chiede conferma solo per comandi realmente pericolosi. Piu veloce, ma si basa sul giudizio dell'AI.
off: Nessun controllo. Ogni comando viene eseguito immediatamente. Non usarla su un server.

Come collegare Hermes Agent a Telegram?

Il gateway di messaggistica ti permette di chattare con Hermes dal telefono. Telegram e la configurazione piu comune. Il gateway fa connessioni in uscita verso l'API di Telegram, quindi non serve aprire porte in ingresso sul firewall.

Passo 1: Creare un bot Telegram

Apri Telegram e scrivi a @BotFather. Invia questi comandi:

/newbot
Inserisci un nome per il tuo bot (es. "My Hermes Agent")
Inserisci un username (deve terminare con bot, es. myhermes_agent_bot)

BotFather risponde con un token per il bot. Ha questo formato: 7123456789:AAHx.... Copialo.

Passo 2: Ottenere il tuo Telegram user ID

Scrivi a @userinfobot su Telegram. Risponde con il tuo user ID numerico. Copia questo numero.

Passo 3: Configurare il gateway

Aggiungi il token del bot e il tuo user ID al file di ambiente:

echo 'TELEGRAM_BOT_TOKEN=7123456789:AAHxYourTokenHere' >> ~/.hermes/.env
echo 'TELEGRAM_ALLOWED_USERS=your_numeric_user_id' >> ~/.hermes/.env

La variabile TELEGRAM_ALLOWED_USERS e un controllo di sicurezza. Solo gli user ID elencati qui possono interagire con il tuo bot. Senza di essa, chiunque trovi il tuo bot puo inviargli comandi. Separa piu ID con virgole.

Passo 4: Testare il gateway

Avvia il gateway in primo piano per verificare che si connetta:

hermes gateway

Invia un messaggio al tuo bot su Telegram. Dovresti vedere il messaggio apparire nel terminale e una risposta inviata indietro. Premi Ctrl+C per fermare il gateway dopo aver confermato che funziona.

Se il bot non risponde, controlla:

Il token del bot e corretto in ~/.hermes/.env
Il tuo user ID e presente in TELEGRAM_ALLOWED_USERS
Il VPS riesce a raggiungere api.telegram.org sulla porta 443 (HTTPS in uscita)

Altre piattaforme supportate includono Discord, Slack, WhatsApp, Signal e Email. Esegui hermes gateway setup per un wizard interattivo che configura qualsiasi di esse.

Come eseguire Hermes Agent come servizio systemd?

Eseguire hermes gateway in una sessione terminale significa che si ferma quando ti disconnetti. Un servizio systemd utente mantiene il gateway attivo dopo il logout e lo riavvia automaticamente se crasha o il server viene riavviato.

Installare il servizio

Hermes fornisce un comando integrato per installare il gateway come servizio systemd utente:

hermes gateway install

Questo crea un file di servizio in ~/.config/systemd/user/hermes-gateway.service e abilita il lingering automaticamente. Il lingering mantiene i servizi utente in esecuzione dopo che ti disconnetti da SSH. Senza di esso, systemd fermerebbe il gateway alla fine della sessione.

Avvia il servizio e abilitalo all'avvio:

systemctl --user enable --now hermes-gateway

enable lo fa partire al boot. Il flag --now lo avvia immediatamente. Usa sempre entrambi insieme.

Verifica che il servizio sia in esecuzione:

systemctl --user status hermes-gateway

Cerca Active: active (running) nell'output. Se dice failed, controlla i log.

Controllare i log

Visualizza i log del gateway in tempo reale:

journalctl --user -u hermes-gateway -f

Premi Ctrl+C per smettere di seguirli. I log del gateway mostrano ogni messaggio in arrivo, chiamata LLM e esecuzione di tool.

Impostare la directory di lavoro

Per default, il gateway usa la home directory come workspace. Imposta una directory di progetto dedicata:

echo 'MESSAGING_CWD=/home/hermes/projects' >> ~/.hermes/.env
mkdir -p /home/hermes/projects

Riavvia il servizio per applicare:

systemctl --user restart hermes-gateway

Come fare il backup dei dati di Hermes Agent?

Hermes salva tutto il suo stato in ~/.hermes/. Questa directory contiene memorie, skill apprese, cronologia delle sessioni, configurazione e cron job. Perderla significa che l'agent dimentica tutto.

Percorsi principali:

Percorso	Contenuto
`~/.hermes/config.yaml`	Configurazione
`~/.hermes/.env`	Chiavi API e secret
`~/.hermes/memories/`	Memorie persistenti dell'agent
`~/.hermes/skills/`	Skill riutilizzabili create dall'agent
`~/.hermes/sessions/`	Cronologia sessioni gateway
`~/.hermes/cron/`	Job schedulati
`~/.hermes/SOUL.md`	Identita/persona dell'agent

Crea uno script di backup:

cat > /home/hermes/backup-hermes.sh << 'SCRIPT'
#!/bin/bash
BACKUP_DIR="/home/hermes/backups"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"
tar czf "$BACKUP_DIR/hermes-$TIMESTAMP.tar.gz" \
  --exclude='*.log' \
  -C /home/hermes .hermes/
# Keep only the last 7 backups
ls -t "$BACKUP_DIR"/hermes-*.tar.gz | tail -n +8 | xargs -r rm
echo "Backup saved: $BACKUP_DIR/hermes-$TIMESTAMP.tar.gz"
SCRIPT
chmod 700 /home/hermes/backup-hermes.sh

Eseguilo giornalmente con un cron job:

(crontab -l 2>/dev/null; echo "0 3 * * * /home/hermes/backup-hermes.sh") | crontab -

Verifica la voce cron:

crontab -l

Dovresti vedere il job di backup schedulato alle 03:00 ogni giorno. Lo script conserva 7 giorni di backup e rimuove quelli piu vecchi.

Per backup fuori dal server, usa rsync per copiare la directory di backup su un'altra macchina o su object storage. Tenere i backup solo sullo stesso VPS non protegge da guasti del disco.

Come aggiornare Hermes Agent?

Hermes Agent include un comando di aggiornamento integrato. Prima di aggiornare, fai il backup dei dati.

/home/hermes/backup-hermes.sh
hermes update

Verifica la nuova versione:

hermes --version

Controlla se ci sono modifiche alla configurazione necessarie dopo l'aggiornamento:

hermes config migrate
hermes doctor

config migrate aggiunge nuove opzioni di configurazione con i loro valori di default. hermes doctor verifica che tutto funzioni ancora dopo l'aggiornamento.

Riavvia il servizio gateway per eseguire la nuova versione:

systemctl --user restart hermes-gateway
systemctl --user status hermes-gateway

Se qualcosa si rompe dopo un aggiornamento, ripristina dal backup:

systemctl --user stop hermes-gateway
tar xzf /home/hermes/backups/hermes-YYYYMMDD-HHMMSS.tar.gz -C /home/hermes/
systemctl --user start hermes-gateway

Checklist di hardening della sicurezza

Un agent AI su VPS che esegue comandi terminale richiede attenzione alla sicurezza. Ecco un riepilogo di quello che questa guida ha gia configurato e alcuni passi aggiuntivi.

Gia configurato in questa guida:

Utente non-root (hermes) con home directory dedicata
Sandboxing Docker per tutta l'esecuzione dei comandi terminale
Firewall UFW che nega tutto il traffico in ingresso tranne SSH
Chiavi API in ~/.hermes/.env con permessi 600
TELEGRAM_ALLOWED_USERS che restringe l'accesso al bot al tuo user ID
approval_mode: ask che richiede conferma per comandi pericolosi

Hardening aggiuntivo:

Disabilita completamente il backend terminale locale verificando la configurazione:

hermes config

Nella sezione Terminal, conferma che Backend dica docker, non local.

Imposta limiti di risorse sui container Docker per impedire a un processo fuori controllo di consumare tutte le risorse del server. Questo e stato configurato in precedenza con container_cpu e container_memory.

Controlla periodicamente le skill apprese dall'agent:

ls -la ~/.hermes/skills/

Le skill sono script che l'agent scrive e riutilizza. Verificale come faresti con qualsiasi codice in esecuzione sul tuo server.

Monitora i log del gateway per utenti inaspettati o attivita insolite:

journalctl --user -u hermes-gateway --since "1 hour ago" --no-pager

Risoluzione dei problemi

Il gateway non si avvia:

journalctl --user -u hermes-gateway -n 50 --no-pager

Cause comuni: token del bot non valido, chiave API mancante, Docker non in esecuzione. Verifica che Docker sia attivo con systemctl status docker.

Il bot Telegram non risponde:

Verifica che il token del bot e gli utenti autorizzati siano impostati:

grep TELEGRAM ~/.hermes/.env

Testa la connettivita in uscita:

curl -s https://api.telegram.org/bot<YOUR_TOKEN>/getMe

Una risposta valida con le informazioni del tuo bot conferma che token e rete funzionano.

Permesso negato per Docker:

groups

L'output deve includere docker. Se non c'e, riesegui sudo usermod -aG docker hermes e disconnettiti/riconnettiti.

Comando hermes non trovato dopo l'installazione:

source ~/.bashrc

Se ancora non funziona, controlla se ~/.local/bin e nel tuo PATH:

echo $PATH | tr ':' '\n' | grep local

Utilizzo elevato della memoria:

Controlla il consumo di risorse dei container Docker:

docker stats --no-stream

Abbassa l'impostazione container_memory se i container usano troppa RAM.

Stima dei costi

Il self-hosting di Hermes Agent su un VPS costa il server piu l'utilizzo dell'API LLM. Ecco una stima realistica per uno sviluppatore singolo.

Voce	Costo mensile
VPS (2 vCPU, 4 GB RAM)	5-10 EUR
API OpenRouter (uso moderato, ~500K token/giorno)	5-15 EUR
Overhead Docker	Incluso nel VPS
Gateway Telegram	Gratuito
Totale	10-25 EUR/mese

Gli abbonamenti ad assistenti AI gestiti costano 20-200 EUR/mese. Il self-hosting costa meno e tiene i tuoi dati sul tuo server.

Eseguire Claude Code su un VPS

Copyright 2026 Virtua.Cloud. Tutti i diritti riservati. Questo contenuto e un'opera originale del team Virtua.Cloud. La riproduzione, ripubblicazione o redistribuzione senza autorizzazione scritta e vietata.