Come installare Iva, assistente AI Telegram self-hosted

Cosa stai realizzando

Iva è un assistente AI per Telegram self-hosted ed è uno dei pochi che puoi distribuire senza dover aprire porte in ingresso o puntare un dominio. Non è necessario alcun certificato, poiché nulla sul server rimane in ascolto verso l'esterno. Il servizio stabilisce una connessione in uscita verso Telegram, la mantiene aperta e legge i tuoi messaggi dalla risposta. Tutto il resto deriva da questa singola connessione in uscita.

Iva è distribuito con licenza MIT ed è scritto in Node. La sua memoria consiste in una cartella di file markdown in chiaro che Obsidian può aprire direttamente, in modo che le note che conserva su di te rimangano leggibili anche senza l'applicazione. Questa guida fa riferimento alla release v0.3.13, pubblicata il 6 agosto 2026. Il repository è stato nel frattempo rinominato da smixs/iva a smixs/iva-agent e i comandi seguenti utilizzano il nuovo nome.

La maggior parte del software self-hosted inizia con un record DNS (Domain Name System) e un certificato Let's Encrypt emesso con Certbot. Iva salta completamente questo livello, motivo per cui una piccola VPS dietro un firewall che consente solo SSH costituisce una distribuzione completa.

Perché Iva non richiede porte aperte

iva-telegram-poll.service è un bridge long polling. Chiama l'API getUpdates di Telegram e attende la risposta, quindi ogni connessione viene avviata dal server. Telegram non si connette mai al server, perciò non è necessario configurare un reverse proxy né occuparsi del rinnovo dei certificati.

L'agent è comunque in ascolto, ma soltanto sulla porta 127.0.0.1 8723. La documentazione del progetto è chiara: non esporre la porta 8723 e, se si configura un reverse proxy davanti all'agent, mantenere obbligatorio il bearer token. Dopo l'installazione, verificare l'indirizzo di bind.

sudo ss -tlnp | grep 8723

L'indirizzo deve essere 127.0.0.1:8723. Un indirizzo wildcard come 0.0.0.0:8723 rende raggiungibili da Internet le route HTTP dell'agent. Correggere questa configurazione prima di inviare al bot informazioni private.

Il firewall può quindi rimanere chiuso. Consentire SSH prima di abilitarlo, perché ufw enable senza una regola per SSH chiude la sessione in cui si sta lavorando.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Cosa esegue realmente l'installer a riga singola

La pagina principale del progetto fornisce un comando che invia tramite pipe uno script da GitHub a bash. Leggi prima lo script, poiché esegue molte più operazioni della semplice installazione di un programma.

curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh -o iva-install.sh
less iva-install.sh

• Installa i pacchetti di sistema con il gestore pacchetti rilevato: git, gh, python3, ffmpeg, pandoc e poppler-utils.
• Crea un file di swap da 2 GB in /swapfile quando il server ha meno di 1.5 GB di RAM e nessuno swap, poiché altrimenti il processo di build verrebbe terminato.
• Installa nvm, quindi Node 24, ovvero la versione minima richiesta per l'esecuzione di Iva.
• Installa uv, il gestore pacchetti Python, in ~/.local/bin.
• Clona il repository in ~/iva ed esegue npm ci.
• Installa agent-browser come pacchetto npm globale, che successivamente scarica Chromium e posiziona la CLI di Google Workspace, gws, in ~/.local senza privilegi di sudo.
• Avvia la procedura guidata di configurazione, compila il progetto e crea il vault.
• Scrive un comando iva in ~/.local/bin e installa le systemd user unit.

Si tratta di una quantità considerevole di software per un'unica riga di comando. Questo spiega anche l'istruzione nel README di eseguire l'installazione come utente ordinario e non come root: lo strumento shell dell'agente verrà eseguito in seguito con i privilegi utilizzati durante l'installazione. Lo script richiama sudo solo per l'installazione dei pacchetti e per il file di swap, oltre eventualmente a un'ulteriore volta per il passaggio relativo a Chromium, tramite un helper che esegue i comandi direttamente nel caso in cui si sia già root.

Crea un utente dedicato prima dell'installazione

Assegna a Iva un account dedicato. L'agente esegue comandi shell sull'host tramite child_process di Node, senza container né sandbox. L'account con cui viene eseguito costituisce quindi il confine di sicurezza.

sudo adduser --disabled-password --gecos "" iva
sudo usermod -aG sudo iva
sudo install -d -m 700 -o iva -g iva /home/iva/.ssh
sudo cp ~/.ssh/authorized_keys /home/iva/.ssh/authorized_keys
sudo chown iva:iva /home/iva/.ssh/authorized_keys
sudo chmod 600 /home/iva/.ssh/authorized_keys
sudo loginctl enable-linger iva

enable-linger è necessario perché Iva viene eseguita come unità user di systemd. Senza linger, systemd arresta i servizi di quell'utente non appena termina l'ultima sessione. L'assistente quindi si arresterebbe quando chiudi SSH. La stessa regola si applica a ogni servizio e timer che scrivi direttamente in systemd.

L'account richiede sudo solo mentre il programma di installazione aggiunge i pacchetti. Rimuovilo al termine dell'installazione.

sudo deluser iva sudo

Accedi direttamente tramite SSH con quell'utente. Una shell aperta con sudo -iu iva non ha impostati DBUS_SESSION_BUS_ADDRESS né XDG_RUNTIME_DIR. Di conseguenza, ogni comando systemctl --user fallisce con Failed to connect to bus. Definire questo confine equivale a eseguire i servizi con utenti dotati del privilegio minimo.

Installare una release specifica invece di eseguire lo script tramite pipe

L'installer possiede una proprietà utile. Prima di clonare qualsiasi elemento, verifica se la directory in cui risiede lo script contiene già un package.json con "eve". In tal caso, esegue la build di quel checkout e salta la clonazione. In questo modo è possibile scegliere la versione autonomamente.

git clone --branch v0.3.13 https://github.com/smixs/iva-agent.git ~/iva
cd ~/iva
git log -1 --oneline
bash install.sh

Ora è possibile conoscere quale codice è in esecuzione. Non è possibile saperlo quando lo script clona main nello stato in cui si trova in quel preciso momento. Iva ha rilasciato cinque versioni tra il 4 e il 6 agosto 2026, quindi main di questa mattina e main di questo pomeriggio non sono lo stesso programma.

Un checkout di un tag lascia git in uno stato di detached HEAD. Questo funziona correttamente, ma è necessario comprenderne il limite: iva update sposta il checkout in avanti sul branch di aggiornamento, quindi il pin rappresenta un punto di partenza noto e non un blocco permanente. iva version stampa la versione del pacchetto e il commit git, permettendo di verificare sempre la propria posizione.

Per passare intenzionalmente a una release successiva, elencare i tag, eseguire il checkout di quello scelto al posto di v0.3.13 qui sotto, quindi eseguire nuovamente l'installer dall'interno del checkout. L'installer stesso non dispone di impostazioni per un tag di release. Le sue variabili d'ambiente documentate sono REPO_URL, BRANCH e INSTALL_DIR, pertanto il checkout git è l'unico metodo per effettuare il pinning.

cd ~/iva
git fetch --tags
git tag --list 'v*' | sort -V | tail -5
git checkout v0.3.13
bash install.sh --skip-setup
iva restart

--skip-setup impedisce al wizard di essere eseguito nuovamente su un .env già funzionante. Eseguire iva version successivamente per confermare il commit raggiunto.

I cinque passaggi della procedura guidata e le chiavi richieste

1. Provider e modello. MODEL_PROVIDER accetta opencode, ollama, openrouter o codex. La procedura guidata convalida la chiave in tempo reale ed elenca i modelli inclusi nel piano.
2. Voce e ricerca. Una chiave Deepgram trascrive i messaggi vocali. Una chiave per la ricerca web (Tavily, Exa, Parallel o Brave) è facoltativa.
3. Token del bot Telegram ottenuto da @BotFather, verificato sull'endpoint getMe.
4. Controllo degli accessi. Invia un messaggio al bot e la procedura guidata legge il tuo ID utente numerico da getUpdates.
5. Impostazioni di sistema. Fuso orario IANA, directory del vault e porta locale, 8723 per impostazione predefinita.

Due di questi elementi sono dipendenze che la formula "un solo comando" nasconde. Iva non include alcun modello, quindi prima di rispondere ha bisogno di un piano per un modello a pagamento o di una chiave API. Inoltre, non trascrive autonomamente l'audio, quindi i messaggi vocali richiedono un servizio separato. Il modello Deepgram nova-3 con DEEPGRAM_LANGUAGE=multi rileva la lingua e i nuovi account Deepgram ricevono crediti iniziali sufficienti per mesi di uso personale. I messaggi di testo funzionano con la sola chiave del modello. Solo la voce dipende da Deepgram.

Controlla ciò che la procedura guidata ha scritto.

grep -E '^(MODEL_PROVIDER|TELEGRAM_ALLOWED_USER_IDS|ASSISTANT_VAULT_DIR|IVA_PORT)=' ~/iva/.env
ls -l ~/iva/.env

ls dovrebbe mostrare -rw-------, modalità 0600, perché quel file contiene tutte le chiavi appena incollate. TELEGRAM_ALLOWED_USER_IDS deve contenere il tuo ID numerico. L'allowlist adotta una modalità fail closed, quindi un valore vuoto impedisce a Iva di rispondere a chiunque.

Il modello viene letto una sola volta, all'avvio del processo. Modificare MODEL_PROVIDER o il nome di un modello in .env non produce alcun effetto finché non esegui iva restart. Su openrouter il nome del modello è uno slug del vendor, ad esempio anthropic/claude-sonnet-4.5, non un nome semplice. Su codex non esiste alcuna chiave API: iva login accede a un abbonamento ChatGPT esistente.

Quanto costa gestire Iva ogni mese

[
  {
    "plan": "Small VPS, always on",
    "usd_per_month": 5
  },
  {
    "plan": "OpenCode Go model plan",
    "usd_per_month": 10
  },
  {
    "plan": "Ollama Cloud model plan",
    "usd_per_month": 20
  },
  {
    "plan": "Deepgram voice, starter credits",
    "usd_per_month": 0
  },
  {
    "plan": "Tavily web search, free tier",
    "usd_per_month": 0
  },
  {
    "plan": "Cheapest complete setup",
    "usd_per_month": 15
  }
]

Questi sono i prezzi di listino pubblicati a ottobre 2026, non misurazioni effettive. Una piccola VPS a 5 dollari statunitensi più il piano OpenCode Go a 10 dollari rappresentano la configurazione completa più economica, circa 15 dollari al mese. La pagina Go di OpenCode riporta tale prezzo mensile senza sconti per il primo mese, e il README di Iva stima lo stesso stack a circa 14-15 dollari tutto incluso. Ollama Cloud è l'altra opzione a tariffa fissa a 20 dollari per il piano Pro; l'utilizzo che eccede i crediti inclusi nel piano viene fatturato a parte. I costi vocali sono pari a 0 finché durano i crediti starter di Deepgram.

OpenRouter non è presente in questo elenco poiché adotta una tariffazione a consumo, pertanto la fattura varia in base all'utilizzo. Questa è l'opzione da monitorare: un assistente che mantiene una finestra di contesto di 131072 token a ogni turno può superare rapidamente i costi di un piano a tariffa fissa. Impostare la variabile della finestra di contesto sulla dimensione reale del modello, poiché un valore gonfiato comporta solo uno spreco di token.

I due servizi e i due timer

• iva.service esegue direttamente l'agente.
• iva-telegram-poll.service esegue il bridge long polling che comunica con Telegram.
• iva-memory-doctor.timer si attiva alle 05:00 ed esegue la manutenzione notturna del vault.
• iva-update-check.timer si attiva alle 10:00 e verifica se è disponibile una release più recente.
• iva-telegram-userbot.service esiste solo se hai configurato il proxy Telethon opzionale.

iva status
systemctl --user status iva.service iva-telegram-poll.service
systemctl --user list-timers
iva logs poll

iva status mostra lo stato di entrambi i servizi e dei due timer di watchdog. systemctl --user list-timers visualizza l'orario della prossima esecuzione di ciascun timer. In questo modo puoi verificare che il memory doctor venga effettivamente eseguito stanotte. Entrambi i servizi devono rimanere in active (running). Se uno dei due viene riavviato continuamente, journalctl --user -u iva.service -n 100 ne indica il motivo.

La separazione è importante durante il troubleshooting. Il bridge può essere attivo e in fase di polling mentre l'agente è arrestato. In questo caso Telegram accetta il messaggio, ma non ricevi alcuna risposta. iva logs poll segue il bridge, mentre iva logs segue l'agente. I due log permettono quindi di stabilire quale componente non funziona.

Dove si trova il vault di Obsidian e come eseguirne il backup

ASSISTANT_VAULT_DIR punta per impostazione predefinita a vault nella directory di installazione, quindi la memoria si trova in ~/iva/vault. È un repository git autonomo, separato dal codice. Questo consente di aggiornare Iva senza modificare le note.

• vault/CORE.md contiene fatti persistenti e preferenze permanenti, con un limite di 1200 caratteri, e viene incluso in ogni prompt di sistema.
• vault/daily/YYYY-MM-DD.md contiene la trascrizione della giornata e viene gestito solo in modalità append.
• vault/cards/ contiene schede tipizzate per contatti, progetti, decisioni, idee e note.
• vault/summaries/daily/, weekly/, monthly/ e yearly/ contengono i riepiloghi.
• vault/attachments/ contiene i file organizzati per data, mentre vault/.graph/ contiene il grafo dei collegamenti.
• vault/schema.json definisce i tipi di scheda e le regole di decadimento.

I riepiloghi vengono generati secondo una pianificazione interna al processo. L'esecuzione giornaliera delle 04:00 trasforma la trascrizione del giorno precedente in schede e in un riepilogo, quindi riscrive CORE.md. Le esecuzioni settimanali, mensili e annuali comprimono poi questi dati in successione. Alle 05:00 memory doctor esegue un passaggio deterministico senza coinvolgere alcun modello: applica lo schema, ricostruisce il grafo dei collegamenti, rigenera l'indice, quindi esegue commit e push.

Questo push è il backup ed è il passaggio che spesso viene omesso. Se il vault non ha un remote git, doctor prova a creare un repository GitHub privato tramite gh, che richiede un GitHub CLI autenticato.

gh auth login
systemctl --user start iva-memory-doctor.service
cd ~/iva/vault && git log --oneline -3

Un commit con la data odierna indica che l'esecuzione è terminata e che il vault è stato sottoposto a commit. Gli avvisi gh not available nel log indicano il contrario: il vault viene mantenuto, ma non lascia mai il server. Se il VPS si guasta, perdi anche la memoria.

Conserva comunque anche una copia sotto il tuo controllo.

tar czf ~/iva-vault-backup.tgz -C ~/iva vault

Copia quel file fuori dal server con scp, quindi eliminalo dal server. Per leggere la memoria in Obsidian, indica a Obsidian un clone del repository del vault. I wikilink e i backlink funzionano senza modifiche, così come la vista a grafo. Puoi modificare manualmente le schede e CORE.md senza rischi. Non modificare MOC.md e .graph/, perché l'esecuzione notturna li rigenera entrambi.

Considera il vault come un registro della tua vita

Quella directory è un registro datato di ciò che hai detto, delle persone che hai incontrato e delle decisioni che hai preso, su una macchina che noleggi. Da questo derivano due conseguenze.

Il self-hosting sposta lo storage, non l'elaborazione. Ogni turno viene inviato al tuo provider del modello e ogni nota vocale viene inviata a Deepgram. Il vault è tuo. Le richieste non sono private rispetto alle aziende che le gestiscono. Eseguire autonomamente il livello di memoria, come con un server di memoria Mem0 sul tuo VPS, segue lo stesso modello: lo storage è locale, ma la chiamata al modello esce comunque dalla macchina. Se un argomento è troppo sensibile per un servizio di terze parti, non inserirlo nella chat.

La portata di quell'account comprende l'intero vault. Gli strumenti di Iva vengono eseguiti direttamente sull'host tramite fs e child_process di Node, senza Docker e senza sandbox, quindi un turno dirottato dispone di tutti gli accessi dell'utente del servizio. Per questo, dopo l'installazione, l'account non contiene alcun sudo e per questo la allowlist richiede più attenzione di quanto possa sembrare: è il controllo che decide quali messaggi diventano comandi sul server. Se vuoi avere l'assistente sempre disponibile senza esporre nulla, questo è lo stesso modello usato per raggiungere dal telefono un agente Hermes self-hosted, con il client di chat che svolge il ruolo che altrimenti avrebbe un endpoint pubblico.

Cosa non funziona e quale messaggio verrà visualizzato

Build terminata, exit 137. L'oom killer del kernel ha terminato la build. L'installer aggiunge lo swap solo quando la RAM è inferiore a 1.5 GB e non esiste alcuno swap; aggiungilo manualmente ed esegui di nuovo l'installer.

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
free -h

Failed to connect to bus. Ogni comando systemctl --user visualizza questo messaggio quando la shell non dispone di una sessione bus utente, che è ciò che fornisce sudo -iu iva. Apri una normale sessione SSH con quell'utente oppure esporta XDG_RUNTIME_DIR=/run/user/$(id -u iva) prima di eseguire il comando.

Il bot non risponde. TELEGRAM_ALLOWED_USER_IDS è vuoto e l'allowlist applica una policy fail-closed. Invia un messaggio al bot: risponderà con il tuo ID numerico e nient'altro. Inserisci quell'ID in .env ed esegui iva restart.

Il bot smette di rispondere subito dopo iva config. Il wizard può spostare IVA_PORT senza aggiornare ASSISTANT_HOST, quindi il bridge si connette a una porta sulla quale non è in ascolto alcun servizio. Confronta le due righe, quindi riavvia.

grep -E '^(IVA_PORT|ASSISTANT_HOST)=' ~/iva/.env
iva restart

Una nota vocale non riceve risposta. La Bot API di Telegram rifiuta i download di file superiori a 20 MB, quindi il bridge non riceve gli audio lunghi e non ha nulla da inviare a Deepgram. Dividi il file prima di inviarlo.

ffmpeg -i long.ogg -f segment -segment_time 600 -c copy part-%02d.ogg

Un turno rimane bloccato e non riceve mai risposta. Lo stato bloccato del workflow sopravvive a un riavvio e viene nuovamente accodato, quindi il solo riavvio non lo elimina. iva reset mette in quarantena quello stato e riavvia entrambi i servizi. /new nella chat avvia una nuova conversazione.

Chromium non funziona su Ubuntu 24.04. Ubuntu 24.04 blocca gli user namespace non privilegiati tramite AppArmor, quindi la sandbox interna di Chromium non può avviarsi e agent-browser non funziona. L'installer aggira il problema scrivendo "--no-sandbox" in ~/.agent-browser/config.json. Tienilo presente. Questa impostazione riduce l'isolamento del browser e costituisce un ulteriore motivo per cui l'account non dovrebbe essere proprietario di nulla, ad eccezione di Iva.

FAQ

È necessario un dominio o una porta aperta per l'hosting di Iva?

No. Iva comunica con Telegram tramite long polling: iva-telegram-poll.service chiama getUpdates e rimane in attesa, quindi ogni connessione è in uscita dal server. Nulla deve raggiungere la macchina dall'esterno, pertanto non sono necessari record DNS né certificati. La porta HTTP dell'agente, la 8723, è in ascolto su 127.0.0.1 e la documentazione del progetto specifica di non esporla. Un firewall che consenta solo il traffico SSH è la configurazione corretta.

Qual è il costo mensile per l'esecuzione di Iva?

Secondo i listini di ottobre 2026, una piccola VPS a 5 dollari, sommata al piano tariffario flat più economico a 10 dollari, porta a un totale di circa 15 dollari statunitensi al mese. Ollama Cloud costa invece 20 dollari, con addebiti aggiuntivi per l'utilizzo oltre i crediti inclusi. I crediti iniziali di Deepgram coprono inizialmente la parte vocale, mentre i livelli di ricerca web prevedono franchigie gratuite. OpenRouter segue un modello pay-as-you-go, quindi non ha un costo mensile fisso.

Dove conserva i dati Iva e come posso eseguire il backup?

Per impostazione predefinita in ~/iva/vault, definito da ASSISTANT_VAULT_DIR. Si tratta di un repository git privato separato contenente file markdown in chiaro: CORE.md, daily/YYYY-MM-DD.md, cards/ e summaries/. La procedura di "memory doctor" delle 05:00 esegue il commit e il push, operazione utile solo se il repository ha un remote configurato; pertanto, esegui gh auth login o aggiungi un tuo remote durante la configurazione. Mantieni anche una copia offline con tar czf ~/iva-vault-backup.tgz -C ~/iva vault e sposta tale file fuori dal server.

I miei dati sono privati se eseguo Iva in self-hosting?

L'archiviazione è sotto il tuo controllo, l'elaborazione no. Il vault rimane sul tuo disco finché non esegui il push e .env è impostato con permessi 0600, di proprietà dell'utente del servizio. Le chiamate ai modelli e la trascrizione vocale avvengono tramite API cloud, quindi i messaggi transitano attraverso il fornitore del modello e Deepgram. Iva è distribuito con licenza MIT, quindi puoi verificare esattamente cosa invia e modificarlo. La whitelist di Telegram è di tipo "fail-closed": un file TELEGRAM_ALLOWED_USER_IDS vuoto blocca chiunque, te compreso.

Quali fornitori di modelli supporta Iva?

Nella release v0.3.13, MODEL_PROVIDER accetta opencode (OpenCode Go), ollama (Ollama Cloud), openrouter e codex. OpenRouter accetta uno slug del fornitore come anthropic/claude-sonnet-4.5 e offre la scelta più ampia di modelli. codex effettua l'accesso a un abbonamento ChatGPT esistente tramite iva login senza utilizzare alcuna API key. Le release successive aggiungeranno ulteriori percorsi, inclusi un abbonamento Claude e un endpoint personalizzato compatibile con OpenAI. Imposta il fornitore, configura la finestra di contesto corrispondente alla dimensione reale del modello, quindi esegui iva restart, poiché il modello viene letto una sola volta all'avvio del processo.