Cara Self-Host Iva, Asisten AI Telegram

Yang Anda bangun

Iva adalah asisten AI Telegram yang di-hosting sendiri. Iva termasuk salah satu dari sedikit aplikasi yang dapat di-deploy tanpa membuka port inbound dan tanpa mengarahkan domain ke server. Sertifikat juga tidak diperlukan karena tidak ada layanan pada server yang menerima koneksi publik. Service terhubung keluar ke Telegram, mempertahankan koneksi tetap terbuka, lalu membaca pesan Anda dari respons tersebut. Seluruh mekanisme lainnya bergantung pada satu koneksi outbound itu.

Iva berlisensi MIT dan ditulis dalam Node. Memori Iva berupa folder berisi file markdown biasa yang dapat dibuka langsung dengan Obsidian. Karena itu, catatan yang disimpan tentang Anda tetap dapat dibaca tanpa aplikasi tersebut. Panduan ini menetapkan release v0.3.13, yang diterbitkan pada 6 August 2026. Repository tersebut kemudian diganti namanya dari smixs/iva menjadi smixs/iva-agent, dan perintah di bawah menggunakan nama baru.

Sebagian besar software self-hosted diawali 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

Hal yang sebenarnya dilakukan oleh penginstal satu baris

Halaman depan proyek menyediakan satu perintah yang meneruskan skrip dari GitHub ke bash. Baca skrip tersebut terlebih dahulu karena skrip itu melakukan jauh lebih banyak daripada hanya menginstal satu program.

curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/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 tanpa swap.
• Skrip menginstal nvm, lalu Node 24, yang merupakan versi minimum untuk menjalankan Iva.
• Skrip menginstal uv, package manager Python, ke ~/.local/bin.
• Skrip melakukan clone repository ke ~/iva, lalu menjalankan npm ci.
• Skrip menginstal agent-browser sebagai package npm global. Package tersebut kemudian mengunduh Chromium dan menempatkan Google Workspace CLI, gws, di ~/.local tanpa sudo.
• Skrip menjalankan wizard setup, melakukan build terhadap proyek, dan membuat vault.
• Skrip menulis perintah iva ke ~/.local/bin, lalu menginstal unit user systemd.

Satu baris tersebut menginstal banyak software. Hal ini juga menjelaskan instruksi pada README untuk melakukan instalasi sebagai user biasa, bukan sebagai root: shell tool milik agent nantinya berjalan dengan hak akses yang dimiliki saat penginstalan. Skrip memanggil sudo hanya untuk instalasi package dan pembuatan swapfile, serta mungkin satu kali lagi pada tahap Chromium, 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 tertentu, bukan meneruskan skrip ke bash

Installer memiliki properti yang berguna. Sebelum melakukan clone, installer memeriksa apakah direktori tempat skrip berada sudah berisi package.json yang memuat "eve". Jika ya, installer akan 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-agent.git ~/iva
cd ~/iva
git log -1 --oneline
bash install.sh

Sekarang Anda mengetahui kode yang sedang berjalan. Anda tidak akan mengetahui hal itu jika skrip melakukan clone terhadap main pada status apa pun yang kebetulan dimilikinya pada jam tersebut. Iva merilis lima versi antara 4 dan 6 August 2026, sehingga main pada pagi ini dan main pada sore ini bukan program yang sama.

Checkout tag membuat git berada dalam keadaan detached HEAD. Ini tetap dapat berjalan, tetapi pahami batasannya: iva update memindahkan checkout ke depan, ke 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 Anda.

Untuk berpindah ke rilis yang lebih baru secara sengaja, tampilkan daftar tag, checkout tag yang Anda pilih sebagai pengganti v0.3.13 di bawah ini, lalu jalankan kembali installer dari dalam checkout tersebut. Installer tidak memiliki pengaturan untuk release tag. Variabel lingkungan yang didokumentasikan adalah REPO_URL, BRANCH, dan INSTALL_DIR, sehingga checkout git merupakan satu-satunya mekanisme untuk menetapkan pin.

cd ~/iva
git fetch --tags
git tag --list 'v*' | sort -V | tail -5
git checkout v0.3.13
bash install.sh --skip-setup
iva restart

--skip-setup mencegah wizard berjalan kembali pada .env yang sudah berfungsi. Setelah itu, jalankan iva version untuk mengonfirmasi commit yang digunakan.

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.

Berapa biaya operasional Iva setiap bulan

[
  {
    "plan": "Small VPS, always on",
    "usd_per_month": 5
  },
  {
    "plan": "OpenCode Go model plan",
    "usd_per_month": 10
  },
  {
    "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": 15
  }
]

Berikut adalah harga resmi yang dipublikasikan per Oktober 2026, bukan hasil pengukuran. VPS kecil seharga 5 dolar AS ditambah paket OpenCode Go seharga 10 dolar merupakan penyiapan lengkap termurah, yaitu sekitar 15 dolar per bulan. Halaman Go milik OpenCode mencantumkan harga bulanan tersebut tanpa diskon bulan pertama, dan README Iva menyebut total biaya stack yang sama sekitar 14 hingga 15 dolar. Ollama Cloud adalah opsi tarif tetap lainnya, yaitu 20 dolar untuk paket Pro, sedangkan penggunaan yang melampaui kredit yang termasuk dalam paket akan ditagihkan secara terpisah. Biaya voice adalah 0 selama kredit awal Deepgram masih tersedia.

OpenRouter tidak dicantumkan di sini karena menggunakan model pay as you go, sehingga tagihan mengikuti penggunaan Anda. Opsi ini perlu dipantau: asisten yang membawa context window 131072 token pada setiap giliran dapat dengan cepat menghabiskan biaya lebih besar daripada paket tarif tetap. Tetapkan variabel context window sesuai ukuran sebenarnya dari model, karena nilai yang terlalu besar hanya memboroskan 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 data DNS atau sertifikat. Port HTTP milik agent, yaitu 8723, terikat pada 127.0.0.1, dan dokumentasi proyek menyarankan agar port tersebut tidak diekspos. Konfigurasi firewall yang benar adalah hanya mengizinkan SSH dan tidak mengizinkan koneksi lainnya.

Berapa biaya menjalankan Iva setiap bulan?

Menurut harga daftar yang dipublikasikan pada Oktober 2026, VPS kecil seharga 5 dolar ditambah paket model flat rate termurah seharga 10 dolar menjadi sekitar 15 dolar AS per bulan. Ollama Cloud mengenakan biaya 20 dolar sebagai gantinya, serta menagih penggunaan yang melebihi kredit yang disertakan. Kredit awal Deepgram cukup untuk kebutuhan suara pada tahap awal, dan tingkat layanan web search memiliki kuota gratis. OpenRouter menggunakan skema 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 ditentukan oleh ASSISTANT_VAULT_DIR. Direktori tersebut adalah git repository privat terpisah yang berisi markdown biasa: CORE.md, daily/YYYY-MM-DD.md, cards/, dan summaries/. Memory doctor pada 05:00 melakukan commit dan push, tetapi ini hanya membantu jika repository memiliki remote. Karena itu, jalankan gh auth login atau tambahkan remote sendiri saat setup. Simpan juga salinan offline dengan tar czf ~/iva-vault-backup.tgz -C ~/iva vault, lalu pindahkan file tersebut dari server.

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

Penyimpanannya berada di bawah kendali 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 API cloud, sehingga pesan tersebut melewati provider model Anda dan Deepgram. Iva menggunakan lisensi MIT, sehingga Anda dapat membaca secara tepat data yang dikirimnya dan mengubahnya. Telegram allowlist menggunakan mekanisme fail closed. Artinya, TELEGRAM_ALLOWED_USER_IDS yang kosong akan memblokir semua orang, termasuk Anda.

Provider model apa yang didukung Iva?

Dalam rilis v0.3.13 yang dipin, 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. Rilis berikutnya menambahkan route lain, termasuk subscription Claude dan endpoint kompatibel OpenAI kustom. Tetapkan provider, tetapkan context window yang sesuai dengan ukuran sebenarnya model, lalu jalankan iva restart karena model dibaca sekali saat proses dimulai.