Iva selbst hosten: Telegram-KI-Assistent auf kleinem VPS

Was Sie aufbauen

Iva ist ein selbst gehosteter Telegram-KI-Assistent. Die Anwendung lässt sich ohne eingehenden Port und ohne Domain bereitstellen. Es ist auch kein Zertifikat erforderlich, weil auf dem Server kein Dienst auf öffentliche Verbindungen wartet. Der Dienst baut die Verbindung zu Telegram ausgehend auf, hält sie offen und liest Ihre Nachrichten aus der Antwort. Alles Weitere ergibt sich aus dieser einen ausgehenden Verbindung.

Iva steht unter der MIT-Lizenz und ist in Node geschrieben. Der Speicher besteht aus einfachen Markdown-Dateien, die Obsidian direkt öffnet. Die Notizen, die Iva über Sie speichert, bleiben daher auch ohne die Anwendung lesbar. Diese Anleitung verwendet Release v0.3.13, veröffentlicht am 6. August 2026.

Die meisten selbst gehosteten Anwendungen beginnen mit einem DNS-Eintrag (Domain Name System) und einem mit Certbot ausgestellten Let's-Encrypt-Zertifikat. Iva verwendet diese Schicht überhaupt nicht. Deshalb reicht ein kleiner VPS hinter einer Firewall, die nur SSH zulässt, für eine vollständige Bereitstellung aus.

Warum Iva keine offenen Ports benötigt

iva-telegram-poll.service ist eine Long-Polling-Bridge. Sie ruft die getUpdates-API von Telegram auf und wartet auf die Antwort. Daher wird jede Verbindung von Ihrem Server aus gestartet. Telegram stellt keine Rückverbindung her. Sie müssen daher weder einen Reverse Proxy konfigurieren noch an die Zertifikatserneuerung denken.

Der Agent lauscht selbst, jedoch ausschließlich auf dem 127.0.0.1-Port 8723. Die Projektdokumentation formuliert es eindeutig: Port 8723 darf nicht veröffentlicht werden. Ein vorgeschalteter Reverse Proxy muss außerdem die Anforderung eines Bearer-Tokens beibehalten. Prüfen Sie die Bind-Adresse nach der Installation.

sudo ss -tlnp | grep 8723

Die Adresse muss 127.0.0.1:8723 lauten. Eine Wildcard-Adresse wie 0.0.0.0:8723 bedeutet, dass die HTTP-Routen des Agents aus dem Internet erreichbar sind. Beheben Sie das, bevor Sie dem Bot private Daten senden.

Die Firewall bleibt daher geschlossen. Erlauben Sie SSH, bevor Sie sie aktivieren. ufw enable ohne eine SSH-Regel beendet die Sitzung, in der Sie gerade Befehle eingeben.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Was der einzeilige Installer tatsächlich macht

Die Startseite des Projekts enthält einen Befehl, der ein Skript von GitHub an bash weiterleitet. Lesen Sie das Skript zuerst, denn es installiert deutlich mehr als nur ein Programm.

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

• Das Skript installiert Systempakete mit dem erkannten Paketmanager: git, gh, python3, ffmpeg, pandoc und poppler-utils.
• Wenn der Server weniger als 1.5 GB RAM und keinen Swap hat, erstellt es unter /swapfile eine 2-GB-Swap-Datei. Ohne Swap wird der Build-Prozess beendet.
• Es installiert nvm und anschließend Node 24. Das ist die Mindestversion, die Iva benötigt.
• Es installiert uv, den Python-Paketmanager, unter ~/.local/bin.
• Es klont das Repository nach ~/iva und führt npm ci aus.
• Es installiert zwei globale npm-Pakete: agent-browser, das anschließend Chromium herunterlädt, und @googleworkspace/cli.
• Es führt den Setup-Assistenten aus, erstellt den Build des Projekts und legt den Vault an.
• Es schreibt einen iva-Befehl in ~/.local/bin und installiert die systemd-User-Units.

Das ist eine große Menge Software für eine einzige Befehlszeile. Das erklärt auch die Anweisung in der README, die Installation als normaler Benutzer und nicht als root auszuführen: Das Shell-Tool des Agenten läuft später mit den Berechtigungen, die beim Ausführen des Installers verwendet wurden. Das Skript ruft sudo nur für die Paketinstallation und die Swap-Datei auf. Dafür verwendet es einen Helfer, der Befehle direkt ausführt, wenn Sie bereits root sind.

Einen dedizierten Benutzer vor der Installation anlegen

Geben Sie Iva ein eigenes Konto. Der Agent führt über Node's child_process Shell-Befehle auf dem Host aus. Dabei werden weder ein Container noch eine Sandbox verwendet. Das Konto, unter dem der Agent ausgeführt wird, bildet daher die Sicherheitsgrenze.

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 ist erforderlich, weil Iva als systemd-Benutzereinheiten ausgeführt wird. Ohne Linger beendet systemd die Dienste dieses Benutzers, sobald dessen letzte Sitzung endet. Der Assistent würde daher beendet, sobald Sie die SSH-Verbindung schließen. Dieselbe Regel gilt für jeden Dienst und Timer, den Sie selbst unter systemd erstellen.

Das Konto benötigt sudo nur, solange das Installationsprogramm Pakete hinzufügt. Entziehen Sie die Berechtigung nach Abschluss der Installation wieder.

sudo deluser iva sudo

Melden Sie sich direkt per SSH als dieser Benutzer an. Eine Shell, die Sie mit sudo -iu iva öffnen, enthält weder DBUS_SESSION_BUS_ADDRESS noch XDG_RUNTIME_DIR. Daher schlägt jeder systemctl --user-Befehl mit Failed to connect to bus fehl. Diese Abgrenzung entspricht dem Ausführen von Diensten unter Benutzern mit den geringsten erforderlichen Berechtigungen.

Eine festgelegte Version installieren, statt sie an bash weiterzuleiten

Das Installationsprogramm hat eine nützliche Eigenschaft. Bevor es etwas klont, prüft es, ob das Verzeichnis, in dem das Skript liegt, bereits ein package.json mit "eve" enthält. Ist das der Fall, erstellt es diesen Checkout und überspringt das Klonen. Sie können die Version daher selbst auswählen.

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

Jetzt wissen Sie, welcher Code ausgeführt wird. Das wissen Sie nicht, wenn das Skript main in dem Zustand klont, in dem es sich zu diesem Zeitpunkt gerade befindet. Iva hat zwischen dem 4. und 6. August 2026 fünf Releases veröffentlicht. Daher sind main heute Morgen und main heute Nachmittag nicht dasselbe Programm.

Ein Checkout eines Tags versetzt git in einen Zustand mit detached HEAD. Das funktioniert problemlos. Beachten Sie jedoch die Einschränkung: iva update verschiebt den Checkout auf den Update-Branch. Die festgelegte Version ist daher ein bekannter Ausgangspunkt und keine dauerhafte Sperre. iva version gibt die Paketversion und den git-Commit aus. So sehen Sie jederzeit, auf welchem Stand Sie sich befinden.

Um gezielt zu einem späteren Release zu wechseln, listen Sie die Tags auf, setzen IVA_TAG auf den ausgewählten Tag und führen das Installationsprogramm anschließend erneut innerhalb des Checkouts aus.

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 verhindert, dass der Assistent erneut über einem bereits funktionierenden .env ausgeführt wird.

Die fünf Schritte des Assistenten und die abgefragten Schlüssel

1. Modellanbieter und Modell. MODEL_PROVIDER akzeptiert opencode, ollama, openrouter oder codex. Der Assistent prüft den Schlüssel direkt und listet die Modelle auf, die Ihr Tarif anbietet.
2. Spracheingabe und Suche. Ein Deepgram-Schlüssel transkribiert Sprachnachrichten. Ein Schlüssel für die Websuche (Tavily, Exa, Parallel oder Brave) ist optional.
3. Telegram-Bot-Token von @BotFather, geprüft gegen den Endpunkt getMe.
4. Zugriffskontrolle. Sie senden Ihrem Bot eine Nachricht, und der Assistent liest Ihre numerische Benutzer-ID aus getUpdates.
5. Systemeinstellungen. IANA-Zeitzone, Vault-Verzeichnis und der lokale Port, standardmäßig 8723.

Zwei dieser Punkte sind Abhängigkeiten, die die Formulierung "ein Befehl" verschleiert. Iva enthält kein Modell. Daher benötigen Sie einen kostenpflichtigen Modelltarif oder einen API-Schlüssel, bevor Iva antworten kann. Außerdem transkribiert Iva Audiodateien nicht selbst. Sprachnachrichten benötigen daher einen separaten Dienst. Das Deepgram-Modell nova-3 erkennt mit DEEPGRAM_LANGUAGE=multi die Sprache. Neue Deepgram-Konten erhalten Startguthaben, das für mehrere Monate der persönlichen Nutzung ausreicht. Text funktioniert allein mit dem Modellschlüssel. Nur Spracheingaben hängen von Deepgram ab.

Prüfen Sie, was der Assistent geschrieben hat.

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

ls sollte -rw------- ausgeben und den Modus 0600 haben, da diese Datei alle gerade eingefügten Schlüssel enthält. TELEGRAM_ALLOWED_USER_IDS muss Ihre numerische ID enthalten. Die Allowlist verweigert standardmäßig den Zugriff. Ein leerer Wert bedeutet daher, dass Iva niemandem antwortet.

Das Modell wird einmal beim Prozessstart eingelesen. Änderungen an MODEL_PROVIDER oder an einem Modellnamen in .env haben keine Wirkung, bis Sie iva restart ausführen. Bei openrouter ist der Modellname ein anbieterspezifischer Slug wie anthropic/claude-sonnet-4.5, kein einfacher Name. Bei codex gibt es überhaupt keinen API-Schlüssel: iva login meldet sich bei einem vorhandenen ChatGPT-Abonnement an.

Was kostet der Betrieb von Iva pro Monat

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

Dies sind veröffentlichte Listenpreise mit Stand August 2026, keine Messwerte. Ein kleiner VPS für 5 US-Dollar plus der OpenCode-Go-Tarif für 5 US-Dollar ist die günstigste vollständige Konfiguration und kostet etwa 10 US-Dollar pro Monat. Ollama Cloud ist mit 20 US-Dollar die andere Option mit Pauschalpreis. Die Frontier-Modelle werden zusätzlich zum Tarif nach Nutzung abgerechnet. Voice kostet 0, solange die Startguthaben von Deepgram ausreichen.

OpenRouter wird hier nicht aufgeführt, weil der Dienst nutzungsbasiert abgerechnet wird. Ihre Rechnung richtet sich daher nach Ihrer Nutzung. Diese Option müssen Sie besonders überwachen: Ein Assistent, der in jede Anfrage ein Kontextfenster mit 131072 Tokens übernimmt, kann einen Pauschaltarif schnell übersteigen. Setzen Sie die Variable für das Kontextfenster auf die tatsächliche Größe des Modells. Ein zu hoch gesetzter Wert verbraucht lediglich unnötig Tokens.

Die beiden Dienste und die beiden Timer

• iva.service führt den Agenten selbst aus.
• iva-telegram-poll.service führt die Long-Polling-Bridge aus, die mit Telegram kommuniziert.
• iva-memory-doctor.timer wird um 05:00 ausgeführt und startet den nächtlichen Wartungslauf für den Vault.
• iva-update-check.timer wird um 10:00 ausgeführt und prüft, ob ein neueres Release verfügbar ist.
• iva-telegram-userbot.service ist nur vorhanden, wenn Sie den optionalen Telethon-Proxy eingerichtet haben.

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

iva status zeigt den Status beider Dienste und beider Watchdog-Timer an. systemctl --user list-timers gibt die nächste Ausführungszeit jedes Timers aus. Damit prüfen Sie, ob der Memory Doctor heute Nacht tatsächlich ausgeführt wird. Beide Dienste sollten sich im Status active (running) befinden. Wenn einer der Dienste in einer Neustartschleife läuft, zeigt journalctl --user -u iva.service -n 100 den Grund an.

Die Aufteilung ist beim Debugging wichtig. Die Bridge kann aktiv sein und Anfragen abholen, während der Agent beendet ist. Dann nimmt Telegram Ihre Nachricht an, aber es antwortet niemand. iva logs poll überwacht die Bridge, iva logs überwacht den Agenten. Anhand der beiden Logs sehen Sie, welcher Teil fehlerhaft ist.

Wo das Obsidian-Vault liegt und wie Sie es sichern

ASSISTANT_VAULT_DIR verwendet standardmäßig vault im Installationsverzeichnis. Der Speicher liegt daher unter ~/iva/vault. Er ist ein eigenes Git-Repository und vom Code getrennt. Dadurch können Sie Iva aktualisieren, ohne Ihre Notizen zu verändern.

• vault/CORE.md enthält dauerhafte Fakten und grundlegende Präferenzen. Der Inhalt ist auf 1200 Zeichen begrenzt und wird in jeden System-Prompt übernommen.
• vault/daily/YYYY-MM-DD.md ist das Transkript des Tages und wird ausschließlich angehängt.
• vault/cards/ enthält typisierte Karten für Kontakte, Projekte, Entscheidungen, Ideen und Notizen.
• vault/summaries/daily/, weekly/, monthly/ und yearly/ enthalten die Zusammenfassungen.
• vault/attachments/ enthält Dateien nach Datum. vault/.graph/ enthält den Link-Graphen.
• vault/schema.json definiert die Kartentypen und die Regeln für den Abbau.

Die Zusammenfassungen werden innerhalb des Prozesses nach einem Zeitplan erstellt. Der tägliche Lauf um 04:00 wandelt das Transkript des Vortags in Karten und eine Zusammenfassung um und schreibt CORE.md neu. Anschließend komprimieren die wöchentlichen, monatlichen und jährlichen Läufe diese Daten jeweils weiter. Um 05:00 führt der Memory Doctor einen deterministischen Lauf ohne Modell aus. Er erzwingt das Schema, erstellt den Link-Graphen neu, generiert den Index neu und führt anschließend Commit und Push aus.

Dieser Push ist Ihr Backup. Dieser Schritt wird häufig übersehen. Wenn für das Vault kein Git-Remote konfiguriert ist, versucht der Doctor, über gh ein privates GitHub-Repository zu erstellen. Dafür ist eine authentifizierte GitHub CLI erforderlich.

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

Ein heute datierter Commit bedeutet, dass der Lauf ausgeführt und das Vault committed wurde. gh not available-Warnungen im Log bedeuten das Gegenteil: Das Vault wird zwar gepflegt, verlässt den Server aber nie. Wenn der VPS ausfällt, geht Ihr Speicher daher mit verloren.

Bewahren Sie zusätzlich eine Kopie unter Ihrer Kontrolle auf.

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

Kopieren Sie diese Datei mit scp vom Server weg. Löschen Sie sie anschließend vom Server. Um den Speicher in Obsidian zu lesen, verweisen Sie Obsidian auf einen Clone des Vault-Repositorys. Wikilinks, Backlinks und auch die Graphansicht funktionieren unverändert. Das manuelle Bearbeiten von Karten und CORE.md ist sicher. Lassen Sie MOC.md und .graph/ unverändert, da der nächtliche Lauf beide Dateien neu generiert.

Behandeln Sie den Tresor als Protokoll Ihres Lebens

Dieses Verzeichnis ist eine datierte Aufzeichnung dessen, was Sie gesagt, wen Sie getroffen und was Sie entschieden haben – auf einer von Ihnen gemieteten Maschine. Daraus ergeben sich zwei Punkte.

Self-Hosting verlagert den Speicher, nicht die Verarbeitung. Jede Eingabe geht an Ihren Modellanbieter, und jede Sprachnotiz geht an Deepgram. Der Tresor gehört Ihnen. Die Anfragen bleiben für die Unternehmen, die sie verarbeiten, nicht privat. Wenn Sie die Speicherschicht selbst betreiben, etwa mit einem Mem0-Speicherserver auf Ihrem eigenen VPS, ist das Prinzip identisch: Der Speicher bleibt lokal, während der Modellaufruf die Maschine weiterhin verlässt. Wenn ein Thema für einen Drittanbieter zu sensibel ist, halten Sie es aus dem Chat heraus.

Der Zugriff dieses Kontos erstreckt sich auf den gesamten Tresor. Ivas Tools laufen über Nodes fs und child_process direkt auf dem Host, ohne Docker und ohne Sandbox. Eine kompromittierte Eingabe verfügt daher über alle Berechtigungen, die der Dienstbenutzer besitzt. Deshalb enthält das Konto nach der Installation keine sudo. Deshalb verdient die Allowlist mehr Aufmerksamkeit, als es zunächst den Anschein hat: Sie ist das Gate, das entscheidet, wessen Nachrichten zu Befehlen auf Ihrem Server werden. Wenn Sie den Assistenten bei sich haben möchten, ohne etwas zu öffnen, ist dies dasselbe Muster wie beim Zugriff auf einen selbst gehosteten Hermes-Agenten vom Telefon aus. Dabei übernimmt der Chat-Client die Aufgabe, die andernfalls ein öffentlicher Endpunkt erfüllen würde.

Was fehlschlägt und welche Meldung Sie sehen

Build abgebrochen, Exit-Code 137. Der Out-of-Memory-Killer des Kernels hat den Build beendet. Das Installationsprogramm fügt Swap nur hinzu, wenn weniger als 1.5 GB RAM vorhanden sind und kein Swap existiert. Richten Sie den Swap daher selbst ein und führen Sie das Installationsprogramm erneut aus.

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

Failed to connect to bus. Jeder systemctl --user-Befehl gibt diese Meldung aus, wenn für die Shell kein Benutzer-Session-Bus vorhanden ist. Diesen stellt sudo -iu iva bereit. Öffnen Sie als dieser Benutzer eine normale SSH-Sitzung oder exportieren Sie vor dem Befehl XDG_RUNTIME_DIR=/run/user/$(id -u iva).

Der Bot reagiert nicht. TELEGRAM_ALLOWED_USER_IDS ist leer, und die Allowlist verweigert standardmäßig alle Zugriffe. Senden Sie dem Bot eine Nachricht. Er antwortet mit Ihrer numerischen ID und nichts anderem. Tragen Sie diese ID in .env ein und führen Sie iva restart aus.

Der Bot verstummt direkt nach iva config. Der Assistent kann IVA_PORT verschieben, ohne ASSISTANT_HOST zu aktualisieren. Dadurch verbindet sich die Bridge mit einem Port, an dem kein Dienst antwortet. Vergleichen Sie die beiden Zeilen und starten Sie anschließend neu.

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

Eine Sprachnachricht erhält keine Antwort. Die Telegram Bot API verweigert Dateidownloads über 20 MB. Daher empfängt die Bridge lange Audiodateien nicht und kann nichts an Deepgram senden. Teilen Sie die Datei, bevor Sie sie senden.

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

Ein Durchlauf hängt und antwortet nicht. Ein blockierter Workflow-Zustand bleibt nach einem Neustart erhalten und wird erneut in die Warteschlange gestellt. Ein alleiniger Neustart entfernt ihn daher nicht. iva reset verschiebt diesen Zustand in Quarantäne und startet beide Dienste neu. /new im Chat startet eine neue Unterhaltung.

Chromium schlägt unter Ubuntu 24.04 fehl. Ubuntu 24.04 blockiert nicht privilegierte User Namespaces durch AppArmor. Daher kann Chromium seine eigene Sandbox nicht starten, und agent-browser schlägt fehl. Das Installationsprogramm umgeht dies, indem es "--no-sandbox" in ~/.agent-browser/config.json schreibt. Beachten Sie diese Einstellung. Sie verringert die Isolation des Browsers. Das ist ein weiterer Grund dafür, dass der Account außer Iva nichts besitzen sollte.

FAQ

Do I need a domain or an open port to self-host Iva?

No. Iva talks to Telegram by long polling: iva-telegram-poll.service calls getUpdates and waits, so every connection is outbound from your server. Nothing has to reach the box from outside, so you need no DNS record and no certificate. The agent's own HTTP port, 8723, binds to 127.0.0.1, and the project documentation tells you not to expose it. A firewall that allows SSH and nothing else is the correct configuration.

What does it cost to run Iva each month?

At published August 2026 list prices, a small VPS at 5 dollars plus the cheapest flat rate model plan at 5 dollars comes to about 10 US dollars a month. Ollama Cloud costs 20 dollars instead, and bills frontier models on top. Deepgram starter credits cover voice at first, and the web search tiers have free allowances. OpenRouter is pay as you go, so it has no fixed monthly figure.

Where does Iva keep my data, and how do I back it up?

In ~/iva/vault by default, set by ASSISTANT_VAULT_DIR. It is a separate private git repository of plain markdown: CORE.md, daily/YYYY-MM-DD.md, cards/ and summaries/. The 05:00 memory doctor commits and pushes it, which only helps if the repository has a remote, so run gh auth login or add a remote of your own during setup. Keep an offline copy as well with tar czf ~/iva-vault-backup.tgz -C ~/iva vault and move that file off the server.

Is my data private if I self-host Iva?

The storage is yours. The processing is not. The vault stays on your disk until you push it, and .env sits at mode 0600 owned by the service user. Model calls and voice transcription are cloud APIs, so those messages transit your model provider and Deepgram. Iva is MIT licensed, so you can read exactly what it sends and change it. The Telegram allowlist is fail closed, which means an empty TELEGRAM_ALLOWED_USER_IDS blocks everyone, including you.

Which model providers does Iva support?

MODEL_PROVIDER accepts opencode (OpenCode Go), ollama (Ollama Cloud), openrouter and codex. OpenRouter takes a vendor slug such as anthropic/claude-sonnet-4.5 and offers the widest choice of models. codex signs in to an existing ChatGPT subscription with iva login and uses no API key. Set the provider, set the matching context window to the model's real size, then run iva restart, because the model is read once at process start.