Come installare Iva, assistente AI Telegram self-hosted

Cosa stai configurando

Iva è un assistente AI per Telegram self-hosted. È una delle poche soluzioni che puoi distribuire senza aprire porte in ingresso e senza associare un dominio al servizio. Non serve nemmeno un certificato, perché sul server non è in ascolto alcun servizio per il traffico pubblico. Il servizio avvia una connessione in uscita verso Telegram, la mantiene attiva 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 memoria è costituita da una directory di semplici file Markdown, che Obsidian può aprire direttamente. Le note che conserva su di te restano quindi leggibili anche senza l'applicazione. Questa guida blocca la release v0.3.13, pubblicata il 6 August 2026.

La maggior parte dei software self-hosted richiede innanzitutto un record DNS (domain name system) e un certificato Let's Encrypt emesso con Certbot. Iva elimina completamente questo livello. Per questo motivo, una piccola VPS protetta da un firewall che consente soltanto SSH è sufficiente per completare la distribuzione.

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 fa realmente l'installer su una sola riga

La pagina principale del progetto fornisce un comando che inoltra uno script da GitHub a bash. Leggete prima lo script, perché esegue molte più operazioni della semplice installazione di un programma.

curl -fsSL https://raw.githubusercontent.com/smixs/iva/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 uno swapfile da 2 GB in /swapfile quando il sistema dispone di meno di 1.5 GB di RAM e non ha swap, perché senza questo spazio il processo di build viene terminato.
• Installa nvm, quindi Node 24, che è la versione minima richiesta da Iva.
• Installa uv, il gestore dei pacchetti Python, in ~/.local/bin.
• Clona il repository in ~/iva ed esegue npm ci.
• Installa due pacchetti npm globali, agent-browser, che scarica quindi Chromium, e @googleworkspace/cli.
• Esegue la procedura guidata di configurazione, compila il progetto e crea il vault.
• Scrive un comando iva in ~/.local/bin e installa le unità user di systemd.

Per una sola riga, vengono installati molti componenti. Questo spiega anche l'indicazione nel README di eseguire l'installazione come utente normale e non come root: in seguito, lo strumento shell dell'agente viene eseguito con i privilegi dell'utente che ha eseguito l'installer. Lo script chiama sudo solo per installare i pacchetti e creare lo swapfile, tramite un helper che esegue direttamente i comandi quando l'utente è 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 fissata invece di passare lo script a bash

L’installer ha una caratteristica utile. Prima di clonare qualsiasi contenuto, verifica se la directory in cui si trova lo script contiene già un package.json con "eve". In caso affermativo, compila quella copia locale e salta la clonazione. Puoi quindi scegliere autonomamente la versione.

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

Ora sai quale codice viene eseguito. Non puoi saperlo quando lo script clona main nello stato in cui si trova in quel momento. Iva ha pubblicato cinque release tra il 4 e il 6 agosto 2026, quindi main questa mattina e main questo pomeriggio non sono lo stesso programma.

Il checkout di un tag lascia git nello stato detached HEAD. Funziona correttamente, ma devi comprenderne il limite: iva update sposta il checkout in avanti sul ramo di aggiornamento, quindi il pin definisce un punto di partenza noto e non un blocco permanente. iva version stampa la versione del pacchetto e il commit git, così puoi sapere sempre in quale stato ti trovi.

Per passare intenzionalmente a una release successiva, elenca i tag, imposta IVA_TAG su quello scelto, quindi esegui di nuovo l’installer dall’interno del checkout.

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

--skip-setup impedisce l’esecuzione guidata su un .env già funzionante.

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 Iva al mese

[
  {
    "plan": "Small VPS, always on",
    "usd_per_month": 5
  },
  {
    "plan": "OpenCode Go model plan",
    "usd_per_month": 5
  },
  {
    "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": 10
  }
]

Questi sono i prezzi di listino pubblicati ad agosto 2026, non misurazioni. Un piccolo VPS a 5 dollari statunitensi, più il piano OpenCode Go a 5 dollari, è la configurazione completa più economica: circa 10 dollari al mese. Ollama Cloud è l'altra opzione a tariffa fissa, a 20 dollari; i suoi modelli frontier vengono fatturati come consumo aggiuntivo oltre al piano. Voice costa 0 finché sono disponibili i crediti iniziali di Deepgram.

OpenRouter non compare nella tabella perché usa la fatturazione a consumo, quindi l'importo segue il tuo utilizzo. È l'opzione da monitorare: un assistente che porta una finestra di contesto di 131072 token in ogni turno può superare rapidamente il costo di un piano a tariffa fissa. Imposta la variabile della finestra di contesto sulla dimensione effettiva del modello, perché un valore sovrastimato consuma soltanto token inutilmente.

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

Iva richiede un dominio o una porta aperta?

No. Iva comunica con Telegram tramite long polling: iva-telegram-poll.service chiama getUpdates e attende, quindi ogni connessione è in uscita dal server. Non è necessario che dall'esterno raggiunga il server, quindi non servono né un record DNS né un certificato. La porta HTTP dell'agente, 8723, è associata a 127.0.0.1 e la documentazione del progetto ne vieta l'esposizione. La configurazione corretta prevede un firewall che consenta solo SSH.

Quanto costa eseguire Iva ogni mese?

Ai prezzi di listino pubblicati per agosto 2026, un piccolo VPS da 5 dollari, sommato al piano con tariffa fissa più economico da 5 dollari, costa circa 10 dollari statunitensi al mese. Ollama Cloud costa invece 20 dollari e addebita separatamente l'uso dei modelli frontier. I crediti iniziali di Deepgram coprono il riconoscimento vocale nella fase iniziale e i piani di ricerca sul web prevedono soglie gratuite. OpenRouter applica una tariffazione a consumo, quindi non ha un costo mensile fisso.

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

Per impostazione predefinita, in ~/iva/vault, configurato da ASSISTANT_VAULT_DIR. Si tratta di un repository git privato separato, composto da file markdown in chiaro: CORE.md, daily/YYYY-MM-DD.md, cards/ e summaries/. Il memory doctor delle 05:00 esegue il commit e il push, ma questo funziona solo se il repository ha un repository remoto. Durante la configurazione esegui quindi gh auth login oppure aggiungi un remote personalizzato. Conserva anche una copia offline con tar czf ~/iva-vault-backup.tgz -C ~/iva vault e trasferisci quel file fuori dal server.

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

Lo storage è tuo. L'elaborazione no. Il vault resta sul disco finché non lo esegui il push e .env ha i permessi 0600 ed è di proprietà dell'utente del servizio. Le chiamate ai modelli e la trascrizione vocale usano API cloud, quindi quei messaggi transitano dal provider del modello e da Deepgram. Iva è distribuito con licenza MIT: puoi leggere esattamente ciò che invia e modificarlo. L'allowlist di Telegram applica una configurazione fail closed: un TELEGRAM_ALLOWED_USER_IDS vuoto blocca tutti, incluso te.

Quali provider di modelli supporta Iva?

MODEL_PROVIDER accetta opencode (OpenCode Go), ollama (Ollama Cloud), openrouter e codex. OpenRouter richiede uno slug del vendor come anthropic/claude-sonnet-4.5 e offre la scelta più ampia di modelli. codex accede a un abbonamento ChatGPT esistente tramite iva login e non usa alcuna API key. Imposta il provider e la context window corrispondente alle dimensioni effettive del modello, quindi esegui iva restart, perché il modello viene letto una sola volta all'avvio del processo.