Zelf Iva hosten als Telegram AI-assistent

Wat u bouwt

Iva is een zelfgehoste Telegram AI-assistent. Het is een van de weinige assistenten die u kunt implementeren zonder inkomende poorten te openen of een domein naar de server te verwijzen. Er is ook geen certificaat nodig, omdat er niets op de server is dat luistert naar publiek verkeer. De service maakt een uitgaande verbinding met Telegram, houdt deze verbinding open en leest uw berichten via het antwoord. Alles vloeit voort uit die ene uitgaande verbinding.

Iva is MIT-gelicentieerd en geschreven in Node. Het geheugen bestaat uit een map met platte markdown-bestanden die direct door Obsidian kunnen worden geopend, waardoor de notities die de assistent over u bijhoudt leesbaar blijven zonder de applicatie. Deze handleiding is gebaseerd op release v0.3.13, gepubliceerd op 6 augustus 2026.

De meeste zelfgehoste software begint met een DNS-record (Domain Name System) en een via Certbot uitgegeven Let's Encrypt-certificaat. Iva slaat die laag volledig over. Daarom is een kleine VPS achter een firewall die alleen SSH toestaat, voldoende voor een volledige implementatie.

Waarom Iva geen open poorten nodig heeft

iva-telegram-poll.service is een long polling bridge. Deze roept de getUpdates API van Telegram aan en wacht op het antwoord, waardoor elke verbinding vanuit uw server wordt gestart. Telegram maakt nooit een terugkerende verbinding, wat betekent dat er geen reverse proxy geconfigureerd hoeft te worden en er geen certificaatvernieuwing is om te vergeten.

De agent zelf luistert wel, uitsluitend op 127.0.0.1 poort 8723. De projectdocumentatie is hier duidelijk over: stel poort 8723 niet bloot aan het internet en elke reverse proxy die u ervoor plaatst, moet de vereiste voor een bearer token handhaven. Controleer het bind-adres na de installatie.

sudo ss -tlnp | grep 8723

Het adres moet 127.0.0.1:8723 weergeven. Een wildcard-adres zoals 0.0.0.0:8723 betekent dat de HTTP-routes van de agent bereikbaar zijn vanaf het internet; u dient dit te corrigeren voordat u de bot gevoelige informatie verstuurt.

De firewall blijft dus gesloten. Sta SSH toe voordat u deze inschakelt, want ufw enable zonder SSH-regel sluit de sessie waarin u op dat moment werkt.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Wat de one-line installer daadwerkelijk uitvoert

De voorpagina van het project biedt een commando dat een script van GitHub direct naar bash pipe-t. Lees het script eerst door, aangezien het aanzienlijk meer doet dan alleen één programma installeren.

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

• Het installeert systeempakketten met de gedetecteerde package manager: git, gh, python3, ffmpeg, pandoc en poppler-utils.
• Het maakt een swapfile van 2 GB aan op /swapfile wanneer de server minder dan 1.5 GB RAM heeft en geen swap gebruikt, omdat het build-proces anders wordt beëindigd.
• Het installeert nvm en vervolgens Node 24, de minimale versie waarop Iva draait.
• Het installeert uv, de Python package manager, in ~/.local/bin.
• Het kloont de repository naar ~/iva en voert npm ci uit.
• Het installeert twee globale npm-pakketten, agent-browser (die vervolgens Chromium downloadt) en @googleworkspace/cli.
• Het voert de setup-wizard uit, bouwt het project en maakt de vault aan.
• Het schrijft een iva-commando naar ~/.local/bin en installeert de systemd user units.

Dat is een aanzienlijke hoeveelheid software voor één regel. Dit verklaart ook de instructie in de README om als gewone gebruiker te installeren en niet als root: de shell-tool van de agent draait later met de rechten die de installer had. Het script roept sudo alleen aan voor de pakketinstallaties en de swapfile, via een helper die commando's direct uitvoert wanneer u al als root bent ingelogd.

Maak een toegewezen gebruiker aan voor de installatie

Geef Iva een eigen account. De agent voert shell-commando's uit op de host via Node's child_process, zonder container of sandbox. Het account waaronder deze draait, vormt daarom de beveiligingsgrens.

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 is van belang omdat Iva draait als systemd user units. Zonder linger stopt systemd de services van die gebruiker zodra de laatste sessie wordt beëindigd. De assistent zou dus stoppen zodra u de SSH-verbinding verbreekt. Dezelfde regel geldt voor elke service en timer die u zelf onder systemd aanmaakt.

Het account heeft alleen sudo nodig terwijl het installatieprogramma pakketten toevoegt. Trek deze rechten in zodra de installatie is voltooid.

sudo deluser iva sudo

Log direct in als die gebruiker via SSH. Een shell die u opent met sudo -iu iva heeft noch DBUS_SESSION_BUS_ADDRESS, noch XDG_RUNTIME_DIR ingesteld. Hierdoor faalt elk systemctl --user-commando met Failed to connect to bus. Het trekken van deze grens is dezelfde oefening als het draaien van services onder gebruikers met minimale rechten.

Een pinned release installeren in plaats van pipe naar bash

Het installatieprogramma heeft een nuttige eigenschap. Voordat het iets kloont, controleert het of de map waarin het script zich bevindt al een package.json bevat met daarin "eve". Als dat zo is, bouwt het die checkout en slaat het klonen over. U kunt de versie dus zelf kiezen.

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

Nu weet u welke code er draait. Dat weet u niet wanneer het script main kloont in de staat waarin het zich op dat uur toevallig bevindt. Iva bracht tussen 4 en 6 augustus 2026 vijf releases uit, dus main van vanochtend en main van vanmiddag zijn niet hetzelfde programma.

Een tag-checkout laat git achter in een detached HEAD-status. Dat werkt prima, maar begrijp de beperking: iva update verplaatst de checkout naar de update-branch, dus de pin is een bekend startpunt en geen permanente bevriezing. iva version toont de pakketversie en de git-commit, zodat u altijd kunt zien waar u bent.

Om bewust naar een latere release te gaan, lijst u de tags op, stelt u IVA_TAG in op de door u gekozen tag en voert u het installatieprogramma opnieuw uit vanuit de 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 voorkomt dat de wizard opnieuw wordt uitgevoerd over een .env die al werkt.

De vijf stappen van de wizard en de vereiste sleutels

1. Modelprovider en model. MODEL_PROVIDER accepteert opencode, ollama, openrouter of codex. De wizard valideert de sleutel direct en toont de modellen die uw abonnement aanbiedt.
2. Spraak en zoekopdrachten. Een Deepgram-sleutel transcribeert spraakberichten. Een sleutel voor webzoekopdrachten (Tavily, Exa, Parallel of Brave) is optioneel.
3. Telegram bot-token van @BotFather, gecontroleerd via het getMe-eindpunt.
4. Toegangsbeheer. U stuurt uw bot een bericht en de wizard leest uw numerieke gebruikers-ID uit getUpdates.
5. Systeeminstellingen. IANA-tijdzone, vault-directory en de lokale poort, standaard 8723.

Twee van deze punten zijn afhankelijkheden die door de "één commando"-benadering worden verborgen. Iva bevat zelf geen model, dus is er een betaald modelabonnement of een API-sleutel nodig voordat het antwoord geeft. Het transcribeert ook zelf geen audio, dus voor spraakberichten is een aparte dienst vereist. Het nova-3-model van Deepgram met DEEPGRAM_LANGUAGE=multi detecteert de taal, en nieuwe Deepgram-accounts ontvangen starttegoed dat maandenlang persoonlijk gebruik dekt. Tekst werkt enkel met de modelsleutel. Alleen spraak is afhankelijk van Deepgram.

Controleer wat de wizard heeft geschreven.

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

ls hoort -rw------- weer te geven, met modus 0600, omdat dat bestand alle sleutels bevat die u zojuist heeft geplakt. TELEGRAM_ALLOWED_USER_IDS moet uw numerieke ID bevatten. De toegangslijst is standaard gesloten (fail closed), dus een lege waarde betekent dat Iva niemand antwoordt.

Het model wordt eenmalig gelezen bij het starten van het proces. Het bewerken van MODEL_PROVIDER of een modelnaam in .env heeft geen effect totdat u iva restart uitvoert. Op openrouter is de modelnaam een vendor-slug zoals anthropic/claude-sonnet-4.5, niet enkel de naam. Op codex is er helemaal geen API-sleutel: iva login logt in op een bestaand ChatGPT-abonnement.

Wat zijn de maandelijkse kosten voor het draaien van Iva

[
  {
    "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
  }
]

Dit zijn de gepubliceerde catalogusprijzen per augustus 2026, geen metingen. Een kleine VPS voor 5 Amerikaanse dollar, plus het OpenCode Go-abonnement voor 5 dollar, vormt de goedkoopste complete opstelling; dit kost ongeveer 10 dollar per maand. Ollama Cloud is de andere optie met een vast tarief van 20 dollar, waarbij de frontier-modellen als extra verbruik boven op het abonnement worden gefactureerd. Spraak kost 0 zolang de Deepgram-startercredits toereikend zijn.

OpenRouter staat hier niet in de lijst omdat dit een pay-as-you-go-model is; uw factuur volgt dus uw verbruik. Dit is de optie om in de gaten te houden: een assistent die bij elke beurt een contextvenster van 131072 tokens meeneemt, kan de kosten van een vast abonnement snel overstijgen. Stel de variabele voor het contextvenster in op de werkelijke grootte van het model, aangezien een te hoge waarde alleen maar tokens verspilt.

De twee services en de twee timers

• iva.service voert de agent zelf uit.
• iva-telegram-poll.service voert de long polling bridge uit die communiceert met Telegram.
• iva-memory-doctor.timer wordt om 05:00 geactiveerd en voert de nachtelijke onderhoudsronde uit over de vault.
• iva-update-check.timer wordt om 10:00 geactiveerd en controleert of er een nieuwere release beschikbaar is.
• iva-telegram-userbot.service bestaat alleen als u de optionele Telethon proxy heeft geconfigureerd.

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

iva status rapporteert beide services en beide watchdog-timers. systemctl --user list-timers toont de volgende uitvoeringstijd voor elke timer; hiermee bevestigt u dat de memory doctor vannacht daadwerkelijk zal draaien. Beide services horen in de status active (running) te staan. Als een service in een lus blijft herstarten, geeft journalctl --user -u iva.service -n 100 de reden aan.

Deze splitsing is van belang bij het debuggen. De bridge kan actief zijn en pollen terwijl de agent offline is; in dat geval accepteert Telegram uw bericht, maar volgt er geen antwoord. iva logs poll volgt de bridge, iva logs volgt de agent; de twee logs vertellen u dus welk deel defect is.

Waar de Obsidian vault zich bevindt en hoe u hiervan een back-up maakt

ASSISTANT_VAULT_DIR staat standaard ingesteld op vault binnen de installatiemap, waardoor het geheugen zich op ~/iva/vault bevindt. Het is een eigen git-repository, los van de code, waardoor u Iva kunt bijwerken zonder uw notities aan te passen.

• vault/CORE.md bevat duurzame feiten en vaste voorkeuren, beperkt tot 1200 tekens, en wordt bij elke systeem-prompt meegestuurd.
• vault/daily/YYYY-MM-DD.md is het transcript van de dag, dat uitsluitend wordt aangevuld.
• vault/cards/ bevat getypte kaarten voor contacten, projecten, beslissingen, ideeën en notities.
• vault/summaries/daily/, weekly/, monthly/ en yearly/ bevatten de rollups.
• vault/attachments/ bevat bestanden op datum en vault/.graph/ bevat de link-graaf.
• vault/schema.json definieert de kaarttypen en de vervalregels.

Rollups worden volgens een schema binnen het proces uitgevoerd. De dagelijkse run om 04:00 uur zet het transcript van gisteren om in kaarten en een samenvatting en herschrijft CORE.md. Daarna comprimeren de wekelijkse, maandelijkse en jaarlijkse runs deze op hun beurt. Om 05:00 uur voert de memory doctor een deterministische run uit zonder tussenkomst van een model: deze dwingt het schema af, herbouwt de link-graaf, genereert de index opnieuw en voert vervolgens een commit en push uit.

Die push is uw back-up, en dit is de stap die mensen vaak vergeten. Als de vault geen git-remote heeft, probeert de doctor een privé GitHub-repository aan te maken via gh, waarvoor een geauthenticeerde GitHub CLI nodig is.

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

Een commit met de datum van vandaag betekent dat de run is voltooid en de vault is vastgelegd. gh not available-waarschuwingen in het logboek betekenen het tegenovergestelde: de vault wordt onderhouden maar verlaat de server nooit, waardoor een defecte VPS uw geheugen meeneemt.

Houd zelf ook een kopie bij die u beheert.

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

Kopieer dat bestand van de server met scp en verwijder het daarna van de server. Om het geheugen in Obsidian te lezen, wijst u Obsidian naar een kloon van de vault-repository. Wikilinks en backlinks werken zoals ze zijn, evenals de grafiekweergave. Het handmatig bewerken van kaarten en CORE.md is veilig. Laat MOC.md en .graph/ met rust, omdat de nachtelijke run beide opnieuw genereert.

Behandel de vault als een logboek van uw leven

Die directory is een gedateerd verslag van wat u zei, wie u ontmoette en wat u besloot, op een machine die u huurt. Hieruit volgen twee zaken.

Self-hosting verplaatst de opslag, niet de verwerking. Elke beurt gaat naar uw modelprovider en elke spraaknotitie gaat naar Deepgram. De vault is van u. De verzoeken zijn niet privé ten opzichte van de bedrijven die ze verwerken. Het zelf draaien van de geheugenlaag, zoals bij een Mem0 memory server op uw eigen VPS, heeft dezelfde vorm: de opslag is lokaal, terwijl de modelaanroep het systeem nog steeds verlaat. Als een onderwerp te gevoelig is voor een derde partij, houd het dan buiten de chat.

Het bereik van dat account is de gehele vault. De tools van Iva draaien host-native via fs en child_process van Node, zonder Docker en zonder sandbox, dus een gekaapte beurt heeft alle rechten die de service-gebruiker heeft. Daarom bevat het account na de installatie geen sudo, en daarom verdient de allowlist meer aandacht dan het lijkt: het is de poort die bepaalt wiens berichten commando's op uw server worden. Als u de assistent in uw broekzak wilt hebben zonder iets open te stellen, is dit hetzelfde patroon als wordt gebruikt om een self-hosted Hermes agent vanaf uw telefoon te bereiken, waarbij de chatclient het werk doet dat anders door een publiek eindpunt zou worden gedaan.

Wat gaat er mis en welke melding krijgt u te zien

Build killed, exit 137. De out-of-memory killer van de kernel heeft het build-proces beëindigd. Het installatieprogramma voegt alleen swap toe als het RAM-geheugen minder dan 1.5 GB bedraagt en er nog geen swap bestaat; voeg deze dus zelf toe en voer het installatieprogramma opnieuw uit.

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

Failed to connect to bus. Elk systemctl --user-commando geeft deze melding als de shell geen gebruikerssessie-bus heeft, wat precies is wat sudo -iu iva u biedt. Open een normale SSH-sessie als die gebruiker, of exporteer XDG_RUNTIME_DIR=/run/user/$(id -u iva) voordat u het commando uitvoert.

De bot reageert niet op u. TELEGRAM_ALLOWED_USER_IDS is leeg en de allowlist is standaard gesloten (fail closed). Stuur de bot een bericht: deze antwoordt met uw numerieke ID en niets anders. Plaats dat ID in .env en voer iva restart uit.

De bot wordt stil direct na iva config. De wizard kan IVA_PORT verplaatsen zonder ASSISTANT_HOST bij te werken, waardoor de bridge verbinding maakt met een poort waar niemand luistert. Vergelijk de twee regels en start daarna opnieuw op.

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

Een spraakbericht krijgt geen antwoord. De Telegram Bot API weigert bestandsdownloads groter dan 20 MB, waardoor de bridge geen audio ontvangt en dus niets naar Deepgram kan sturen. Splits het bestand voordat u het verstuurt.

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

Een beurt (turn) blijft hangen en antwoordt niet. Een vastgelopen workflow-status overleeft een herstart en wordt opnieuw in de wachtrij geplaatst; alleen herstarten lost dit dus niet op. iva reset plaatst die status in quarantaine en herstart beide services. /new in de chat start een nieuw gesprek.

Chromium faalt op Ubuntu 24.04. Ubuntu 24.04 blokkeert unprivileged user namespaces via AppArmor, waardoor de sandbox van Chromium niet kan starten en agent-browser faalt. Het installatieprogramma omzeilt dit door "--no-sandbox" naar ~/.agent-browser/config.json te schrijven. Wees u ervan bewust dat dit aanwezig is. Het verlaagt de isolatie van de browser, wat een extra reden is waarom het account niets anders dan Iva zou moeten bezitten.

FAQ

Heb ik een domein of een open poort nodig om Iva zelf te hosten?

Nee. Iva communiceert met Telegram via long polling: iva-telegram-poll.service roept getUpdates aan en wacht, waardoor elke verbinding uitgaand is vanaf uw server. Er hoeft niets van buitenaf de server te bereiken, dus u heeft geen DNS-record of certificaat nodig. De eigen HTTP-poort van de agent, 8723, bindt aan 127.0.0.1, en de projectdocumentatie adviseert nadrukkelijk om deze niet bloot te stellen aan het internet. Een firewall die enkel SSH toestaat, is de juiste configuratie.

Wat kost het om Iva maandelijks te draaien?

Op basis van de gepubliceerde prijslijst van augustus 2026 kost een kleine VPS 5 dollar, plus het goedkoopste vaste tariefplan van 5 dollar, wat neerkomt op ongeveer 10 Amerikaanse dollar per maand. Ollama Cloud kost in plaats daarvan 20 dollar, waarbij frontier-modellen apart worden gefactureerd. Deepgram starter-credits dekken in eerste instantie de spraakverwerking, en de webzoek-tiers bieden gratis gebruiksmogelijkheden. OpenRouter werkt op basis van verbruik, waardoor er geen vast maandelijks bedrag is.

Waar bewaart Iva mijn gegevens en hoe maak ik een back-up?

Standaard in ~/iva/vault, ingesteld via ASSISTANT_VAULT_DIR. Het is een afzonderlijke private git-repository met platte markdown-bestanden: CORE.md, daily/YYYY-MM-DD.md, cards/ en summaries/. De memory doctor voert om 05:00 uur een commit en push uit, wat alleen werkt als de repository een remote heeft; voer daarom gh auth login uit of voeg tijdens de installatie zelf een remote toe. Bewaar daarnaast een offline kopie met tar czf ~/iva-vault-backup.tgz -C ~/iva vault en verplaats dat bestand van de server af.

Zijn mijn gegevens privé als ik Iva zelf host?

De opslag is van u. De verwerking niet. De kluis blijft op uw schijf staan totdat u deze pusht, en .env heeft de modus 0600 en is eigendom van de servicegebruiker. Modelaanroepen en spraaktranscriptie verlopen via cloud-API's, waardoor die berichten via uw modelprovider en Deepgram gaan. Iva is MIT-gelicentieerd, dus u kunt precies inzien wat er wordt verzonden en dit aanpassen. De Telegram-allowlist is 'fail closed', wat betekent dat een lege TELEGRAM_ALLOWED_USER_IDS iedereen blokkeert, inclusief uzelf.

Welke modelproviders ondersteunt Iva?

MODEL_PROVIDER accepteert opencode (OpenCode Go), ollama (Ollama Cloud), openrouter en codex. OpenRouter accepteert een vendor-slug zoals anthropic/claude-sonnet-4.5 en biedt de ruimste keuze aan modellen. codex logt in op een bestaand ChatGPT-abonnement met iva login en gebruikt geen API-sleutel. Stel de provider in, stel het bijbehorende contextvenster in op de werkelijke grootte van het model en voer daarna iva restart uit, omdat het model slechts eenmaal wordt ingelezen bij het starten van het proces.