Jak zainstalować Iva Telegram AI na własnym serwerze

Co budujesz

Iva to samodzielnie hostowany asystent AI dla Telegrama. Jest to jedno z niewielu rozwiązań, które można wdrożyć bez otwierania portów przychodzących i bez wskazywania na nie domeny. Nie wymaga również certyfikatu, ponieważ żaden proces na serwerze nie nasłuchuje połączeń publicznych. Usługa nawiązuje połączenie wychodzące do Telegrama, utrzymuje je i odczytuje wiadomości z odpowiedzi. Cała reszta funkcjonalności wynika z tego jednego połączenia wychodzącego.

Iva jest udostępniana na licencji MIT i napisana w Node. Jej pamięć stanowi folder ze zwykłymi plikami markdown, które można otwierać bezpośrednio w Obsidian, dzięki czemu notatki pozostają czytelne nawet bez użycia aplikacji. Niniejszy przewodnik dotyczy wersji v0.3.13, opublikowanej 6 sierpnia 2026.

Większość samodzielnie hostowanego oprogramowania wymaga rekordu DNS (domain name system) oraz certyfikatu Let's Encrypt wystawionego za pomocą Certbot. Iva całkowicie pomija tę warstwę, dlatego mały VPS za firewallem, który zezwala jedynie na ruch SSH, jest w pełni wystarczającym środowiskiem wdrożeniowym.

Dlaczego Iva nie wymaga otwartych portów

iva-telegram-poll.service to most typu long polling. Łączy się on z API getUpdates serwisu Telegram i oczekuje na odpowiedź, dlatego każde połączenie inicjowane jest z poziomu serwera użytkownika. Telegram nigdy nie nawiązuje połączenia zwrotnego, co oznacza brak konieczności konfiguracji reverse proxy oraz zarządzania odnawianiem certyfikatów.

Sam agent nasłuchuje wyłącznie na porcie 127.0.0.1 8723. Dokumentacja projektu jest w tej kwestii jednoznaczna: nie należy wystawiać portu 8723 na zewnątrz, a każde reverse proxy umieszczone przed nim musi egzekwować wymóg posiadania tokena bearer. Po instalacji należy sprawdzić adres powiązania (bind address).

sudo ss -tlnp | grep 8723

Adres musi wskazywać na 127.0.0.1:8723. Adres typu wildcard, taki jak 0.0.0.0:8723, oznacza, że trasy HTTP agenta są dostępne z poziomu Internetu; należy to naprawić przed przesyłaniem botowi jakichkolwiek prywatnych danych.

W związku z tym firewall pozostaje zamknięty. Przed jego włączeniem należy zezwolić na ruch SSH, ponieważ ufw enable bez reguły dla SSH spowoduje zerwanie aktywnej sesji.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Co faktycznie wykonuje instalator jednowierszowy

Strona główna projektu udostępnia jedno polecenie, które przesyła skrypt z GitHub bezpośrednio do bash. Należy najpierw zapoznać się z treścią skryptu, ponieważ wykonuje on znacznie więcej operacji niż tylko instalację jednego programu.

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

• Instaluje pakiety systemowe za pomocą wykrytego menedżera pakietów: git, gh, python3, ffmpeg, pandoc oraz poppler-utils.
• Tworzy plik wymiany (swapfile) o rozmiarze 2 GB w /swapfile, jeśli serwer posiada mniej niż 1.5 GB pamięci RAM i brak skonfigurowanego swapu, ponieważ w przeciwnym razie proces budowania zostanie przerwany.
• Instaluje nvm, a następnie Node 24, czyli minimalną wersję wymaganą do działania Iva.
• Instaluje uv, menedżer pakietów Python, w lokalizacji ~/.local/bin.
• Klonuje repozytorium do ~/iva i uruchamia npm ci.
• Instaluje dwa globalne pakiety npm: agent-browser (który następnie pobiera Chromium) oraz @googleworkspace/cli.
• Uruchamia kreator konfiguracji, buduje projekt i tworzy skarbiec (vault).
• Zapisuje polecenie iva w ~/.local/bin i instaluje jednostki systemd dla użytkownika.

To duża ilość oprogramowania jak na jedno polecenie. Wyjaśnia to również zalecenie z pliku README, aby instalację przeprowadzać jako zwykły użytkownik, a nie jako root: narzędzie powłoki agenta działa później z uprawnieniami, które posiadał instalator. Skrypt wywołuje sudo tylko w celu instalacji pakietów oraz utworzenia pliku wymiany, korzystając z pomocnika wykonującego polecenia bezpośrednio, jeśli użytkownik posiada już uprawnienia root.

Utworzenie dedykowanego użytkownika przed instalacją

Należy utworzyć osobne konto dla Iva. Agent wykonuje polecenia powłoki na hoście za pośrednictwem child_process środowiska Node, bez kontenera i piaskownicy, dlatego konto, na którym działa, stanowi granicę bezpieczeństwa.

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 jest istotne, ponieważ Iva działa jako jednostki user w systemd. Bez włączonego linger, systemd zatrzymuje usługi użytkownika w momencie zakończenia jego ostatniej sesji, co spowodowałoby wyłączenie asystenta po zamknięciu połączenia SSH. Ta sama zasada dotyczy wszystkich usług i timerów tworzonych samodzielnie w systemd.

Konto potrzebuje uprawnień sudo tylko podczas instalacji pakietów przez instalator. Należy je odebrać po zakończeniu instalacji.

sudo deluser iva sudo

Należy zalogować się bezpośrednio na tego użytkownika przez SSH. Powłoka uzyskana za pomocą sudo -iu iva nie ma ustawionych zmiennych DBUS_SESSION_BUS_ADDRESS ani XDG_RUNTIME_DIR, przez co każde polecenie systemctl --user kończy się błędem Failed to connect to bus. Wyznaczenie tej granicy jest tożsame z uruchamianiem usług na kontach z minimalnymi uprawnieniami.

Instalacja przypiętej wersji zamiast potokowania do bash

Instalator posiada użyteczną właściwość. Przed rozpoczęciem klonowania sprawdza, czy katalog, w którym znajduje się skrypt, zawiera już package.json z "eve". Jeśli tak, buduje tę wersję i pomija klonowanie. Dzięki temu można samodzielnie wybrać wersję oprogramowania.

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

Dzięki temu wiadomo, jaki kod jest uruchamiany. Nie można tego stwierdzić, gdy skrypt klonuje main w stanie, w jakim znajduje się ona w danej godzinie. Iva wydała pięć wersji między 4 a 6 sierpnia 2026, więc main dziś rano i main dziś po południu to nie ten sam program.

Wykupienie tagu pozostawia git w stanie detached HEAD. Działa to poprawnie, ale należy pamiętać o ograniczeniu: iva update przenosi checkout na gałąź aktualizacji, więc przypięcie jest znanym punktem startowym, a nie trwałym zamrożeniem. iva version wyświetla wersję pakietu oraz commit git, co pozwala zawsze sprawdzić bieżący stan.

Aby celowo przejść do późniejszej wersji, należy wyświetlić listę tagów, ustawić IVA_TAG na wybrany z nich, a następnie ponownie uruchomić instalator z wnętrza katalogu 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 zapobiega ponownemu uruchomieniu kreatora w przypadku .env, który już działa poprawnie.

Pięć kroków kreatora i wymagane klucze

1. Dostawca modelu i model. MODEL_PROVIDER akceptuje opencode, ollama, openrouter lub codex. Kreator weryfikuje klucz w czasie rzeczywistym i wyświetla listę modeli dostępnych w ramach posiadanego planu.
2. Głos i wyszukiwanie. Klucz Deepgram umożliwia transkrypcję notatek głosowych. Klucz do wyszukiwarki internetowej (Tavily, Exa, Parallel lub Brave) jest opcjonalny.
3. Token bota Telegram uzyskiwany od @BotFather, weryfikowany względem punktu końcowego getMe.
4. Kontrola dostępu. Użytkownik wysyła wiadomość do bota, a kreator odczytuje numeryczny identyfikator użytkownika z getUpdates.
5. Ustawienia systemowe. Strefa czasowa IANA, katalog przechowalni (vault) oraz port lokalny, domyślnie 8723.

Dwa z powyższych punktów to zależności, które są ukryte w założeniu "jednego polecenia". Iva nie zawiera wbudowanego modelu, więc do udzielania odpowiedzi wymaga płatnego planu lub klucza API. Nie dokonuje również samodzielnie transkrypcji dźwięku, dlatego notatki głosowe wymagają oddzielnej usługi. Model nova-3 w Deepgram z opcją DEEPGRAM_LANGUAGE=multi wykrywa język, a nowe konta Deepgram otrzymują środki startowe wystarczające na miesiące użytkowania osobistego. Tekst działa przy użyciu samego klucza modelu. Tylko obsługa głosu zależy od Deepgram.

Sprawdź, co zapisał kreator.

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

ls powinno wyświetlić -rw-------, w trybie 0600, ponieważ ten plik przechowuje wszystkie wklejone klucze. TELEGRAM_ALLOWED_USER_IDS musi zawierać numeryczny identyfikator użytkownika. Lista dozwolonych osób działa w trybie domyślnego odrzucania, więc pusta wartość oznacza, że Iva nie odpowie nikomu.

Model jest odczytywany jednorazowo, podczas uruchamiania procesu. Edycja MODEL_PROVIDER lub nazwy modelu w .env nie przynosi efektu do momentu wykonania iva restart. W openrouter nazwa modelu jest identyfikatorem dostawcy, takim jak anthropic/claude-sonnet-4.5, a nie samą nazwą. W codex nie używa się klucza API: iva login loguje się do istniejącej subskrypcji ChatGPT.

Ile kosztuje miesięczne utrzymanie 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
  }
]

Podane kwoty to oficjalne ceny katalogowe z sierpnia 2026 roku, a nie pomiary rzeczywistego zużycia. Najtańsza kompletna konfiguracja obejmuje mały VPS w cenie 5 dolarów amerykańskich oraz plan OpenCode Go za 5 dolarów, co daje łącznie około 10 dolarów miesięcznie. Ollama Cloud to druga opcja ze stałą stawką wynoszącą 20 dolarów, przy czym modele klasy frontier są rozliczane jako dodatkowe zużycie ponad plan. Koszt obsługi głosowej wynosi 0 do momentu wyczerpania początkowych kredytów Deepgram.

OpenRouter nie został uwzględniony w zestawieniu, ponieważ działa w modelu płatności za faktyczne użycie (pay as you go), więc wysokość rachunku zależy bezpośrednio od aktywności. Jest to opcja wymagająca monitorowania: asystent, który w każdej turze przesyła okno kontekstowe o rozmiarze 131072 tokenów, może szybko przekroczyć koszty planu ze stałą opłatą. Należy ustawić zmienną okna kontekstowego zgodnie z rzeczywistym rozmiarem modelu, ponieważ zawyżona wartość powoduje jedynie niepotrzebne zużycie tokenów.

Dwie usługi i dwa timery

• iva.service uruchamia samego agenta.
• iva-telegram-poll.service uruchamia mostek long polling komunikujący się z Telegram.
• iva-memory-doctor.timer wyzwala się o 05:00 i wykonuje nocną konserwację skarbca.
• iva-update-check.timer wyzwala się o 10:00 i sprawdza, czy dostępna jest nowsza wersja (release).
• iva-telegram-userbot.service istnieje tylko w przypadku skonfigurowania opcjonalnego proxy Telethon.

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

iva status raportuje stan obu usług oraz obu timerów typu watchdog. systemctl --user list-timers wyświetla czas następnego uruchomienia dla każdego timera; w ten sposób można potwierdzić, że procedura naprawy pamięci zostanie wykonana w nocy. Obie usługi powinny znajdować się w stanie active (running). Jeśli jedna z nich restartuje się w pętli, journalctl --user -u iva.service -n 100 wskaże przyczynę.

Podział ten jest istotny podczas debugowania. Mostek może działać i utrzymywać połączenie, podczas gdy agent jest wyłączony; w takiej sytuacji Telegram przyjmie wiadomość, ale żadna usługa na nią nie odpowie. iva logs poll śledzi mostek, a iva logs śledzi agenta, dzięki czemu oba dzienniki pozwalają ustalić, która część systemu uległa awarii.

Lokalizacja skarbca Obsidian i sposób tworzenia jego kopii zapasowych

ASSISTANT_VAULT_DIR domyślnie wskazuje na vault wewnątrz katalogu instalacyjnego, więc pamięć znajduje się w ~/iva/vault. Jest to osobne repozytorium git, niezależne od kodu, co pozwala na aktualizację Iva bez ingerencji w notatki.

• vault/CORE.md przechowuje trwałe fakty i stałe preferencje, ograniczone do 1200 znaków, i jest dołączane do każdego system prompt.
• vault/daily/YYYY-MM-DD.md to transkrypcja z danego dnia, traktowana jako plik typu append-only.
• vault/cards/ zawiera wpisane karty dla kontaktów, projektów, decyzji, pomysłów i notatek.
• vault/summaries/daily/, weekly/, monthly/ oraz yearly/ przechowują podsumowania (rollups).
• vault/attachments/ przechowuje pliki według daty, a vault/.graph/ zawiera graf powiązań.
• vault/schema.json definiuje typy kart oraz zasady ich wygasania.

Podsumowania są uruchamiane zgodnie z harmonogramem wewnątrz procesu. Codzienny przebieg o 04:00 przekształca wczorajszą transkrypcję w karty i podsumowanie, a następnie nadpisuje CORE.md. Kolejno przebiegi tygodniowe, miesięczne i roczne kompresują te dane. O 05:00 uruchamiany jest "lekarz pamięci" (memory doctor), który wykonuje deterministyczny proces bez udziału modelu: wymusza schemat, przebudowuje graf powiązań, regeneruje indeks, a następnie wykonuje commit i push.

Ten push stanowi kopię zapasową i jest to krok, który użytkownicy często pomijają. Jeśli skarbiec nie posiada zdalnego repozytorium git, "lekarz" próbuje utworzyć prywatne repozytorium GitHub poprzez gh, co wymaga uwierzytelnionego GitHub CLI.

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

Commit z dzisiejszą datą oznacza, że proces został wykonany, a skarbiec zapisany. Ostrzeżenia gh not available w dzienniku oznaczają sytuację odwrotną: skarbiec jest utrzymywany, ale nigdy nie opuszcza serwera, więc awaria VPS spowoduje utratę pamięci.

Należy przechowywać również kopię, nad którą sprawuje się pełną kontrolę.

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

Skopiuj ten plik z serwera za pomocą scp, a następnie usuń go z serwera. Aby odczytać pamięć w Obsidian, wskaż Obsidianowi klon repozytorium skarbca. Wikilinki i backlinki działają bez zmian, podobnie jak widok grafu. Ręczna edycja kart oraz CORE.md jest bezpieczna. Nie należy modyfikować MOC.md oraz .graph/, ponieważ nocny proces regeneruje oba te elementy.

Traktuj vault jako dziennik swojego życia

Ten katalog stanowi datowany zapis tego, co zostało powiedziane, z kim doszło do spotkania i jakie decyzje podjęto na wynajmowanej maszynie. Wynikają z tego dwie kwestie.

Self-hosting przenosi przechowywanie danych, a nie ich przetwarzanie. Każda tura konwersacji trafia do dostawcy modelu, a każda notatka głosowa do Deepgram. Vault należy do użytkownika. Zapytania nie są prywatne względem firm, które je obsługują. Samodzielne uruchomienie warstwy pamięci, tak jak w przypadku serwera pamięci Mem0 na własnym VPS, ma ten sam charakter: magazyn danych jest lokalny, podczas gdy wywołanie modelu nadal opuszcza infrastrukturę. Jeśli temat jest zbyt wrażliwy dla podmiotu trzeciego, należy wykluczyć go z czatu.

Zasięg tego konta obejmuje cały vault. Narzędzia Iva działają natywnie na hoście poprzez fs oraz child_process środowiska Node, bez użycia Docker i bez piaskownicy, więc przejęta tura konwersacji posiada wszelkie uprawnienia użytkownika usługi. Dlatego po instalacji konto nie przechowuje żadnych sudo i dlatego lista dozwolonych (allowlist) wymaga większej uwagi, niż mogłoby się wydawać: jest to brama decydująca o tym, czyje wiadomości stają się poleceniami na serwerze. Jeśli asystent ma być dostępny w kieszeni bez wystawiania usług na zewnątrz, jest to ten sam schemat, który stosuje się, aby uzyskać dostęp do self-hosted agenta Hermes z telefonu, gdzie klient czatu wykonuje zadanie, które w innym przypadku wymagałoby publicznego punktu końcowego.

Co ulega awarii i jaki komunikat zobaczysz

Build killed, exit 137. Mechanizm OOM Killer jądra systemu przerwał proces budowania. Instalator dodaje swap tylko wtedy, gdy pamięć RAM jest mniejsza niż 1.5 GB i nie istnieje żadna partycja wymiany, dlatego należy dodać ją samodzielnie i ponownie uruchomić instalator.

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

Failed to connect to bus. Każde polecenie systemctl --user wyświetla ten komunikat, gdy powłoka nie posiada sesyjnej szyny użytkownika, którą zapewnia sudo -iu iva. Należy otworzyć standardową sesję SSH jako ten użytkownik lub wyeksportować XDG_RUNTIME_DIR=/run/user/$(id -u iva) przed wykonaniem polecenia.

Bot ignoruje użytkownika. Zmienna TELEGRAM_ALLOWED_USER_IDS jest pusta, a lista dozwolonych (allowlist) działa w trybie domyślnego odrzucania. Należy wysłać do bota wiadomość: odpowie on wyłącznie numerycznym identyfikatorem. Należy umieścić ten identyfikator w .env i uruchomić iva restart.

Bot przestaje odpowiadać zaraz po iva config. Kreator może przenieść IVA_PORT bez aktualizacji ASSISTANT_HOST, przez co most łączy się z portem, na którym nikt nie nasłuchuje. Należy porównać obie linie, a następnie zrestartować usługę.

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

Wiadomość głosowa pozostaje bez odpowiedzi. API botów Telegram odrzuca pobieranie plików powyżej 20 MB, więc most nie otrzymuje długich nagrań i nie ma czego przekazać do Deepgram. Przed wysłaniem plik należy podzielić na mniejsze części.

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

Tura zawiesza się i nie odpowiada. Zablokowany stan przepływu pracy przetrwa restart i ponownie ustawi się w kolejce, więc samo ponowne uruchomienie nie rozwiąże problemu. iva reset poddaje kwarantannie ten stan i restartuje obie usługi. /new na czacie rozpoczyna nową konwersację.

Chromium nie działa na Ubuntu 24.04. Ubuntu 24.04 blokuje nieuprzywilejowane przestrzenie nazw użytkownika (user namespaces) poprzez AppArmor, przez co piaskownica Chromium nie może wystartować, a agent-browser kończy się błędem. Instalator obchodzi to ograniczenie, zapisując "--no-sandbox" w ~/.agent-browser/config.json. Należy mieć świadomość istnienia tego pliku. Obniża on poziom izolacji przeglądarki, co stanowi kolejny powód, dla którego konto to nie powinno posiadać dostępu do żadnych zasobów poza Iva.

FAQ

Czy do samodzielnego hostowania Iva potrzebuję domeny lub otwartego portu?

Nie. Iva komunikuje się z Telegramem za pomocą long polling: iva-telegram-poll.service wywołuje getUpdates i oczekuje na odpowiedź, więc każde połączenie jest wychodzące z serwera. Żaden ruch z zewnątrz nie musi docierać do maszyny, dlatego nie jest wymagany rekord DNS ani certyfikat. Własny port HTTP agenta, 8723, jest powiązany z 127.0.0.1, a dokumentacja projektu zaleca, aby go nie wystawiać. Poprawna konfiguracja to firewall zezwalający wyłącznie na ruch SSH.

Ile kosztuje miesięczne utrzymanie Iva?

Według opublikowanych cenników z sierpnia 2026 roku, mały VPS za 5 dolarów plus najtańszy plan ryczałtowy za 5 dolarów daje łącznie około 10 dolarów amerykańskich miesięcznie. Ollama Cloud kosztuje 20 dolarów, a modele klasy frontier są rozliczane dodatkowo. Kredyty startowe Deepgram początkowo pokrywają koszty głosu, a pakiety wyszukiwania internetowego posiadają darmowe limity. OpenRouter działa w modelu pay-as-you-go, więc nie posiada stałej miesięcznej opłaty.

Gdzie Iva przechowuje moje dane i jak wykonać ich kopię zapasową?

Domyślnie w ~/iva/vault, co jest określone przez ASSISTANT_VAULT_DIR. Jest to oddzielne, prywatne repozytorium git zawierające zwykłe pliki markdown: CORE.md, daily/YYYY-MM-DD.md, cards/ oraz summaries/. Funkcja memory doctor o godzinie 05:00 wykonuje commit i push, co jest skuteczne tylko wtedy, gdy repozytorium posiada zdalny serwer (remote), więc należy uruchomić gh auth login lub dodać własny remote podczas konfiguracji. Warto również przechowywać kopię offline za pomocą tar czf ~/iva-vault-backup.tgz -C ~/iva vault i przenieść ten plik poza serwer.

Czy moje dane są prywatne, jeśli hostuję Iva samodzielnie?

Magazyn danych należy do użytkownika. Przetwarzanie danych – nie. Magazyn pozostaje na dysku do momentu wykonania operacji push, a .env posiada uprawnienia 0600 i należy do użytkownika usługi. Wywołania modeli oraz transkrypcja głosu to API chmurowe, więc wiadomości przechodzą przez dostawcę modelu oraz Deepgram. Iva jest na licencji MIT, więc można sprawdzić dokładnie, co jest wysyłane i wprowadzić zmiany. Lista dozwolonych użytkowników Telegrama działa w trybie fail-closed, co oznacza, że pusty plik TELEGRAM_ALLOWED_USER_IDS blokuje dostęp wszystkim, w tym właścicielowi.

Jakich dostawców modeli wspiera Iva?

MODEL_PROVIDER obsługuje opencode (OpenCode Go), ollama (Ollama Cloud), openrouter oraz codex. OpenRouter przyjmuje slug dostawcy, taki jak anthropic/claude-sonnet-4.5, i oferuje najszerszy wybór modeli. codex loguje się do istniejącej subskrypcji ChatGPT za pomocą iva login i nie wymaga klucza API. Należy ustawić dostawcę, dopasować okno kontekstowe do rzeczywistego rozmiaru modelu, a następnie uruchomić iva restart, ponieważ model jest wczytywany jednorazowo podczas startu procesu.