Eseguire Hermes Agent su Windows con WSL2

Hermes Agent non supporta Windows nativo

Se sei su Windows e stai cercando di installare Hermes Agent, ti scontrerai subito con un ostacolo. La documentazione ufficiale di Hermes lo dice chiaramente: Windows nativo non e supportato. Le piattaforme supportate sono Linux, macOS, WSL2 e Android tramite Termux.

Questo non e un limite destinato a colmarsi presto. Hermes usa strumenti shell, gestione dei processi e convenzioni del filesystem che sono native di Linux. Il percorso corretto su Windows e WSL2, il Windows Subsystem for Linux 2, che ti fornisce un vero kernel Linux in esecuzione all'interno di Windows.

Questa guida illustra la configurazione completa di WSL2 per Hermes Agent e spiega dove emergono le difficolta dopo il primo avvio riuscito.

Cos'e davvero WSL2

WSL2 non e un emulatore ne uno strato di compatibilita. Esegue un vero kernel Linux in una macchina virtuale leggera. Dall'interno di una shell WSL2 hai un ambiente Linux completo: filesystem, tabella dei processi, gestore di pacchetti e rete.

Per Hermes, questo significa che tutto cio che funziona su un server Linux funziona anche in WSL2, con alcune avvertenze su rete e persistenza che vedremo piu avanti.

Microsoft distribuisce WSL2 con Windows 10 moderni (build 1903 e successive) e Windows 11. Se il tuo Windows e ragionevolmente aggiornato, hai gia accesso a questa funzionalita.

Passo 1: abilitare WSL2

Apri PowerShell come Amministratore ed esegui:

wsl --install

Questo comando abilita la funzionalita WSL, installa la distribuzione Linux predefinita (Ubuntu) e imposta WSL2 come versione predefinita. E necessario un riavvio per completare l'operazione.

Se hai gia WSL1 installato e vuoi passare a WSL2:

wsl --set-default-version 2

Poi controlla quale versione sta usando la tua distribuzione:

wsl --list --verbose

Cerca la colonna VERSION. Deve mostrare 2.

Passo 2: configurare Ubuntu in WSL2

Dopo il riavvio, apri Ubuntu dal menu Start. Al primo avvio ti viene chiesto di creare un nome utente Unix e una password. Questo e il tuo utente WSL2, separato dal tuo account Windows.

Aggiorna l'elenco dei pacchetti e aggiorna i pacchetti installati:

sudo apt update && sudo apt upgrade -y

Installa curl e le altre basi di cui Hermes avra bisogno:

sudo apt install -y curl git build-essential

Passo 3: installare Hermes Agent dentro WSL2

Con un ambiente Ubuntu funzionante, installa Hermes usando lo script di installazione ufficiale:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Dopo l'installazione, esegui la configurazione:

hermes setup

Questo ti guida attraverso la scelta del provider, la configurazione del modello e la configurazione opzionale di Telegram. Scegli OpenRouter per il primo avvio piu semplice: dovrai avere pronta una chiave API di OpenRouter.

Dopo aver completato la configurazione, avvia Hermes:

hermes

Se vedi l'interfaccia a terminale, la tua installazione WSL2 funziona correttamente.

Passo 4: configurazione di Telegram in WSL2

Far funzionare Hermes su Telegram dentro WSL2 richiede qualche passaggio in piu rispetto a un server Linux nativo.

Il gateway di messaggistica di Hermes deve rimanere in esecuzione per ricevere i messaggi Telegram. In WSL2, il processo gira finche la sessione WSL2 e aperta. Se chiudi il terminale, il gateway si ferma e i messaggi Telegram non verranno consegnati.

Per tenere il gateway in esecuzione in background:

hermes gateway start --detach

Verifica che sia in esecuzione:

hermes gateway status

Se vuoi che il gateway si avvii automaticamente all'apertura di WSL2, puoi aggiungerlo al tuo ~/.bashrc oppure configurare un servizio systemd (WSL2 supporta systemd nelle versioni recenti su Windows 11).

Limitazioni note di WSL2 per Hermes

Memoria e stato non sopravvivono agli spegnimenti di WSL2. Per impostazione predefinita, WSL2 termina quando chiudi l'ultima sessione. I processi in esecuzione si fermano. Se Hermes sta ricevendo messaggi Telegram o eseguendo attivita programmate, verranno interrotti. Dovrai riavviare Hermes e il gateway ogni volta che WSL2 si avvia.

La rete e in bridge, non nativa. WSL2 crea un adattatore di rete virtuale. La tua istanza Hermes non ha un indirizzo IP stabile dal punto di vista di Internet. Questo e rilevante se stai costruendo integrazioni che devono ricevere traffico webhook, ma non influisce sulle chiamate in uscita verso Telegram o le API dei modelli.

Attriti con i percorsi dei file. WSL2 ha il proprio filesystem Linux (\\wsl$\Ubuntu\home\... su Windows). Se vuoi condividere file tra WSL2 e le applicazioni Windows, puoi montare percorsi Windows dentro WSL2 (/mnt/c/...). I file di memoria e la configurazione di Hermes si trovano di default nella home directory di WSL2, il che significa che non sono direttamente accessibili da Esplora file di Windows senza usare il percorso di rete.

Prestazioni sui percorsi Windows. Se salvi i file di Hermes sul filesystem Windows (sotto /mnt/c/), le operazioni sui file saranno piu lente rispetto al filesystem WSL2. Mantieni i dati di Hermes nella home directory Linux per prestazioni migliori.

Richiede di tenere WSL2 aperto. Affinche Hermes sia continuamente disponibile su Telegram, il tuo terminale WSL2 deve rimanere in esecuzione. Questo e il principale vincolo operativo per gli utenti Windows che vogliono un agente sempre attivo.

Quando il managed hosting e la scelta migliore per gli utenti Windows

Per la maggior parte degli utenti Windows, WSL2 funziona abbastanza bene per valutazione e apprendimento. I problemi emergono quando si vuole una disponibilita persistente e sempre attiva di Hermes.

WSL2 e uno strumento per sviluppatori, non un server. Tenerlo in esecuzione in modo continuativo significa che il tuo PC Windows deve restare acceso, la sessione WSL2 non deve chiudersi, e sei tu a dover gestire i riavvii quando gli aggiornamenti di Windows forzano un reboot.

Se vuoi Hermes disponibile su Telegram 24 ore su 24 senza che la tua macchina locale sia in funzione, hai due opzioni:

1. Affittare un VPS Linux ed eseguire Hermes li invece che in locale.
2. Usare il managed hosting come Hermify, dove il runtime risiede su un server persistente e ci interagisci tramite Telegram e la dashboard.

La seconda opzione non richiede alcuna conoscenza di Linux, nessuna gestione di VPS, e funziona da Windows senza WSL2 del tutto. Non installi nulla in locale: Hermify gestisce il runtime al posto tuo. Il bot Telegram rimane disponibile perche gira su un vero server, non sul tuo portatile.

Questo e il percorso che segue la maggior parte degli utenti Windows quando supera la fase di valutazione e vuole Hermes come assistente quotidiano reale.

Schema decisionale pratico

WSL2 non e lo strumento sbagliato: e quello giusto per lo sviluppo. Per un utilizzo persistente in produzione, un runtime lato server e piu affidabile. Puoi esplorare come il managed hosting di Hermes si confronta con una configurazione self-hosted su VPS se vuoi valutare le opzioni affiancate.