Cara Pasang Iva: Pembantu AI Telegram Sendiri

Apa yang anda bina

Iva ialah pembantu AI Telegram yang dihoskan sendiri, dan ia merupakan salah satu daripada segelintir pembantu yang boleh anda gunakan tanpa perlu membuka port masuk atau menghalakan domain kepadanya. Tiada sijil diperlukan kerana tiada apa-apa pada pelayan yang mendengar trafik awam. Servis ini membuat sambungan keluar ke Telegram, mengekalkan sambungan tersebut, dan membaca mesej anda daripada balasan. Segala fungsi lain berpunca daripada satu sambungan keluar tersebut.

Iva dilesenkan di bawah MIT dan ditulis dalam Node. Memorinya ialah folder fail markdown biasa yang boleh dibuka terus oleh Obsidian, jadi nota yang disimpan tentang anda kekal boleh dibaca tanpa aplikasi tersebut. Panduan ini menetapkan versi keluaran v0.3.13, yang diterbitkan pada 6 Ogos 2026.

Kebanyakan perisian yang dihoskan sendiri bermula dengan rekod DNS (domain name system) dan sijil Let's Encrypt yang dikeluarkan dengan Certbot. Iva melangkau lapisan tersebut sepenuhnya, itulah sebabnya VPS kecil di sebalik firewall yang hanya membenarkan SSH sudah memadai sebagai satu penempatan lengkap.

Mengapa Iva tidak memerlukan port terbuka

iva-telegram-poll.service ialah jambatan long polling. Ia memanggil API getUpdates Telegram dan menunggu jawapan, jadi setiap sambungan bermula daripada pelayan anda. Telegram tidak pernah menyambung semula ke pelayan anda, yang bermaksud tiada reverse proxy untuk dikonfigurasikan dan tiada pembaharuan sijil yang perlu diingati.

Ejen itu sendiri memang mendengar, pada port 127.0.0.1 8723 sahaja. Dokumentasi projek menyatakan dengan jelas: jangan dedahkan port 8723, dan mana-mana reverse proxy yang anda letakkan di hadapannya mesti mengekalkan keperluan bearer token. Semak alamat bind selepas pemasangan.

sudo ss -tlnp | grep 8723

Alamat tersebut mestilah terbaca 127.0.0.1:8723. Alamat wildcard seperti 0.0.0.0:8723 bermakna laluan HTTP ejen boleh dicapai dari internet, dan anda harus membetulkannya sebelum anda menghantar sebarang maklumat peribadi kepada bot tersebut.

Oleh itu, firewall kekal tertutup. Benarkan SSH sebelum anda mengaktifkannya, kerana ufw enable tanpa peraturan SSH akan menutup sesi yang sedang anda taip.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Tindakan sebenar pemasang satu baris

Halaman utama projek memberikan anda satu arahan yang menyalurkan skrip daripada GitHub terus ke dalam bash. Baca skrip tersebut terlebih dahulu, kerana ia melakukan lebih banyak perkara daripada sekadar memasang satu program.

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

• Ia memasang pakej sistem menggunakan pengurus pakej yang dikesan: git, gh, python3, ffmpeg, pandoc dan poppler-utils.
• Ia mencipta swapfile bersaiz 2 GB pada /swapfile apabila pelayan mempunyai kurang daripada 1.5 GB RAM dan tiada swap, kerana proses binaan akan terhenti tanpanya.
• Ia memasang nvm, kemudian Node 24, iaitu versi minimum yang diperlukan untuk menjalankan Iva.
• Ia memasang uv, pengurus pakej Python, ke dalam ~/.local/bin.
• Ia mengklon repositori ke ~/iva dan menjalankan npm ci.
• Ia memasang dua pakej npm global, agent-browser (yang kemudian memuat turun Chromium) dan @googleworkspace/cli.
• Ia menjalankan wizard penyediaan, membina projek, dan mencipta vault.
• Ia menulis arahan iva ke dalam ~/.local/bin dan memasang unit pengguna systemd.

Itu adalah jumlah perisian yang banyak untuk satu baris arahan. Ia juga menjelaskan arahan dalam README untuk memasang sebagai pengguna biasa dan bukan sebagai root: alat shell ejen tersebut akan berjalan dengan keistimewaan yang dimiliki oleh pemasang tadi. Skrip ini hanya memanggil sudo untuk pemasangan pakej dan swapfile, melalui satu pembantu yang menjalankan arahan secara terus apabila anda sudah pun menjadi root.

Cipta pengguna khusus sebelum anda memasang

Berikan Iva akaunnya sendiri. Ejen ini menjalankan arahan shell pada hos melalui child_process Node, tanpa bekas (container) dan tanpa kotak pasir (sandbox), jadi akaun yang menjalankannya merupakan sempadan keselamatan.

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 adalah penting kerana Iva berjalan sebagai unit user systemd. Tanpa linger, systemd akan menghentikan servis pengguna tersebut sebaik sahaja sesi terakhir mereka berakhir, jadi pembantu ini akan mati apabila anda menutup SSH. Peraturan yang sama mengawal mana-mana servis dan pemasa yang anda tulis sendiri di bawah systemd.

Akaun ini hanya memerlukan sudo semasa pemasang menambah pakej. Tarik balik kebenaran tersebut apabila pemasangan selesai.

sudo deluser iva sudo

Log masuk sebagai pengguna tersebut secara terus melalui SSH. Shell yang anda masuki dengan sudo -iu iva tidak mempunyai DBUS_SESSION_BUS_ADDRESS mahupun XDG_RUNTIME_DIR yang ditetapkan, jadi setiap arahan systemctl --user akan gagal dengan Failed to connect to bus. Menetapkan sempadan ini adalah latihan yang sama seperti menjalankan servis di bawah pengguna dengan keistimewaan paling rendah.

Install a pinned release instead of piping to bash

The installer has a useful property. Before it clones anything, it checks whether the directory the script sits in already holds a package.json containing "eve". If it does, it builds that checkout and skips the clone. So you can choose the version yourself.

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

Now you know which code is running. You do not know that when the script clones main at whatever state it happens to be in that hour. Iva shipped five releases between 4 and 6 August 2026, so main this morning and main this afternoon are not the same program.

A tag checkout leaves git in a detached HEAD state. That runs fine, but understand the limit: iva update moves the checkout forward onto the update branch, so the pin is a known starting point and not a permanent freeze. iva version prints the package version and the git commit, so you can always see where you are.

To move to a later release on purpose, list the tags, set IVA_TAG to the one you picked, then run the installer from inside the checkout again.

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 stops the wizard from running again over a .env that already works.

Lima langkah wizard, dan kunci yang diperlukan

1. Penyedia model dan model. MODEL_PROVIDER menerima opencode, ollama, openrouter atau codex. Wizard akan mengesahkan kunci secara langsung dan menyenaraikan model yang ditawarkan oleh pelan anda.
2. Suara dan carian. Kunci Deepgram mentranskripsikan nota suara. Kunci carian web (Tavily, Exa, Parallel atau Brave) adalah pilihan.
3. Token bot Telegram daripada @BotFather, yang disemak terhadap endpoint getMe.
4. Kawalan akses. Anda menghantar mesej kepada bot anda, dan wizard membaca ID pengguna berangka anda daripada getUpdates.
5. Tetapan sistem. Zon masa IANA, direktori vault, dan port tempatan, secara lalai 8723.

Dua daripada perkara tersebut merupakan dependensi yang disembunyikan oleh kerangka "satu arahan". Iva tidak menyertakan sebarang model, jadi ia memerlukan pelan model berbayar atau kunci API sebelum ia boleh menjawab apa-apa. Ia juga tidak mentranskripsikan audio sendiri, jadi nota suara memerlukan perkhidmatan berasingan. Model nova-3 daripada Deepgram dengan DEEPGRAM_LANGUAGE=multi mengesan bahasa, dan akaun Deepgram baharu menerima kredit permulaan yang mencukupi untuk kegunaan peribadi selama berbulan-bulan. Teks berfungsi dengan kunci model sahaja. Hanya suara yang bergantung pada Deepgram.

Semak apa yang telah ditulis oleh wizard.

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

ls sepatutnya memaparkan -rw-------, mod 0600, kerana fail tersebut menyimpan setiap kunci yang baru anda tampal. TELEGRAM_ALLOWED_USER_IDS mesti mengandungi ID berangka anda. Senarai kebenaran (allowlist) bersifat "fail closed", jadi nilai kosong bermakna Iva tidak menjawab sesiapa pun.

Model dibaca sekali sahaja, semasa proses bermula. Menyunting MODEL_PROVIDER atau nama model dalam .env tidak akan mengubah apa-apa sehingga anda menjalankan iva restart. Pada openrouter, nama model adalah slug vendor seperti anthropic/claude-sonnet-4.5, bukan nama biasa. Pada codex, tiada kunci API langsung: iva login log masuk ke langganan ChatGPT sedia ada.

Berapakah kos operasi bulanan 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
  }
]

Ini adalah harga senarai yang diterbitkan setakat Ogos 2026, bukan ukuran sebenar. VPS kecil pada harga 5 dolar AS ditambah pelan OpenCode Go pada harga 5 dolar merupakan persediaan lengkap paling murah, iaitu sekitar 10 dolar sebulan. Ollama Cloud ialah pilihan kadar rata yang lain pada harga 20 dolar, dan model frontier-nya dibilkan sebagai penggunaan tambahan di luar pelan tersebut. Kos suara adalah 0 sementara kredit permulaan Deepgram masih berbaki.

OpenRouter tidak mempunyai baris di sini kerana ia menggunakan kaedah bayar semasa guna, jadi bil anda mengikut penggunaan anda. Itu adalah pilihan yang perlu dipantau: pembantu yang membawa tetingkap konteks 131072 token ke dalam setiap pusingan boleh melebihi kos pelan rata dengan cepat. Tetapkan pemboleh ubah tetingkap konteks kepada saiz sebenar model, kerana nilai yang terlalu tinggi hanya membazirkan token.

Dua servis dan dua pemasa

• iva.service menjalankan ejen itu sendiri.
• iva-telegram-poll.service menjalankan jambatan long polling yang berhubung dengan Telegram.
• iva-memory-doctor.timer dicetuskan pada jam 05:00 dan menjalankan proses penyelenggaraan harian ke atas vault.
• iva-update-check.timer dicetuskan pada jam 10:00 dan menyemak sama ada keluaran (release) yang lebih baharu wujud.
• iva-telegram-userbot.service wujud hanya jika anda menyediakan proksi Telethon pilihan.

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

iva status melaporkan kedua-dua servis dan kedua-dua pemasa watchdog. systemctl --user list-timers mencetak waktu larian seterusnya bagi setiap pemasa, iaitu cara anda mengesahkan bahawa doktor memori akan benar-benar berjalan pada malam ini. Kedua-dua servis sepatutnya berada dalam status active (running). Jika salah satu dimulakan semula secara berulang, journalctl --user -u iva.service -n 100 memberikan puncanya.

Pembahagian ini penting semasa anda melakukan penyahpepijatan (debug). Jambatan boleh kekal aktif dan melakukan polling semasa ejen tidak berfungsi, kemudian Telegram menerima mesej anda tetapi tiada apa-apa yang membalasnya. iva logs poll mengikuti jambatan, iva logs mengikuti ejen, jadi kedua-dua log memberitahu anda bahagian mana yang rosak.

Lokasi vault Obsidian dan cara membuat sandarannya

ASSISTANT_VAULT_DIR secara lalai berada di vault di dalam direktori pemasangan, jadi memori tersebut terletak di ~/iva/vault. Ia merupakan repositori git yang tersendiri, terpisah daripada kod, yang membolehkan anda mengemas kini Iva tanpa menjejaskan nota anda.

• vault/CORE.md menyimpan fakta kekal dan keutamaan tetap, dihadkan kepada 1200 aksara, dan disertakan dalam setiap prompt sistem.
• vault/daily/YYYY-MM-DD.md ialah transkrip harian, yang dikendalikan sebagai fail tambah-sahaja (append-only).
• vault/cards/ menyimpan kad bertaip untuk kenalan, projek, keputusan, idea dan nota.
• vault/summaries/daily/, weekly/, monthly/ dan yearly/ menyimpan data ringkasan (rollups).
• vault/attachments/ menyimpan fail mengikut tarikh, dan vault/.graph/ menyimpan graf pautan.
• vault/schema.json mentakrifkan jenis kad dan peraturan luput.

Ringkasan dijalankan mengikut jadual di dalam proses tersebut. Proses harian pada jam 04:00 menukarkan transkrip semalam menjadi kad dan ringkasan serta menulis semula CORE.md, kemudian proses mingguan, bulanan dan tahunan memampatkan data tersebut secara bergilir. Pada jam 05:00, doktor memori menjalankan proses deterministik tanpa melibatkan model: ia menguatkuasakan skema, membina semula graf pautan, menjana semula indeks, kemudian melakukan commit dan push.

Push tersebut ialah sandaran anda, dan ia merupakan langkah yang sering terlepas pandang. Jika vault tidak mempunyai git remote, doktor akan cuba mencipta repositori GitHub peribadi melalui gh, yang memerlukan GitHub CLI yang telah disahkan.

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

Commit yang bertarikh hari ini bermakna proses tersebut telah dijalankan dan vault telah disimpan. Amaran gh not available dalam log bermaksud sebaliknya: vault diselenggara tetapi tidak pernah meninggalkan pelayan, jadi jika VPS rosak, memori anda akan hilang bersamanya.

Simpan satu salinan yang anda kawal sendiri juga.

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

Salin fail tersebut keluar dari pelayan dengan scp, kemudian padamkannya daripada pelayan. Untuk membaca memori dalam Obsidian, halakan Obsidian ke klon repositori vault tersebut. Wikilink dan backlink berfungsi seperti biasa, begitu juga dengan paparan graf. Menyunting kad dan CORE.md secara manual adalah selamat. Jangan usik MOC.md dan .graph/, kerana proses malam akan menjana semula kedua-duanya.

Anggap vault sebagai log kehidupan anda

Direktori tersebut merupakan rekod bertarikh tentang apa yang anda katakan, siapa yang anda temui dan apa yang anda putuskan, pada mesin yang anda sewa. Dua perkara terhasil daripadanya.

Self-hosting memindahkan storan, bukan pemprosesan. Setiap giliran pergi ke penyedia model anda, dan setiap nota suara pergi ke Deepgram. Vault itu milik anda. Permintaan tersebut tidak bersifat peribadi daripada syarikat yang melayaninya. Menjalankan lapisan memori sendiri, seperti pelayan memori Mem0 pada VPS anda sendiri, mempunyai bentuk yang sama: storan adalah setempat manakala panggilan model masih keluar dari pelayan. Jika sesuatu subjek terlalu sensitif untuk pihak ketiga, jangan masukkan ke dalam sembang.

Jangkauan akaun tersebut adalah keseluruhan vault. Alat Iva berjalan secara natif pada hos melalui fs dan child_process Node, tanpa Docker dan tanpa sandbox, jadi giliran yang dirampas mempunyai apa jua akses yang dimiliki oleh pengguna servis. Itulah sebabnya akaun tersebut tidak memegang sudo selepas pemasangan, dan mengapa senarai kebenaran (allowlist) memerlukan lebih perhatian daripada yang dilihat: ia adalah pintu yang menentukan mesej siapa yang menjadi arahan pada pelayan anda. Jika anda mahukan pembantu dalam poket anda tanpa membuka apa-apa, ini adalah corak yang sama yang digunakan untuk mencapai ejen Hermes yang dihoskan sendiri dari telefon anda, dengan klien sembang melakukan tugas yang sepatutnya dilakukan oleh titik akhir awam.

Perkara yang tergendala dan mesej yang akan anda lihat

Build killed, exit 137. Kernel telah menamatkan proses binaan kerana kehabisan memori (OOM killer). Pemasang hanya menambah swap jika RAM kurang daripada 1.5 GB dan tiada swap sedia ada, jadi tambahkan swap secara manual dan jalankan semula pemasang.

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

Failed to connect to bus. Setiap arahan systemctl --user mencetak mesej ini apabila shell tidak mempunyai bas sesi pengguna, iaitu perkara yang disediakan oleh sudo -iu iva. Buka sesi SSH biasa sebagai pengguna tersebut, atau eksport XDG_RUNTIME_DIR=/run/user/$(id -u iva) sebelum menjalankan arahan.

Bot mengabaikan anda. TELEGRAM_ALLOWED_USER_IDS kosong, dan senarai kebenaran (allowlist) ditetapkan kepada gagal secara tertutup (fail closed). Hantar mesej kepada bot: ia akan membalas dengan ID angka anda dan tiada maklumat lain. Masukkan ID tersebut ke dalam .env dan jalankan iva restart.

Bot menjadi senyap sejurus selepas iva config. Wizard boleh mengalihkan IVA_PORT tanpa mengemas kini ASSISTANT_HOST, menyebabkan jambatan (bridge) bersambung ke port yang tidak mempunyai respons. Bandingkan kedua-dua baris tersebut, kemudian mulakan semula.

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

Nota suara tidak mendapat balasan. API Bot Telegram menolak muat turun fail melebihi 20 MB, jadi jambatan tidak menerima audio yang panjang dan tiada data untuk dihantar ke Deepgram. Pecahkan fail tersebut sebelum anda menghantarnya.

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

Giliran (turn) tergantung dan tidak pernah menjawab. Keadaan aliran kerja yang tersekat akan kekal walaupun selepas but semula dan akan beratur semula secara automatik, jadi memulakan semula sahaja tidak akan menyelesaikannya. iva reset akan mengkuarantin keadaan tersebut dan memulakan semula kedua-dua servis. /new dalam sembang akan memulakan perbualan baharu.

Chromium gagal pada Ubuntu 24.04. Ubuntu 24.04 menyekat ruang nama pengguna tanpa keistimewaan (unprivileged user namespaces) melalui AppArmor, jadi sandbox Chromium tidak dapat bermula dan agent-browser gagal. Pemasang mengatasi masalah ini dengan menulis "--no-sandbox" ke dalam ~/.agent-browser/config.json. Ambil maklum bahawa fail ini wujud. Ia merendahkan tahap pengasingan pelayar, yang merupakan satu lagi sebab mengapa akaun tersebut tidak sepatutnya memiliki apa-apa selain Iva.

FAQ

Adakah saya memerlukan domain atau port terbuka untuk mengehos Iva sendiri?

Tidak. Iva berhubung dengan Telegram melalui long polling: iva-telegram-poll.service memanggil getUpdates dan menunggu, jadi setiap sambungan adalah keluar (outbound) daripada pelayan anda. Tiada apa-apa yang perlu mencapai pelayan anda dari luar, jadi anda tidak memerlukan rekod DNS mahupun sijil. Port HTTP ejen tersebut, 8723, terikat pada 127.0.0.1, dan dokumentasi projek menyatakan supaya anda tidak mendedahkannya. Firewall yang membenarkan SSH sahaja adalah konfigurasi yang betul.

Berapakah kos untuk menjalankan Iva setiap bulan?

Berdasarkan harga senarai Ogos 2026 yang diterbitkan, sebuah VPS kecil pada 5 dolar ditambah dengan pelan model kadar rata termurah pada 5 dolar berjumlah kira-kira 10 dolar AS sebulan. Ollama Cloud berharga 20 dolar, dan mengenakan caj tambahan untuk model frontier. Kredit permulaan Deepgram menampung kos suara pada peringkat awal, dan tier carian web mempunyai peruntukan percuma. OpenRouter menggunakan sistem bayar-ikut-penggunaan, jadi ia tiada angka bulanan tetap.

Di manakah Iva menyimpan data saya, dan bagaimana cara membuat sandarannya?

Secara lalai, ia disimpan dalam ~/iva/vault, yang ditetapkan oleh ASSISTANT_VAULT_DIR. Ia merupakan repositori git peribadi berasingan yang mengandungi fail markdown biasa: CORE.md, daily/YYYY-MM-DD.md, cards/ dan summaries/. Doktor memori pada pukul 05:00 melakukan commit dan push pada data tersebut, yang hanya berkesan jika repositori mempunyai remote, jadi jalankan gh auth login atau tambah remote anda sendiri semasa penyediaan. Simpan juga salinan luar talian dengan tar czf ~/iva-vault-backup.tgz -C ~/iva vault dan pindahkan fail tersebut keluar dari pelayan.

Adakah data saya peribadi jika saya mengehos Iva sendiri?

Storan adalah milik anda. Pemprosesan pula tidak. Bilik kebal (vault) kekal pada cakera anda sehingga anda melakukan push, dan .env ditetapkan pada mod 0600 yang dimiliki oleh pengguna servis. Panggilan model dan transkripsi suara adalah API awan, jadi mesej tersebut melalui penyedia model anda dan Deepgram. Iva dilesenkan di bawah MIT, jadi anda boleh membaca dengan tepat apa yang dihantar dan mengubahnya. Senarai kebenaran (allowlist) Telegram bersifat fail-closed, yang bermaksud TELEGRAM_ALLOWED_USER_IDS yang kosong akan menyekat semua orang, termasuk anda.

Penyedia model manakah yang disokong oleh Iva?

MODEL_PROVIDER menerima opencode (OpenCode Go), ollama (Ollama Cloud), openrouter dan codex. OpenRouter menerima slug vendor seperti anthropic/claude-sonnet-4.5 dan menawarkan pilihan model yang paling luas. codex melog masuk ke langganan ChatGPT sedia ada dengan iva login dan tidak menggunakan kunci API. Tetapkan penyedia, tetapkan tetingkap konteks yang sepadan dengan saiz sebenar model, kemudian jalankan iva restart, kerana model dibaca sekali sahaja pada permulaan proses.