Hermes Agent su Android con Termux: installazione e configurazione dei modelli

10 gennaio 2027 15 min di lettura Manuel

Avere un agente AI che gira sul telefono non è un trucco da smanettoni: è un terminale Linux che gira dentro Android, e Termux è il terminale in questione. Hermes Agent ha un pacchetto ufficiale per Termux, configurare i modelli è lo stesso identico lavoro che fai su WSL2, e l'unica cosa che cambia è dove trovare l'app.

Questo articolo fa tre cose: la storia di Termux, che spiega perché l'app non si installa più dal Google Play, e perché trovarla su F-Droid o Zapstore è la procedura corretta; l'installazione passo passo con i comandi; e la configurazione dei modelli, con il comando che serve e i limiti che ci sono davvero su un telefono.

La storia di Termux: un terminale Linux dentro Android

Termux nasce il 30 maggio 2015, opera dello sviluppatore svedese Fredrik Fornwall. L'idea era radicalmente semplice: un emulatore di terminale per Android che installa al primo avvio un sistema base minimo, e poi lascia installare i pacchetti con un gestore derivato da quello di Debian.

Non è una macchina virtuale, e non è un chroot dentro un altro sistema. Termux è un ambiente Linux che gira in userspace direttamente sopra il kernel Android: stesso kernel, zero virtualizzazione. I binari sono compilati con l'Android NDK, senza la struttura delle directory FHS (/etc, /usr, /var non esistono dove ti aspetteresti), e il prefisso è /data/data/com.termux/files/usr.

Questa scelta è la chiave di tutto il resto: nessun root, nessuna particolazione aggiuntiva, nessun boot modificato. Su un telefono qualunque, senza sbloccare nulla, hai bash, git, python, ssh, clang e oltre mille pacchetti.

Il primo problema vero arriva con Android 10. Da novembre 2020, Google impone che le app sul Play Store puntino almeno all'API level 29. Con quella regola, Android impedisce a un'app di chiamare exec() su file dentro la propria home directory — la cosiddetta violazione W^X: non si può eseguire codice da una directory scrivibile.

Termux, per funzionare, fa esattamente questo: installa binari in $PREFIX/bin e li esegue. L'app aveva dichiarato targetSdkVersion 28 per aggirare il problema, e con le nuove regole del Play Store non poteva più essere aggiornata. L'ultima versione pubblicata sul Play Store è la v0.101; il team consiglia esplicitamente di spostarsi su F-Droid o su GitHub, dove non esiste questo vincolo.

I pacchetti hanno avuto un secondo problema indipendente: nel maggio 2021 Bintray, che ospitava i repository dei pacchetti Termux, chiude. Termux migra tutto su Hetzner.

Nel gennaio 2020 il supporto a Android 5 e 6 è stato interrotto: Android 7 è il minimo. Nel novembre 2024, Termux riceve finanziamenti dalla NLnet Foundation nell'ambito del programma NGI Mobifree.

Perché questa storia conta ancora oggi. Se apri il Play Store e cerchi Termux, trovi un'app ferma a una versione vecchia di anni. Non è un progetto morto: è un progetto che non può più passare da lì. E la versione che trovi su F-Droid è quella che continua ad aggiornarsi.

Dove trovare Termux: F-Droid e Zapstore

F-Droid: la via normale

F-Droid è un catalogo di software libero per Android: non serve un account, niente pubblicità, e il client si scarica come APK dal suo sito.

Termux è qui: https://f-droid.org/en/packages/com.termux/. La pagina del pacchetto mostra due cose utili: il numero di versione e l'elenco delle architetture supportate.

Version 0.118.3  (1002)  suggested
arm64-v8a  armeabi-v7a  x86  x86_64
Requires Android 7.0 or newer

La versione suggested è quella stabile raccomandata; le beta sono elencate sopra. F-Droid costruisce l'APK da solo quando rileva una nuova release su GitHub, quindi può volerci da due a sette giorni: se sul sito del progetto esce una versione nuova e su F-Droid non c'è, non è un bug.

Due note pratiche. Primo, non serve installare il client F-Droid per avere Termux: dalla pagina del pacchetto si può scaricare l'APK direttamente. Il client serve per ricevere gli avvisi di aggiornamento. Secondo, se installi l'APK a mano non avrai mai notifiche: F-Droid stesso lo dice nella pagina del pacchetto.

Il file è un APK universale di circa 108-109 MiB, che vale per tutte le architetture. Al primo avvio viene scaricato e configurato il sistema base.

Zapstore: l'app store costruito su Nostr

Zapstore (zapstore.dev) è un altro catalogo di app per Android, e la differenza rispetto a F-Droid è il motivo per cui merita di essere nominato qui: non c'è un server centrale che decide cosa si può installare.

In F-Droid gli sviluppatori inviano il codice, e F-Droid lo ricompila su una propria infrastruttura, firmandolo con la propria chiave. È un modello di fiducia preciso: ti fidi di F-Droid. In Zapstore, invece, lo sviluppatore firma lui i metadati di release e li pubblica su relay Nostr, secondo il modello di eventi NIP-82 — che è una bozza, non ancora nel repository canonico delle NIP, e che Zapstore implementa da sé.

I tre tipi di evento in gioco:

Kind	Nome	Cosa contiene	Sostituibile da
`32267`	Software Application	nome, descrizione, icona, repository, licenza	`d` = package id
`30063`	Software Release	versione e riferimenti agli asset	`d` = package@versione
`3063`	Software Asset	l'APK, con hash e URL	`d` = coordinata

Questo è lo stesso meccanismo che abbiamo descritto nell'articolo Nostr: il protocollo che sposta il controllo dagli utenti alle piattaforme: l'identità è una coppia di chiavi, non un account. Su Zapstore chiunque con una coppia di chiavi può pubblicare, e chi riceve verifica la firma. Non serve un account, non serve un gatekeeper.

Il client Android è il prodotto più maturo del progetto, ed è rilasciato su GitHub: la release corrente è la 1.1.3, con APK allegato. Il client legge dai relay, verifica hash e certificato di firma prima dell'installazione, e usa i segnali di fiducia della web of trust di Nostr (chi segui, chi ti segue, quante zaps) per dirti quanto un publisher è attendibile.

Zapstore non è un sostituto esclusivo di F-Droid: molti app sono indicizzate a partire dai release di GitHub, o pubblicate dal developer stesso con lo strumento di pubblicazione zsp. È un canale in più.

Termux è indicizzato lì, all'indirizzo zapstore.dev/apps/com.termux, con la stessa descrizione e la stessa icona della pagina F-Droid. Nel caso di Termux la scheda mostra lo stato Indexed: il catalogo lo conosce, ma non è un publisher verificato che pubblica da sé, quindi la scheda non elenca release firmate. La via F-Droid resta la più diretta per Termux; Zapstore è la risposta giusta se il tuo obiettivo è non dipendere da un unico catalogo.

L'installazione del client Zapstore segue lo schema che Android impone a tutto ciò che sta fuori dal Play Store: si scarica l'APK dal sito del progetto, si concede una volta il permesso di installare da fonti sconosciute, e poi si apre l'app. Per Zapstore non serve un account, e dopo l'installazione vale la pena aggiornarlo dall'app quando propone una versione nuova: resta su una build recente evita la maggior parte dei problemi di catalogo e di notifiche di aggiornamento.

Perché non il Play Store

Perché il Play Store è la via chiusa, non la via sconsigliata. L'app è ferma alla versione 0.101, e il team dello sviluppo non ha accesso alla console del Play Store dove Termux è pubblicato, quindi non può nemmeno ritirarla: ha chiesto esplicitamente agli utenti di spostarsi altrove. In alcuni dispositivi il Play Store ha ripreso a pubblicare una versione aggiornata costruita da un codebase diverso (serve Android 11), ma non è il canale ufficiale e le due build non sono intercambiabili: se hai installato una delle due, l'installazione dell'altra fallisce per firma diversa.

Installare Termux

Un telefono arm64-v8a con Android 7 o superiore. Conviene avere qualche centinaia di MB liberi e una connessione decente per il primo avvio.

pkg update && pkg upgrade
termux-setup-storage

Il secondo comando è quello che spesso si salta e che poi fa perdere tempo: chiede il permesso di accesso all'archivio condiviso, e senza quel permesso Termux non vede le cartelle dei file scaricati. I file di Termux vivono in una home proprietaria, e i download di altre app sono in /storage/emulated/0. Quando serve lavorare su quei file, si monta il collegamento:

ls ~/storage/shared

Se hai installato Termux dal Play Store e vuoi passare a F-Droid: disinstalla prima quella, perché le firme sono diverse e l'aggiornamento fallisce con errori come INSTALL_FAILED_UPDATE_INCOMPATIBLE o signatures do not match. Stessa cosa vale per i plugin: Termux:API e gli altri sono APK separati, e vanno rimossi tutti.

Installare Hermes Agent su Termux

Qui c'è una cosa che bisogna sapere prima di cominciare, perché la documentazione ufficiale la dice e non è una nota a margine: il pacchetto Termux è una piattaforma di secondo livello, mantenuta best-effort. I commit su main possono romperlo in qualsiasi momento. La via che segue è quella che funziona; non è coperta dalle stesse garanzie di macOS, Windows e Linux.

E c'è una seconda cosa, che vale la pena leggere due volte: la documentazione ufficiale porta l'avviso "Termux is currently broken". Il pacchetto non funziona al momento, una correzione è in arrivo, e i passi seguenti possono fallire o installare un pacchetto che non parte. Lo stesso repo mostra la discrepanza: il canale stable non risponde (404 sia per la chiave che per il repository), mentre il canale canary è presente e contiene una versione pre-release.

Via APT: il pacchetto ufficiale

Hermes pubblica un repository APT firmato per Termux, a due canali sotto hermes-assets.nousresearch.com/releases/termux/:

Canale	Suite APT	Contenuto
`stable`	`hermes-stable`	release taggate `vMAJOR.MINOR.PATCH` che hanno superato il gate stabile
`canary`	`hermes-canary`	build pre-release, versioni con suffisso `~canary.<timestamp>`

Questo pacchetto non compila nulla sul telefono: include Python, Node.js, npm, uv, ripgrep, ffmpeg e le librerie di runtime, con le wheel native già costruite. È circa 173 MB di pacchetto, che si installano senza toolchain. Le wheel puntano a Android API 24 (android_24_arm64_v8a), quindi serve aarch64.

I passi:

# 1. Strumenti per il repository
pkg install curl gnupg

# 2. Chiave pubblica
mkdir -p "$PREFIX/etc/apt/keyrings"
curl -fsSL https://hermes-assets.nousresearch.com/releases/termux/canary/key.asc \
  -o "$PREFIX/etc/apt/keyrings/hermes-agent.asc"

# 3. Verifica dell'impronta
gpg --show-keys --with-fingerprint "$PREFIX/etc/apt/keyrings/hermes-agent.asc"

L'impronta della chiave è:

C572 B5FD D1A2 9CCF A9A9  12B6 840B 0848 E139 156D

Se è diversa, fermati. Non disabilitare la verifica della firma: il valore che ho trovato è stato letto dal canale canary, che risponde; la documentazione cita lo stesso identificativo per entrambi i canali, perché la chiave è una sola.

# 4. Repository (canary, visto che stable non risponde)
printf '%s\n' \
  "deb [signed-by=$PREFIX/etc/apt/keyrings/hermes-agent.asc] https://hermes-assets.nousresearch.com/releases/termux/canary hermes-canary main" \
  > "$PREFIX/etc/apt/sources.list.d/hermes-agent.list"

# 5. Installazione
pkg update
pkg install hermes-agent

# 6. Verifica
hermes --version
hermes doctor

I comandi hermes, hermes-agent e hermes-acp sono symlink in $PREFIX/bin e non richiedono i pacchetti python o nodejs di Termux: usano i runtime contenuti nel pacchetto.

Via install.sh: l'alternativa che c'è oggi

C'è una seconda via, e a questo momento è quella che ha più probabilità di funzionare, perché non dipende dal repository APT:

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

Lo script riconosce Termux da solo: usa pkg per i pacchetti di sistema, crea il virtual environment con python -m venv, esporta ANDROID_API_LEVEL per le build delle wheel, e mette hermes in $PREFIX/bin così resta sul PATH. Salta di proposito il bootstrap del browser e di WhatsApp.

Un dettaglio che dice molto sulla cura dello script: se lo esegui in un ambiente in cui Hermes è già installato via APT, lo script si rifiuta e ti dice di usare pkg install hermes-agent invece. Non sovrascrive un'installazione gestita dal package manager.

Aggiornamenti

Se l'installazione è APT, si aggiorna con:

pkg update && pkg upgrade hermes-agent

hermes update non va usato: su un'installazione di proprietà di APT rifiuta di modificare i file del pacchetto e stampa il comando del package manager al posto suo.

Per cambiare canale si modifica il percorso e la suite nel file hermes-agent.list, poi:

pkg update && pkg upgrade hermes-agent

File e configurazione

Contenuto	Posizione
File del pacchetto	`$PREFIX/lib/hermes-agent/`
Symlink dei comandi	`$PREFIX/bin/hermes`, `$PREFIX/bin/hermes-agent`, `$PREFIX/bin/hermes-acp`
Configurazione e dati utente	`~/.hermes/`, oppure `HERMES_HOME`

Il pacchetto include Python 3.14 e la TUI, e il closure delle wheel è core più acp, non tutti gli extra desktop. Aggiornare con APT preserva configurazione, sessioni, skill e memoria.

Configurare l'accesso ai modelli

La configurazione dei modelli è identica a quella che fai su WSL2, perché è lo stesso agente. Cambia solo il comando iniziale.

hermes setup
hermes --tui

Il comando che serve

hermes model

Questo è il wizard: aggiunge provider, chiede le chiavi API, esegue i flussi OAuth e scrive la scelta. È l'unico comando che aggiunge un provider.

Se sei già dentro una sessione, puoi cambiare modello con lo slash command:

/model openrouter/anthropic/claude-sonnet-4.5

Con --global la scelta resta anche per le sessioni future. Ma /model non aggiunge provider: se non lo vedi nel picker, esci dalla sessione e usa hermes model.

Dove va la configurazione

~/.hermes/
├── config.yaml     # modello, terminal backend, compressione
├── .env            # chiavi API e segreti
├── auth.json       # credenziali OAuth
└── sessions/       # sessioni

Le chiavi vanno in .env, il resto in config.yaml. Con hermes config set il valore finisce nel file giusto da solo: un nome MAIUSCOLO_SNAKE come OPENROUTER_API_KEY va in .env, le chiavi puntate vanno in config.yaml.

Il modo più rapido per un provider con chiave API:

hermes config set OPENROUTER_API_KEY «redacted:sk-…»
hermes config set model.provider openrouter
hermes config set model.default anthropic/claude-sonnet-4.5

La sezione risultante in config.yaml:

model:
  provider: openrouter
  default: anthropic/claude-sonnet-4.5

Un'avvertenza che vale su qualsiasi piattaforma, non solo qui. Se scrivi la chiave a mano, verifica l'indentazione: YAML la usa per la struttura, e una chiave allineata male non è un errore che si vede nel messaggio, è un provider che non compare nel picker.

Le opzioni di configurazione

Oltre al modello principale ci sono i modelli ausiliari: compito di comprimere il contesto, analizzare immagini, riassumere pagine, generare i titoli delle sessioni. Ognuno ha uno slot proprio e può essere sostituito indipendentemente. Su un telefono vale la pena tenerne due o tre configurati invece di sette: meno comandi, meno tentativi, meno traffico.

Se vuoi restringere il picker a quello che usi davvero:

model:
  default: anthropic/claude-sonnet-4.5
  provider: openrouter
  picker_providers:
    - openrouter

E se un provider cade, una catena di riserva interrompe la sessione:

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4.5
  - provider: openrouter
    model: google/gemini-2.5-flash

Il gateway

Questa installazione non usa systemd, launchd né i Task di Windows. Il gateway va lanciato in una sessione Termux:

hermes gateway run

Per tenerlo in background:

mkdir -p "${HERMES_HOME:-$HOME/.hermes}/logs"
nohup hermes gateway run >> "${HERMES_HOME:-$HOME/.hermes}/logs/gateway.log" 2>&1 &

Un'interruzione a metà di una frase è il sintomo tipico: Android ha ucciso il processo. Si controlla nei log e si riprova con termux-wake-lock attivo, sapendo che è un rimedio parziale.

Cosa funziona e cosa no su un telefono

Questa è la parte che gli articoli sull'argomento tendono a comprimere in una riga, e invece è dove si decide se lo strumento fa per te.

Funziona: la CLI, la TUI, il supporto a cron, i terminali PTY e in background, il gateway Telegram, MCP, Honcho per la memoria e ACP.

Non è disponibile:

Docker come terminale backend: non c'è un daemon Docker dentro Termux.
Il browser locale: il pacchetto non include Chromium. Il tool del browser usa un chromium di sistema se c'è su PATH (pkg install chromium, se il repository lo fornisce); senza, la navigazione non è disponibile e il tool lo dice.
La trascrizione vocale locale con faster-whisper: dipende da ctranslate2, che non pubblica wheel per Android. È il blocco concreto, non una mancanza di configurazione.
.[all] come extra di installazione: non supportato su Android.

Android può terminare i processi in background. Le esenzioni dall'ottimizzazione della batteria e termux-wake-lock aiutano, ma non garantiscono un funzionamento persistente. Il gateway su un telefono è best-effort, non un servizio gestito.

C'è anche un dettaglio di natura diversa, che viene da Python: su questa piattaforma sys.platform vale "android". Una dipendenza o una skill protetta solo per linux non è automaticamente disponibile.

Conclusione

Termux è il modo più diretto per avere un ambiente Linux reale su Android senza root, e la sua storia spiega perché si installa da F-Droid o Zapstore e non dal Play Store: la restrizione su exec() di Android 10 ha chiuso quel canale. Zapstore è in più interessante per ciò che è — un catalogo che firma e pubblica su Nostr invece di ricompilare su un'infrastruttura centrale — che per Termux in sé, dove F-Droid resta la via più semplice.

Hermes Agent c'è, con un pacchetto dedicato che non fa compilare nulla sul telefono. La configurazione dei modelli è la stessa di WSL2. Ma è una piattaforma di secondo livello, la documentazione ufficiale dichiara il pacchetto rotto, e il canale stabile del repository non risponde: chi parte deve sapere che sta entrando in un territorio mantenuto best-effort, non in uno supportato come le piattaforme desktop.

Per un telefono, questo non è un difetto. È il prezzo esatto di avere un agente che gira sul dispositivo che hai in tasca, con la batteria e i processi in background che il sistema operativo può sempre rivendicare.