Paano i-self-host ang Iva Telegram AI assistant

Ang bina-build mo

Ang Iva ay isang self-hosted Telegram AI assistant. Isa ito sa iilang app na maaari mong i-deploy nang walang kailangang buksang inbound port at walang domain na kailangang ituro rito. Wala ring certificate dahil walang process sa server na nakikinig para sa public network. Kumokonekta palabas ang service sa Telegram, pinananatiling bukas ang connection, at binabasa ang iyong mga mensahe mula sa reply. Ang lahat ng iba pa ay nakabatay sa isang outbound connection na ito.

MIT licensed ang Iva at nakasulat sa Node. Ang memory nito ay isang folder ng plain markdown files na direktang binubuksan ng Obsidian. Dahil dito, nananatiling nababasa nang wala ang app ang mga note na itinatala nito tungkol sa iyo. Sa guide na ito, naka-pin ang release na v0.3.13, na inilabas noong 6 August 2026.

Karamihan sa self-hosted software ay nagsisimula sa isang DNS (domain name system) record at isang Let's Encrypt certificate na inisyu gamit ang Certbot. Lubusang nilalaktawan ng Iva ang layer na iyon. Kaya sapat na deployment ang isang maliit na VPS sa likod ng firewall na SSH lamang ang pinapahintulutang traffic.

Bakit hindi nangangailangan ng open ports si Iva

Ang iva-telegram-poll.service ay isang long polling bridge. Tinatawag nito ang getUpdates API ng Telegram at hinihintay ang tugon, kaya ang bawat koneksyon ay nagsisimula sa iyong server. Hindi kumokonekta pabalik ang Telegram. Ibig sabihin, walang reverse proxy na kailangang i-configure at walang certificate renewal na maaaring makalimutan.

Nakikinig mismo ang agent sa 127.0.0.1 port 8723 lamang. Malinaw ang sinasabi sa project documentation: huwag i-expose ang port 8723, at anumang reverse proxy na ilagay mo sa harap nito ay dapat magpanatili ng bearer token requirement. Suriin ang bind address pagkatapos ng install.

sudo ss -tlnp | grep 8723

Dapat nakalagay ang address na 127.0.0.1:8723. Kapag wildcard address gaya ng 0.0.0.0:8723 ang ginamit, maaabot mula sa internet ang HTTP routes ng agent. Ayusin ito bago ka magpadala ng anumang pribadong data sa bot.

Kaya nananatiling sarado ang firewall. Payagan muna ang SSH bago mo ito i-enable, dahil ang ufw enable na walang SSH rule ay magsasara sa session na ginagamit mo.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Aktuwal na ginagawa ng one-line installer

Nagbibigay ang front page ng proyekto ng isang command na nagpi-pipe ng script mula sa GitHub papunta sa bash. Basahin muna ang script, dahil higit pa sa pag-install ng isang program ang ginagawa nito.

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

• Nag-i-install ito ng system packages gamit ang natukoy na package manager: git, gh, python3, ffmpeg, pandoc at poppler-utils.
• Gumagawa ito ng 2 GB swapfile sa /swapfile kapag wala pang 1.5 GB RAM ang server at walang swap, dahil napapatay ang build kapag wala nito.
• Nag-i-install ito ng nvm, at pagkatapos ay ng Node 24, na siyang minimum na bersyon na pinapatakbo ng Iva.
• Ini-install nito ang uv, ang Python package manager, sa ~/.local/bin.
• Kino-clone nito ang repository sa ~/iva at pinapatakbo ang npm ci.
• Nag-i-install ito ng dalawang global npm package, agent-browser, na nagda-download pagkatapos ng Chromium, at @googleworkspace/cli.
• Pinapatakbo nito ang setup wizard, bina-build ang project, at ginagawa ang vault.
• Isinusulat nito ang isang iva command sa ~/.local/bin at ini-install ang systemd user units.

Maraming software ang ini-install ng isang line na ito. Ipinapaliwanag din nito kung bakit inuutusan ng README na mag-install bilang ordinaryong user at hindi bilang root: tatakbo ang shell tool ng agent gamit ang mga privilege na mayroon ang installer. Tinatawag ng script ang sudo para lamang sa package installs at swapfile, sa pamamagitan ng isang helper na direktang nagpapatakbo ng mga command kapag root ka na.

Gumawa ng dedicated user bago mag-install

Bigyan ang Iva ng sariling account. Nagpapatakbo ang agent ng shell commands sa host sa pamamagitan ng Node's child_process, nang walang container at sandbox. Kaya ang account na ginagamit nito ang security boundary.

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

Mahalaga ang enable-linger dahil tumatakbo ang Iva bilang systemd user units. Kapag walang linger, pinahihinto ng systemd ang mga service ng user sa sandaling matapos ang huling session nito. Dahil dito, mamamatay ang assistant kapag isinara mo ang SSH. Nalalapat din ang parehong rule sa anumang service at timer na ikaw mismo ang sumusulat sa ilalim ng systemd.

Kailangan ng account ang sudo habang nagdadagdag lamang ang installer ng mga package. Alisin ito kapag tapos na ang installation.

sudo deluser iva sudo

Direktang mag-log in bilang user na iyon gamit ang SSH. Ang shell na binuksan mo gamit ang sudo -iu iva ay walang nakatakdang DBUS_SESSION_BUS_ADDRESS o XDG_RUNTIME_DIR. Kaya mabibigo ang bawat command na systemctl --user dahil sa Failed to connect to bus. Ang pagtatakda ng boundary na ito ay kapareho ng pagpapatakbo ng mga service gamit ang mga user na may least privilege.

Mag-install ng naka-pin na release sa halip na mag-pipe sa bash

May kapaki-pakinabang na property ang installer. Bago ito mag-clone, tinitingnan nito kung ang directory kung nasaan ang script ay may package.json na naglalaman na ng "eve". Kung mayroon, bina-build nito ang checkout na iyon at nilalaktawan ang clone. Kaya maaari mong ikaw mismo ang pumili ng version.

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

Alam mo na ngayon kung aling code ang tumatakbo. Hindi mo iyon malalaman kapag nag-clone ang script ng main sa kung anumang state nito sa oras na iyon. Nag-release ang Iva ng limang release mula 4 hanggang 6 August 2026, kaya hindi pareho ang main ngayong umaga at main ngayong hapon.

Iniiwan ng tag checkout ang git sa detached HEAD state. Maayos itong tumatakbo, pero dapat mong malaman ang limitasyon: inililipat ng iva update ang checkout pasulong sa update branch, kaya ang pin ay kilalang panimulang punto lamang at hindi permanenteng freeze. Ipinapakita ng iva version ang package version at git commit, kaya lagi mong makikita kung nasaan ka.

Para lumipat nang kusa sa mas bagong release, ilista ang mga tag, itakda ang IVA_TAG sa napili mo, pagkatapos ay patakbuhin muli ang installer mula sa loob ng 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

Pinipigilan ng --skip-setup na muling patakbuhin ang wizard sa isang .env na gumagana na.

Ang limang hakbang ng wizard at ang mga key na hinihingi nito

1. Model provider at model. Tumatanggap ang MODEL_PROVIDER ng opencode, ollama, openrouter o codex. Agad na bine-validate ng wizard ang key at inililista ang mga model na kasama sa plan mo.
2. Voice at search. Ginagamit ang Deepgram key para i-transcribe ang voice notes. Optional ang web search key (Tavily, Exa, Parallel o Brave).
3. Telegram bot token mula sa @BotFather, na chine-check laban sa getMe endpoint.
4. Access control. Magpapadala ka ng message sa bot, at babasahin ng wizard ang numeric user ID mo mula sa getUpdates.
5. System settings. IANA timezone, vault directory, at local port na 8723 bilang default.

Dalawa sa mga ito ay dependencies na itinatago ng framing na "one command." Walang kasamang model ang Iva, kaya kailangan nito ng paid model plan o API key bago ito makasagot. Hindi rin nito kayang mag-transcribe ng audio nang mag-isa, kaya kailangan ng hiwalay na service para sa voice notes. Gamit ang nova-3 model at DEEPGRAM_LANGUAGE=multi, nade-detect ang language. May starter credits ang mga bagong Deepgram account na sapat para sa ilang buwang personal na paggamit. Gumagana ang text gamit ang model key lamang. Ang voice lang ang nakadepende sa Deepgram.

Tingnan kung ano ang isinulat ng wizard.

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

Dapat mag-print ang ls ng -rw-------, mode 0600, dahil hawak ng file na iyon ang lahat ng key na kakapaste mo lang. Dapat maglaman ang TELEGRAM_ALLOWED_USER_IDS ng numeric ID mo. Fail closed ang allowlist, kaya kapag walang laman ang value, walang sasagutin si Iva.

Isang beses lang binabasa ang model sa pagsisimula ng process. Walang mababago kapag in-edit mo ang MODEL_PROVIDER o ang pangalan ng model sa .env hanggang patakbuhin mo ang iva restart. Sa openrouter, ang pangalan ng model ay vendor slug gaya ng anthropic/claude-sonnet-4.5, hindi simpleng pangalan lang. Sa codex, walang API key: nagsa-sign in ang iva login sa isang umiiral na ChatGPT subscription.

Magkano ang gastos sa pagpapatakbo ng Iva bawat buwan

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

Ito ang mga published list price noong August 2026, hindi mga sukat. Ang maliit na VPS na nagkakahalaga ng 5 US dollars, kasama ang OpenCode Go plan na 5 dollars, ang pinakamurang kumpletong setup—humigit-kumulang 10 dollars bawat buwan. Ang Ollama Cloud ang isa pang flat-rate na option sa halagang 20 dollars, at hiwalay na sinisingil ang paggamit ng frontier models bukod sa plan. Ang voice ay nagkakahalaga ng 0 habang may natitira pang Deepgram starter credits.

Walang row ang OpenRouter dito dahil pay as you go ito, kaya nakabatay ang bill sa aktuwal mong paggamit. Ito ang option na dapat bantayan: ang assistant na nagdadala ng 131072-token context window sa bawat turn ay maaaring mabilis na lumampas sa gastos ng flat plan. Itakda ang context window variable sa aktuwal na laki ng model, dahil nagsasayang lamang ng tokens ang sobrang taas na value.

Ang dalawang service at dalawang timer

• Ang iva.service ang nagpapatakbo sa mismong agent.
• Ang iva-telegram-poll.service ang nagpapatakbo sa long polling bridge na kumokonekta sa Telegram.
• Tumatakbo ang iva-memory-doctor.timer sa 05:00 at isinasagawa ang nightly maintenance pass sa vault.
• Tumatakbo ang iva-update-check.timer sa 10:00 at tinitingnan kung may mas bagong release.
• Umiiral lamang ang iva-telegram-userbot.service kung na-set up mo ang optional na Telethon proxy.

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

Iniuulat ng iva status ang dalawang service at dalawang watchdog timer. Ipinapakita ng systemctl --user list-timers ang susunod na run time ng bawat timer. Ito ang paraan upang makumpirma mong tatakbo talaga ang memory doctor ngayong gabi. Dapat nasa active (running) ang dalawang service. Kung paulit-ulit na nagre-restart ang isa, ibinibigay ng journalctl --user -u iva.service -n 100 ang dahilan.

Mahalaga ang paghahati na ito kapag nagde-debug. Maaaring gumagana at nagpo-poll ang bridge habang down ang agent. Sa ganitong sitwasyon, tinatanggap ng Telegram ang mensahe mo pero walang sumasagot dito. Sinusubaybayan ng iva logs poll ang bridge, at sinusubaybayan ng iva logs ang agent. Kaya ipinapakita ng dalawang log kung aling bahagi ang may problema.

Kung saan nakalagay ang Obsidian vault at kung paano ito i-back up

Ang ASSISTANT_VAULT_DIR ay naka-default sa vault sa loob ng install directory, kaya nasa ~/iva/vault ang memory. Sarili itong git repository at hiwalay sa code. Dahil dito, maaari mong i-update ang Iva nang hindi ginagalaw ang iyong mga tala.

• Naglalaman ang vault/CORE.md ng mga permanenteng fact at kasalukuyang preference. Naka-cap ito sa 1200 character at kasama sa bawat system prompt.
• Ang vault/daily/YYYY-MM-DD.md ang transcript ng araw at itinuturing itong append-only.
• Naglalaman ang vault/cards/ ng mga typed card para sa mga contact, project, desisyon, idea, at tala.
• Naglalaman ang vault/summaries/daily/, weekly/, monthly/ at yearly/ ng mga rollup.
• Naglalaman ang vault/attachments/ ng mga file ayon sa petsa, at naglalaman ang vault/.graph/ ng link graph.
• Tinutukoy ng vault/schema.json ang mga uri ng card at mga tuntunin ng decay.

Tumatakbo ang mga rollup ayon sa schedule sa loob ng proseso. Sa 04:00, ginagawang mga card at summary ng daily pass ang transcript ng kahapon at nire-rewrite nito ang CORE.md. Pagkatapos, sunod-sunod na kino-compress ng weekly, monthly, at yearly pass ang mga iyon. Sa 05:00, nagpapatakbo ang memory doctor ng deterministic pass na walang model na ginagamit: ipinapatupad nito ang schema, binubuo muli ang link graph, nire-regenerate ang index, pagkatapos ay nagco-commit at nagpu-push.

Ang push na iyon ang iyong backup, at ito ang hakbang na madalas nakakaligtaan. Kung walang git remote ang vault, sinusubukan ng doctor na gumawa ng private GitHub repository sa pamamagitan ng gh. Kailangan nito ng authenticated GitHub CLI.

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

Ibig sabihin ng commit na may petsa ngayon ay tumakbo ang pass at na-commit ang vault. Ibig sabihin naman ng mga gh not available warning sa log na kabaligtaran: na-maintain ang vault pero hindi ito umaalis sa server. Kaya kapag namatay ang VPS, mawawala rin ang iyong memory.

Magtabi rin ng kopyang ikaw ang may kontrol.

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

Gamitin ang scp para kopyahin ang file palabas ng server, pagkatapos ay burahin ito sa server. Para mabasa ang memory sa Obsidian, ituro ang Obsidian sa clone ng vault repository. Gagana ang Wikilinks at backlinks nang walang pagbabago, pati ang graph view. Ligtas na mano-manong mag-edit ng mga card at ng CORE.md. Huwag galawin ang MOC.md at .graph/, dahil nire-regenerate ng nightly pass ang dalawang iyon.

Ituring logbook ng iyong buhay ang vault

Ang directory na iyon ay dated record ng mga sinabi mo, mga nakilala mo, at mga desisyong ginawa mo, sa machine na nirerentahan mo. May dalawang mahalagang implikasyon dito.

Inililipat ng self-hosting ang storage, hindi ang processing. Ipinapadala pa rin ang bawat turn sa model provider mo, at ipinapadala ang bawat voice note sa Deepgram. Iyo ang vault. Hindi pribado sa mga kumpanyang nagsisilbi sa mga ito ang mga request. Kapag ikaw mismo ang nagpatakbo ng memory layer, gaya ng Mem0 memory server sa sarili mong VPS, pareho pa rin ang setup: local ang store, pero lumalabas pa rin sa iyong environment ang model call. Kung masyadong sensitibo ang isang paksa para sa third party, huwag mo itong isama sa chat.

Sakop ng account na iyon ang buong vault. Host native na tumatakbo ang tools ni Iva sa pamamagitan ng Node's fs at child_process, na walang Docker at walang sandbox, kaya ang na-hijack na turn ay magkakaroon ng anumang access na mayroon ang service user. Kaya walang sudo ang account matapos ang install, at dapat bigyan ng higit na pansin ang allowlist kaysa sa maaaring ipahiwatig nito: ito ang gate na nagpapasya kung aling mga mensahe ang magiging commands sa server mo. Kung gusto mo ang assistant sa iyong telepono nang walang binubuksan, ito rin ang pattern na ginagamit para ma-access ang self-hosted Hermes agent mula sa iyong phone, kung saan ginagawa ng chat client ang trabahong kung hindi ay gagawin ng isang public endpoint.

Ano ang masisira at ang mensaheng makikita mo

Build killed, exit 137. Pinahinto ng out-of-memory killer ng kernel ang build. Nagdadagdag lamang ang installer ng swap kapag mas mababa sa 1.5 GB ang RAM at walang umiiral na swap. Kaya ikaw mismo ang magdagdag nito at patakbuhin muli ang installer.

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

Failed to connect to bus. Ipinapakita ito ng bawat command na systemctl --user kapag walang user session bus ang shell. Ito ang ibinibigay ng sudo -iu iva. Magbukas ng normal na SSH session bilang user na iyon, o i-export ang XDG_RUNTIME_DIR=/run/user/$(id -u iva) bago patakbuhin ang command.

Hindi ka pinapansin ng bot. Walang laman ang TELEGRAM_ALLOWED_USER_IDS, at fail closed ang allowlist. Magpadala ng mensahe sa bot. Ang numeric ID mo lamang ang isasagot nito. Ilagay ang ID na iyon sa .env at patakbuhin ang iva restart.

Tumatahimik ang bot kaagad pagkatapos ng iva config. Maaaring ilipat ng wizard ang IVA_PORT nang hindi ina-update ang ASSISTANT_HOST, kaya kumokonekta ang bridge sa port na walang sumasagot. Ihambing ang dalawang linya, pagkatapos ay mag-restart.

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

Walang tugon sa voice note. Tinatanggihan ng Telegram Bot API ang pag-download ng file na lampas sa 20 MB, kaya hindi natatanggap ng bridge ang mahahabang audio at wala itong maipapadala sa Deepgram. Hatiin ang file bago ito ipadala.

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

Nabibitin ang isang turn at hindi kailanman sumasagot. Nananatili ang na-stuck na workflow state kahit mag-restart at muli itong ipinipila, kaya hindi ito nalilinis ng simpleng pag-restart. Kino-quarantine ng iva reset ang state na iyon at nire-restart ang dalawang serbisyo. Sinisimulan ng /new sa chat ang isang bagong conversation.

Hindi gumagana ang Chromium sa Ubuntu 24.04. Hinaharangan ng Ubuntu 24.04 ang unprivileged user namespaces sa pamamagitan ng AppArmor, kaya hindi makapagsimula ang sariling sandbox ng Chromium at nabibigo ang agent-browser. Nilalampasan ito ng installer sa pamamagitan ng pagsusulat ng "--no-sandbox" sa ~/.agent-browser/config.json. Dapat mong malaman na naroon ito. Pinapababa nito ang isolation ng browser, kaya isa pa itong dahilan upang walang pagmamay-ari ang account maliban sa Iva.

FAQ

Kailangan ko ba ng domain o bukas na port para ma-self-host ang Iva?

Hindi. Nakikipag-ugnayan ang Iva sa Telegram gamit ang long polling: tinatawag ng iva-telegram-poll.service ang getUpdates at naghihintay, kaya outbound mula sa server mo ang bawat connection. Walang kailangang makaabot sa server mula sa labas, kaya hindi mo kailangan ng DNS record o certificate. Ang sariling HTTP port ng agent, 8723, ay nagbi-bind sa 127.0.0.1, at sinasabi ng project documentation na huwag itong i-expose. Ang tamang configuration ay firewall na nagpapahintulot sa SSH at wala nang iba.

Magkano ang buwanang gastos sa pagpapatakbo ng Iva?

Batay sa published list prices noong August 2026, ang maliit na VPS na nagkakahalaga ng 5 dollars, kasama ang pinakamurang flat rate model plan na 5 dollars, ay humigit-kumulang 10 US dollars bawat buwan. Ang Ollama Cloud ay nagkakahalaga naman ng 20 dollars, bukod pa sa singil para sa frontier models. Sapat muna ang starter credits ng Deepgram para sa voice, at may free allowances ang mga web search tier. Pay as you go ang OpenRouter, kaya wala itong fixed monthly cost.

Saan iniimbak ng Iva ang data ko, at paano ko ito iba-back up?

Nasa ~/iva/vault ito bilang default, na itinatakda ng ASSISTANT_VAULT_DIR. Isa itong hiwalay na private git repository na naglalaman ng plain markdown: CORE.md, daily/YYYY-MM-DD.md, cards/ at summaries/. Kino-commit at pine-push ito ng memory doctor nang 05:00. Makakatulong lamang ito kung may remote ang repository, kaya patakbuhin ang gh auth login o magdagdag ng sarili mong remote habang nagse-set up. Magtabi rin ng offline copy gamit ang tar czf ~/iva-vault-backup.tgz -C ~/iva vault at ilipat ang file na iyon palabas ng server.

Pribado ba ang data ko kung ako ang nagse-self-host ng Iva?

Sa iyo ang storage. Hindi sa iyo ang processing. Nananatili sa disk mo ang vault hanggang i-push mo ito, at ang .env ay may mode na 0600 at pagmamay-ari ng service user. Cloud API ang model calls at voice transcription, kaya dumadaan ang mga mensaheng iyon sa model provider mo at sa Deepgram. MIT licensed ang Iva, kaya mababasa mo nang eksakto kung ano ang ipinapadala nito at mababago mo ito. Fail closed ang Telegram allowlist, kaya kapag walang laman ang TELEGRAM_ALLOWED_USER_IDS, bina-block nito ang lahat, kasama ka.

Aling model provider ang sinusuportahan ng Iva?

Tinatanggap ng MODEL_PROVIDER ang opencode (OpenCode Go), ollama (Ollama Cloud), openrouter at codex. Gumagamit ang OpenRouter ng vendor slug gaya ng anthropic/claude-sonnet-4.5 at nag-aalok ng pinakamalawak na pagpipilian ng models. Nagla-log in ang codex sa kasalukuyang ChatGPT subscription gamit ang iva login at hindi nangangailangan ng API key. Itakda ang provider, itakda ang katugmang context window sa aktuwal na laki ng model, at pagkatapos ay patakbuhin ang iva restart, dahil isang beses lamang binabasa ang model kapag nagsisimula ang process.