Come distribuire Hermes Agent su Signal (signal-cli)

Perché usare Hermes Agent su Signal

Se il tuo modello di minaccia mette i metadati al primo posto, Signal è il messenger di cui ti fidi già. La crittografia end-to-end è attiva di default, il server non conserva quasi nulla oltre a un numero di telefono e a un timestamp dell'ultima connessione, e il protocollo stesso è open source. Mettere il tuo agente AI sulla stessa superficie mantiene ogni prompt, ogni risposta e ogni file che gli affidi dentro quella stessa busta.

Hermes Agent supporta Signal nativamente tramite signal-cli, un daemon non ufficiale ma ben mantenuto che parla il protocollo Signal per tuo conto. Il gateway di Hermes comunica con signal-cli via HTTP usando JSON-RPC per le azioni in uscita e Server-Sent Events per il flusso in entrata, così l'intero runtime può girare su un VPS da $5, sul tuo laptop o su un Raspberry Pi dietro un NAT e inviare e ricevere comunque in tempo reale.

Questa guida ti accompagna nell'intera configurazione: l'installazione di signal-cli, il collegamento al tuo account Signal come dispositivo secondario, l'avvio del daemon HTTP, il collegamento al runtime di Hermes e le insidie che bloccano chi installa per la prima volta. Se hai già messo online Hermes su una superficie più pubblica, la guida pratica alla configurazione di Slack e la guida alla consegna su Telegram coprono lo stesso lato dello stack e vale la pena tenerle affiancate.

Cosa ti serve prima di iniziare

Una distribuzione Signal pulita richiede cinque cose sull'host:

Un'installazione funzionante di Hermes Agent. La guida a Hermes Agent con Docker è il punto di partenza più pulito se non ne hai già una.
Una chiave di un provider di modelli. Anthropic, OpenAI, OpenRouter e qualsiasi endpoint compatibile con OpenAI funzionano. Il runtime la usa per rispondere effettivamente ai messaggi.
Un account Signal già attivato su un dispositivo principale (il tuo telefono). signal-cli si collega come dispositivo secondario, allo stesso modo di Signal Desktop: non registra un nuovo account.
Java Runtime Environment 21 o più recente. Il jar di signal-cli non si avvia su JRE 17 nelle build attuali. Il binario nativo GraalVM elimina questo requisito se preferisci un singolo eseguibile.
Circa 20 minuti per la prima installazione. Le ridistribuzioni successive richiedono meno di un minuto.

Il numero di telefono che usi non deve essere per forza quello del tuo telefono di uso quotidiano. Molti self-hoster dedicano un secondo numero (una eSIM economica, un numero Twilio o una linea Google Voice che accetta SMS) così l'account del bot resta separato a livello operativo.

Passo 1 - Installa signal-cli sul tuo host

Su Debian o Ubuntu, installa Java e scarica l'ultima release di signal-cli:

sudo apt update
sudo apt install -y curl openjdk-21-jre
VERSION=$(curl -s https://api.github.com/repos/AsamK/signal-cli/releases/latest | jq -r .tag_name | sed 's/^v//')
curl -L -o /tmp/signal-cli.tar.gz \
  "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux.tar.gz"
sudo tar -xf /tmp/signal-cli.tar.gz -C /opt
sudo ln -sf "/opt/signal-cli-${VERSION}/bin/signal-cli" /usr/local/bin/signal-cli
signal-cli --version

Se preferisci un singolo binario statico senza dipendenza dal JRE, la build nativa GraalVM dalla pagina delle release del progetto è un sostituto immediato ed evita del tutto la trafila degli aggiornamenti di Java.

Passo 2 - Collega signal-cli al tuo account Signal

signal-cli si unisce al tuo account come dispositivo collegato, esattamente come Signal Desktop. Genera un URL di provisioning e fai stampare al daemon un codice QR:

signal-cli link -n "hermes-agent"

Il comando stampa un URL sgnl://linkdevice?... e un codice QR nel terminale. Sul tuo telefono, apri Signal, vai su Impostazioni -> Dispositivi collegati -> Collega nuovo dispositivo e scansiona il QR. Nel giro di pochi secondi il terminale stampa qualcosa come:

Associated with: +12025550123

Quel numero in formato E.164 è il tuo valore SIGNAL_ACCOUNT per il resto della configurazione. Lo stato su disco dell'identità collegata risiede in ~/.local/share/signal-cli/. Fai un backup di quella directory prima di distruggere l'host: è l'unico posto in cui sono memorizzate le chiavi del dispositivo collegato, e ricollegare da zero invalida la cronologia dei messaggi in sospeso.

Passo 3 - Avvia il daemon HTTP di signal-cli

Il gateway di Hermes comunica con signal-cli via HTTP, quindi il daemon deve girare in modalità HTTP associato a una porta accessibile solo in locale:

signal-cli -a +12025550123 daemon --http 127.0.0.1:8080

Il flag --http espone un endpoint JSON-RPC per l'invio e un flusso Server-Sent Events per la ricezione. Associalo a 127.0.0.1 e a nient'altro; il daemon non esegue alcuna autenticazione propria, quindi qualsiasi processo che riesce a raggiungere la porta può inviare messaggi come te. Se il gateway gira in Docker sullo stesso host, host.docker.internal:8080 o una rete Docker condivisa funzionano senza esporre la porta alla LAN.

Per distribuzioni di lunga durata, predisponi una unit systemd così il daemon si riavvia al reboot. Il wiki di signal-cli ha un template di unit pronto all'uso; gli unici campi da compilare sono il numero dell'account e l'indirizzo di bind.

Un terminale diviso che mostra i log del daemon signal-cli a sinistra e i log del gateway di Hermes a destra, entrambi connessi tramite localhost:8080

Passo 4 - Configura il runtime di Hermes

Apri ~/.hermes/.env (o qualunque file .env legga il tuo container) e aggiungi:

SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+12025550123
SIGNAL_ALLOWED_USERS=+34611222333,+12025557788
SIGNAL_GROUP_ALLOWED_USERS=group.abc123==
SIGNAL_HOME_CHANNEL=+34611222333

Una nota su ciascuno:

SIGNAL_HTTP_URL - l'endpoint del daemon locale dal Passo 3. Sempre http://, sempre loopback o una rete privata.
SIGNAL_ACCOUNT - il numero E.164 dell'identità Signal collegata. Deve corrispondere esattamente a ciò che signal-cli link ha riportato.
SIGNAL_ALLOWED_USERS - numeri E.164 o UUID Signal separati da virgola autorizzati a parlare con il bot. Senza questo impostato (e senza l'abbinamento via DM), il gateway nega ogni messaggio in entrata come impostazione predefinita sicura. È il singolo controllo di sicurezza più importante di tutto lo stack.
SIGNAL_GROUP_ALLOWED_USERS (opzionale) - ID di gruppo separati da virgola in cui il bot è autorizzato a rispondere. Gli ID dei gruppi provengono da signal-cli listGroups -d. Lascialo vuoto per disabilitare il supporto ai gruppi.
SIGNAL_HOME_CHANNEL (opzionale) - la destinazione di consegna predefinita per i task pianificati, i cron job e le notifiche attivate dalle skill. Se non impostato, l'output proattivo va al primo utente autorizzato.

Esegui chmod 600 ~/.hermes/.env dopo aver salvato. La combinazione dell'identità Signal collegata e delle chiavi del tuo provider di modelli dà a chiunque abbia accesso in lettura la capacità di impersonare il bot e bruciare i tuoi token: tratta il file come una chiave SSH.

Passo 5 - Avvia il gateway e invia il primo messaggio

Riavvia il gateway di Hermes così carica il nuovo ambiente:

hermes gateway restart

Segui i log e cerca due righe in ordine:

signal: connecting to http://127.0.0.1:8080
signal: subscribed to receive stream for +12025550123

Dal telefono autorizzato, apri Signal e invia un DM al numero del bot. Hermes risponde nello stesso thread, con la memoria persistente e il contesto delle skill intatti: la guida pratica a memoria e skill copre cosa succede sotto il cofano. Gli allegati fino a 100 MB viaggiano sulla stessa API di upload di Signal di un messaggio normale, quindi screenshot, note vocali e PDF passano senza impianti aggiuntivi.

Un thread di chat Signal che mostra uno scambio privato tra un utente e il bot Hermes, con gli indicatori di crittografia end-to-end visibili in cima allo schermo

Le modalità di errore che colpiscono per prime

Cinque errori spiegano quasi ogni thread di supporto del tipo "la configurazione di Signal è rotta":

Dimenticare di collegare il dispositivo. Eseguire signal-cli daemon su un account non collegato non stampa alcun errore: il daemon si avvia e rifiuta silenziosamente ogni messaggio. Se i log mostrano zero eventi e zero tentativi di invio, esegui signal-cli listAccounts e conferma che il tuo numero compaia.

Versione JRE sbagliata. Le build attuali di signal-cli richiedono JRE 21. Su server di lunga vita ancora bloccati su JRE 17 o 11, il jar fallisce con un mismatch di versione delle classi nel momento in cui invochi --http. O aggiorni Java o usi il binario nativo GraalVM.

SIGNAL_ALLOWED_USERS vuoto. L'impostazione predefinita è negare a tutti. È voluto: un numero di telefono dell'account del bot trapelato permetterebbe altrimenti a chiunque al mondo di inviare prompt che bruciano i token dei tuoi modelli. Il bot che sembra morto a chi prova per la prima volta e ha dimenticato di aggiungere il proprio numero è il falso allarme più comune.

Daemon associato a 0.0.0.0. Il daemon HTTP non esegue alcuna autenticazione. Associarlo a un'interfaccia pubblica significa che chiunque riesca a raggiungere la porta può inviare messaggi Signal come te. Associalo sempre a 127.0.0.1 o a una rete Docker privata.

Stato del dispositivo collegato obsoleto. Rieseguire signal-cli link sovrascrive la directory di stato locale. Il nuovo collegamento va bene, ma Hermes si ritrova improvvisamente a guardare un'identità diversa da quella dichiarata nel file env. O mantieni il vecchio valore SIGNAL_ACCOUNT quando ricolleghi, oppure aggiorna l'env al nuovo numero stampato dal comando di link.

Se un problema sembra di matrice Signal ma i sintomi paiono generali - risposte mancanti, deriva della memoria, errori del provider - la guida alla risoluzione dei problemi di Telegram copre più in profondità i problemi sottostanti del gateway e del provider. La maggior parte è indipendente dalla superficie.

Signal a confronto con Telegram e Slack

Aspetto	Signal	Telegram	Slack
Tempo di configurazione	20 min (link + daemon)	5 min (token BotFather)	15 min (manifest + 2 token)
Crittografia	End-to-end di default	Chat segrete opzionali	Solo lato server
Metadati conservati	Quasi nessuno	Cronologia lato server	Conservazione a livello di workspace
Modello di account	Numero di telefono collegato	Account bot, nessun numero	Utente bot nel workspace
Campo allowlist	`SIGNAL_ALLOWED_USERS` (E.164)	`TELEGRAM_ALLOWED_USERS` (numerico)	`SLACK_ALLOWED_USERS` (numerico)
Ideale per	Individui e piccoli team che mettono la privacy al primo posto	Uso personale, mobile-first, modalità vocale	Flussi di lavoro di team e contesto dei canali

Le tre superfici non si escludono a vicenda. Lo stesso runtime di Hermes può consegnare a tutte e tre contemporaneamente, multiplexando su un unico archivio di memoria. Un fondatore che usa un agente personale su Signal e un agente rivolto al team su Slack dalla stessa installazione è uno schema comune.

Salta l'impianto di Signal

I passi sopra sono fattibili ma ti lasciano la responsabilità dell'host: tenere signal-cli aggiornato, fare il backup dello stato del dispositivo collegato, ruotare il JRE, sorvegliare i riavvii del daemon. Per un'installazione personale va bene. Per qualcosa che vuoi online in pochi minuti e poi dimenticare, Hermify effettua il provisioning di un runtime Hermes gestito con il bridge Signal pronto da collegare, cifra a riposo la tua configurazione SIGNAL_* e mantiene sano il daemon signal-cli su un server persistente in cui non devi mai entrare via ssh.

Tu porti il numero Signal e una chiave di un provider di modelli; la piattaforma gestisce tutto il resto sotto. Se vuoi confrontare cosa resta sotto il tuo controllo rispetto a cosa viene delegato, la guida pratica self-hosting contro hosting gestito scompone i numeri di manutenzione e costo. E se il costo è la preoccupazione decisiva, la guida ai VPS economici illustra cosa significhi davvero in pratica un self-host da $5/mese. Inizia con Hermify quando sei pronto a saltare del tutto l'impianto.