Cara Self-Host Iva, Asisten AI Telegram

Yang Anda bangun

Iva adalah asisten AI Telegram yang di-host sendiri. Iva termasuk sedikit aplikasi yang dapat Anda deploy tanpa membuka port inbound dan tanpa mengarahkan domain ke server. Sertifikat juga tidak diperlukan karena tidak ada proses pada server yang menerima koneksi publik. Service membuat koneksi keluar ke Telegram, mempertahankan koneksi tersebut, lalu membaca pesan Anda dari respons. Semua hal lainnya bergantung pada satu koneksi outbound tersebut.

Iva berlisensi MIT dan ditulis dalam Node. Memorinya berupa folder yang berisi file markdown biasa yang dapat dibuka langsung dengan Obsidian. Dengan demikian, catatan tentang Anda tetap dapat dibaca tanpa aplikasi tersebut. Panduan ini menggunakan release v0.3.13, yang diterbitkan pada 6 August 2026.

Sebagian besar software self-hosted dimulai dengan record DNS (domain name system) dan sertifikat Let's Encrypt yang diterbitkan dengan Certbot. Iva sepenuhnya melewati lapisan tersebut. Karena itu, VPS kecil di balik firewall yang hanya mengizinkan SSH sudah cukup untuk deployment lengkap.

Mengapa Iva tidak memerlukan port terbuka

iva-telegram-poll.service adalah bridge long polling. Bridge ini memanggil API getUpdates Telegram dan menunggu jawabannya, sehingga setiap koneksi dimulai dari server Anda. Telegram tidak pernah melakukan koneksi balik. Artinya, Anda tidak perlu mengonfigurasi reverse proxy atau mengingat pembaruan sertifikat.

Agent itu sendiri memang melakukan listen, tetapi hanya pada port 127.0.0.1 8723. Dokumentasi proyek menyatakannya dengan jelas: jangan mengekspos port 8723, dan reverse proxy apa pun yang Anda tempatkan di depannya harus tetap menerapkan persyaratan bearer token. Periksa alamat bind setelah instalasi.

sudo ss -tlnp | grep 8723

Alamat tersebut harus terbaca 127.0.0.1:8723. Alamat wildcard seperti 0.0.0.0:8723 berarti route HTTP agent dapat diakses dari Internet. Perbaiki hal ini sebelum mengirimkan informasi pribadi apa pun kepada bot.

Karena itu, firewall tetap tertutup. Izinkan SSH sebelum mengaktifkannya, karena ufw enable tanpa aturan SSH akan menutup sesi yang sedang Anda gunakan untuk mengetik.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Apa yang sebenarnya dilakukan oleh penginstal satu baris

Halaman utama proyek menyediakan satu perintah yang menyalurkan skrip dari GitHub ke bash. Baca skrip tersebut terlebih dahulu karena skrip itu melakukan lebih dari sekadar menginstal satu program.

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

• Skrip menginstal paket sistem menggunakan package manager yang terdeteksi: git, gh, python3, ffmpeg, pandoc, dan poppler-utils.
• Skrip membuat swapfile berukuran 2 GB di /swapfile jika server memiliki RAM kurang dari 1.5 GB dan tidak memiliki swap, karena proses build akan dihentikan tanpanya.
• Skrip menginstal nvm, lalu Node 24, yang merupakan versi minimum yang diperlukan Iva.
• Skrip menginstal uv, package manager Python, ke ~/.local/bin.
• Skrip melakukan clone repository ke ~/iva lalu menjalankan npm ci.
• Skrip menginstal dua paket npm global, agent-browser, yang kemudian mengunduh Chromium, dan @googleworkspace/cli.
• Skrip menjalankan wizard penyiapan, melakukan build proyek, dan membuat vault.
• Skrip menulis perintah iva ke ~/.local/bin lalu menginstal unit systemd user.

Itu adalah banyak software untuk satu baris perintah. Hal ini juga menjelaskan instruksi dalam README untuk melakukan instalasi sebagai user biasa, bukan sebagai root: shell tool milik agent nantinya berjalan dengan hak akses yang digunakan oleh penginstal. Skrip hanya memanggil sudo untuk instalasi paket dan pembuatan swapfile, melalui satu helper yang menjalankan perintah secara langsung jika Anda sudah menjadi root.

Buat pengguna khusus sebelum instalasi

Berikan Iva akun sendiri. Agent menjalankan perintah shell pada host melalui Node's child_process, tanpa container dan tanpa sandbox, sehingga akun yang digunakan menjadi batas keamanan.

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 penting karena Iva berjalan sebagai unit systemd user. Tanpa linger, systemd menghentikan service milik pengguna tersebut segera setelah sesi terakhirnya berakhir. Akibatnya, assistant akan berhenti ketika Anda menutup SSH. Aturan yang sama berlaku untuk setiap service dan timer yang Anda tulis sendiri di bawah systemd.

Akun tersebut hanya memerlukan sudo selama installer menambahkan paket. Hapus setelah instalasi selesai.

sudo deluser iva sudo

Login langsung melalui SSH sebagai pengguna tersebut. Shell yang Anda masuki dengan sudo -iu iva tidak memiliki DBUS_SESSION_BUS_ADDRESS atau XDG_RUNTIME_DIR, sehingga setiap perintah systemctl --user gagal dengan Failed to connect to bus. Penetapan batas ini merupakan langkah yang sama seperti menjalankan service dengan pengguna berhak istimewa minimum.

Instal rilis yang dipatok, bukan meneruskan skrip ke bash

Installer memiliki perilaku yang berguna. Sebelum melakukan clone, installer memeriksa apakah direktori tempat skrip berada sudah berisi package.json yang memuat "eve". Jika ya, installer membangun checkout tersebut dan melewati proses clone. Dengan demikian, Anda dapat memilih versinya sendiri.

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

Sekarang Anda mengetahui kode yang sedang berjalan. Hal itu tidak diketahui ketika skrip melakukan clone main pada keadaan apa pun yang sedang berlaku pada jam tersebut. Iva merilis lima rilis antara 4 dan 6 Agustus 2026, sehingga main pagi ini dan main sore ini bukan program yang sama.

Checkout tag membuat git berada dalam status detached HEAD. Ini tetap berjalan dengan baik, tetapi pahami batasannya: iva update memindahkan checkout ke depan pada update branch, sehingga pin tersebut merupakan titik awal yang diketahui, bukan pembekuan permanen. iva version menampilkan versi paket dan commit git, sehingga Anda selalu dapat melihat posisi checkout saat ini.

Untuk berpindah ke rilis yang lebih baru secara sengaja, tampilkan daftar tag, tetapkan IVA_TAG ke tag yang dipilih, lalu jalankan kembali installer dari dalam checkout tersebut.

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 mencegah wizard berjalan lagi pada .env yang sudah berfungsi.

Lima langkah wizard dan kunci yang dimintanya

1. Penyedia model dan model. MODEL_PROVIDER menerima opencode, ollama, openrouter, atau codex. Wizard memvalidasi kunci secara langsung dan mencantumkan model yang tersedia untuk paket Anda.
2. Suara dan pencarian. Kunci Deepgram mentranskripsikan pesan suara. Kunci pencarian web (Tavily, Exa, Parallel, atau Brave) bersifat opsional.
3. Token bot Telegram dari @BotFather, yang diperiksa terhadap endpoint getMe.
4. Kontrol akses. Kirim pesan ke bot Anda, lalu wizard membaca ID pengguna numerik Anda dari getUpdates.
5. Pengaturan sistem. Zona waktu IANA, direktori vault, dan port lokal, yaitu 8723 secara default.

Dua di antaranya adalah dependensi yang disembunyikan oleh konsep "satu perintah". Iva tidak menyertakan model, sehingga memerlukan paket model berbayar atau kunci API sebelum dapat menjawab apa pun. Iva juga tidak mentranskripsikan audio sendiri, sehingga pesan suara memerlukan layanan terpisah. Model Deepgram nova-3 dengan DEEPGRAM_LANGUAGE=multi mendeteksi bahasa, dan akun Deepgram baru mendapatkan kredit awal yang cukup untuk penggunaan pribadi selama berbulan-bulan. Teks dapat digunakan hanya dengan kunci model. Hanya suara yang bergantung pada Deepgram.

Periksa hasil yang ditulis wizard.

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

ls harus menampilkan -rw------- dengan mode 0600 karena file tersebut menyimpan semua kunci yang baru saja Anda tempelkan. TELEGRAM_ALLOWED_USER_IDS harus menyimpan ID numerik Anda. Allowlist menggunakan kebijakan fail closed, sehingga nilai kosong berarti Iva tidak menjawab siapa pun.

Model dibaca sekali saat proses dimulai. Mengedit MODEL_PROVIDER atau nama model di .env tidak mengubah apa pun sampai Anda menjalankan iva restart. Pada openrouter, nama model berupa slug vendor seperti anthropic/claude-sonnet-4.5, bukan nama tanpa prefiks. Pada codex, tidak ada kunci API sama sekali: iva login login ke langganan ChatGPT yang sudah ada.

Biaya menjalankan Iva setiap bulan

[
  {
    "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 yang tercantum dan dipublikasikan per Agustus 2026, bukan hasil pengukuran. VPS kecil seharga 5 dolar AS ditambah paket OpenCode Go seharga 5 dolar merupakan konfigurasi lengkap termurah, sekitar 10 dolar per bulan. Ollama Cloud adalah opsi tarif tetap lainnya dengan biaya 20 dolar, dan model frontier-nya ditagihkan sebagai penggunaan tambahan di luar paket. Biaya voice adalah 0 selama kredit awal Deepgram masih tersedia.

OpenRouter tidak dicantumkan di sini karena menggunakan skema bayar sesuai penggunaan, sehingga tagihan mengikuti penggunaan Anda. Opsi ini perlu dipantau: assistant yang membawa context window 131072 token pada setiap giliran dapat dengan cepat menghabiskan biaya lebih besar daripada paket tarif tetap. Atur variabel context window sesuai ukuran sebenarnya model, karena nilai yang terlalu besar hanya membuang token.

Dua service dan dua timer

• iva.service menjalankan agent itu sendiri.
• iva-telegram-poll.service menjalankan bridge long polling yang berkomunikasi dengan Telegram.
• iva-memory-doctor.timer aktif pada 05:00 dan menjalankan pemeliharaan malam pada vault.
• iva-update-check.timer aktif pada 10:00 dan memeriksa apakah tersedia rilis yang lebih baru.
• iva-telegram-userbot.service hanya ada jika Anda menyiapkan proxy Telethon opsional.

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

iva status melaporkan kedua service dan kedua timer watchdog. systemctl --user list-timers menampilkan waktu eksekusi berikutnya untuk setiap timer. Dengan demikian, Anda dapat memastikan bahwa memory doctor benar-benar akan berjalan malam ini. Kedua service harus berada dalam status active (running). Jika salah satunya restart berulang kali, journalctl --user -u iva.service -n 100 menampilkan penyebabnya.

Pemisahan ini penting saat melakukan debugging. Bridge dapat aktif dan terus melakukan polling saat agent berhenti. Dalam kondisi itu, Telegram menerima pesan Anda, tetapi tidak ada yang menjawabnya. iva logs poll memantau bridge, sedangkan iva logs memantau agent. Dengan demikian, kedua log tersebut menunjukkan bagian mana yang mengalami kerusakan.

Lokasi vault Obsidian dan cara mencadangkannya

ASSISTANT_VAULT_DIR secara default berada di vault di dalam direktori instalasi, sehingga memori tersimpan di ~/iva/vault. Direktori ini merupakan repositori git tersendiri, terpisah dari kode. Karena itu, Anda dapat memperbarui Iva tanpa menyentuh catatan.

• vault/CORE.md menyimpan fakta yang berlaku terus-menerus dan preferensi tetap, dengan batas 1200 karakter, serta disertakan dalam setiap system prompt.
• vault/daily/YYYY-MM-DD.md adalah transkrip harian yang hanya ditambahkan.
• vault/cards/ menyimpan card bertipe untuk kontak, proyek, keputusan, ide, dan catatan.
• vault/summaries/daily/, weekly/, monthly/, dan yearly/ menyimpan ringkasan berjenjang.
• vault/attachments/ menyimpan file berdasarkan tanggal, sedangkan vault/.graph/ menyimpan graph tautan.
• vault/schema.json menentukan tipe card dan aturan peluruhan.

Proses ringkasan berjalan sesuai jadwal di dalam proses. Proses harian pada 04:00 mengubah transkrip kemarin menjadi card dan ringkasan, lalu menulis ulang CORE.md. Setelah itu, proses mingguan, bulanan, dan tahunan meringkas hasil tersebut secara bertahap. Pada 05:00, memory doctor menjalankan proses deterministik tanpa melibatkan model: proses ini menerapkan schema, membangun ulang graph tautan, membuat ulang indeks, lalu melakukan commit dan push.

Push tersebut adalah cadangan Anda, dan langkah inilah yang sering terlewat. Jika vault tidak memiliki git remote, doctor mencoba membuat repositori GitHub privat melalui gh. Proses ini memerlukan GitHub CLI yang sudah terautentikasi.

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

Commit bertanggal hari ini berarti proses tersebut telah berjalan dan vault sudah di-commit. Peringatan gh not available di log menunjukkan hal sebaliknya: vault dikelola, tetapi tidak pernah keluar dari server. Akibatnya, jika VPS mati, memori Anda ikut hilang.

Simpan juga salinan yang Anda kendalikan sendiri.

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

Salin file tersebut dari server menggunakan scp, lalu hapus file itu dari server. Untuk membaca memori di Obsidian, arahkan Obsidian ke clone repositori vault. Wikilink dan backlink akan tetap berfungsi, begitu pula tampilan graph. Mengedit card dan CORE.md secara manual aman. Jangan mengubah MOC.md dan .graph/, karena proses malam akan membuat ulang keduanya.

Anggap vault sebagai catatan kehidupan Anda

Direktori tersebut merupakan catatan bertanggal tentang apa yang Anda katakan, siapa yang Anda temui, dan keputusan yang Anda ambil, pada mesin yang Anda sewa. Ada dua hal yang perlu diperhatikan.

Self-hosting memindahkan penyimpanan, bukan pemrosesan. Setiap giliran percakapan dikirim ke penyedia model Anda, dan setiap catatan suara dikirim ke Deepgram. Vault tersebut milik Anda. Namun, permintaan tersebut tidak bersifat privat dari perusahaan yang memprosesnya. Menjalankan lapisan memori sendiri, seperti server memori Mem0 pada VPS Anda sendiri, memiliki pola yang sama: penyimpanan berada secara lokal, sedangkan pemanggilan model tetap meninggalkan server Anda. Jika suatu topik terlalu sensitif untuk pihak ketiga, jangan masukkan topik tersebut ke dalam chat.

Jangkauan akun tersebut mencakup seluruh vault. Iva menjalankan tool secara native pada host melalui Node's fs dan child_process, tanpa Docker dan tanpa sandbox, sehingga giliran percakapan yang dibajak memiliki akses apa pun yang dimiliki oleh user service tersebut. Karena itu, akun tersebut tidak memiliki sudo setelah instalasi, dan allowlist perlu diperhatikan lebih cermat daripada yang terlihat: allowlist merupakan gerbang yang menentukan pesan siapa yang dapat menjadi perintah pada server Anda. Jika Anda ingin menggunakan assistant dari ponsel tanpa membuka akses apa pun, pola yang sama digunakan untuk mengakses agent Hermes yang di-host sendiri dari ponsel, dengan chat client yang menjalankan fungsi yang biasanya dilakukan oleh endpoint publik.

Hal yang dapat gagal dan pesan yang akan Anda lihat

Build dihentikan, exit 137. OOM killer pada kernel menghentikan build. Installer hanya menambahkan swap jika RAM kurang dari 1.5 GB dan tidak ada swap, jadi tambahkan swap sendiri lalu jalankan installer lagi.

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

Failed to connect to bus. Setiap perintah systemctl --user menampilkan pesan ini jika shell tidak memiliki user session bus, yang disediakan oleh sudo -iu iva. Buka sesi SSH normal sebagai user tersebut, atau export XDG_RUNTIME_DIR=/run/user/$(id -u iva) sebelum menjalankan perintah.

Bot mengabaikan Anda. TELEGRAM_ALLOWED_USER_IDS kosong dan allowlist menggunakan kebijakan fail closed. Kirim pesan kepada bot. Bot akan membalas dengan ID numerik Anda dan tidak mengirim apa pun lagi. Masukkan ID tersebut ke .env lalu jalankan iva restart.

Bot langsung diam setelah iva config. Wizard dapat memindahkan IVA_PORT tanpa memperbarui ASSISTANT_HOST, sehingga bridge terhubung ke port yang tidak menerima respons apa pun. Bandingkan kedua baris tersebut, lalu restart.

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

Pesan suara tidak mendapat balasan. Telegram Bot API menolak download file yang berukuran lebih dari 20 MB, sehingga bridge tidak pernah menerima audio panjang dan tidak dapat mengirimkannya ke Deepgram. Bagi file tersebut sebelum mengirimnya.

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

Satu giliran macet dan tidak pernah mendapat balasan. State workflow yang macet tetap ada setelah restart dan memasukkan dirinya kembali ke antrean, sehingga restart saja tidak menghapusnya. iva reset mengarantina state tersebut dan me-restart kedua service. /new di chat memulai percakapan baru.

Chromium gagal di Ubuntu 24.04. Ubuntu 24.04 memblokir user namespace tanpa hak istimewa melalui AppArmor, sehingga sandbox milik Chromium tidak dapat berjalan dan agent-browser gagal. Installer mengatasinya dengan menulis "--no-sandbox" ke ~/.agent-browser/config.json. Pastikan Anda mengetahui konfigurasi ini. Konfigurasi tersebut mengurangi isolasi browser, sehingga akun tersebut sebaiknya tidak memiliki apa pun selain Iva.

FAQ

Apakah saya memerlukan domain atau port terbuka untuk melakukan self-hosting Iva?

Tidak. Iva berkomunikasi dengan Telegram melalui long polling: iva-telegram-poll.service memanggil getUpdates lalu menunggu, sehingga setiap koneksi berasal dari server Anda. Tidak ada koneksi dari luar yang perlu mencapai server tersebut, jadi Anda tidak memerlukan catatan DNS atau sertifikat. Port HTTP milik agent, 8723, terikat pada 127.0.0.1, dan dokumentasi proyek menyarankan agar port tersebut tidak diekspos. Konfigurasi yang tepat adalah firewall yang hanya mengizinkan SSH.

Berapa biaya menjalankan Iva setiap bulan?

Berdasarkan harga daftar yang dipublikasikan pada August 2026, VPS kecil seharga 5 dolar ditambah paket model flat rate termurah seharga 5 dolar berjumlah sekitar 10 dolar AS per bulan. Ollama Cloud berbiaya 20 dolar, lalu menagihkan penggunaan frontier model secara terpisah. Kredit awal Deepgram mencukupi untuk penggunaan suara pada tahap awal, dan tingkatan web search menyediakan kuota gratis. OpenRouter menggunakan sistem pay as you go, sehingga tidak memiliki biaya bulanan tetap.

Di mana Iva menyimpan data saya, dan bagaimana cara mencadangkannya?

Secara default, data disimpan di ~/iva/vault dan ditetapkan oleh ASSISTANT_VAULT_DIR. Data tersebut berada dalam private git repository terpisah yang berisi markdown biasa: CORE.md, daily/YYYY-MM-DD.md, cards/, dan summaries/. Memory doctor pada pukul 05:00 melakukan commit dan push, tetapi ini hanya berguna jika repository memiliki remote. Karena itu, jalankan gh auth login atau tambahkan remote milik Anda sendiri selama setup. Simpan juga salinan offline dengan tar czf ~/iva-vault-backup.tgz -C ~/iva vault, lalu pindahkan file tersebut dari server.

Apakah data saya tetap privat jika saya melakukan self-hosting Iva?

Penyimpanannya adalah milik Anda. Pemrosesannya tidak. Vault tetap berada di disk Anda sampai Anda melakukan push, dan .env memiliki mode 0600 serta dimiliki oleh service user. Pemanggilan model dan transkripsi suara menggunakan cloud API, sehingga pesan tersebut melewati penyedia model dan Deepgram Anda. Iva menggunakan lisensi MIT, sehingga Anda dapat membaca secara tepat data yang dikirimnya dan mengubahnya. Telegram allowlist menerapkan fail closed. Artinya, TELEGRAM_ALLOWED_USER_IDS yang kosong akan memblokir semua orang, termasuk Anda.

Penyedia model apa yang didukung Iva?

MODEL_PROVIDER menerima opencode (OpenCode Go), ollama (Ollama Cloud), openrouter, dan codex. OpenRouter menggunakan vendor slug seperti anthropic/claude-sonnet-4.5 dan menyediakan pilihan model paling luas. codex masuk ke subscription ChatGPT yang sudah ada menggunakan iva login dan tidak menggunakan API key. Tetapkan provider, tetapkan context window yang sesuai dengan ukuran sebenarnya model, lalu jalankan iva restart, karena model hanya dibaca sekali saat proses dimulai.