Як розгорнути Iva як Telegram AI-асистента

Що ви розгортаєте

Iva — це self-hosted AI-асистент для Telegram. Це один із небагатьох асистентів, які можна розгорнути без відкриття вхідного порту та без прив’язування домену. Сертифікат також не потрібен, оскільки жоден процес на сервері не приймає публічні вхідні з’єднання. Сервіс сам встановлює вихідне з’єднання з Telegram, підтримує його відкритим і отримує ваші повідомлення у відповіді. Усе інше залежить від цього єдиного вихідного з’єднання.

Iva поширюється за ліцензією MIT і написаний на Node. Його пам’ять зберігається в каталозі зі звичайними markdown-файлами, які Obsidian відкриває безпосередньо. Тому нотатки, які асистент зберігає про вас, залишаються читабельними без цього застосунку. У цьому посібнику зафіксовано release v0.3.13, опублікований 6 August 2026.

Більшість self-hosted програм починається із запису DNS (domain name system) і сертифіката Let's Encrypt, виданого за допомогою Certbot. Iva повністю обходить цей рівень. Тому невеликого VPS за firewall, який дозволяє лише SSH, достатньо для повного розгортання.

Чому Iva не потребує відкритих портів

iva-telegram-poll.service — це міст long polling. Він звертається до getUpdates API Telegram і очікує на відповідь, тому кожне з’єднання починається з вашого сервера. Telegram ніколи не підключається назад. Тому не потрібно налаштовувати reverse proxy або поновлювати сертифікати.

Сам агент прослуховує лише порт 8723 на 127.0.0.1. Документація проєкту прямо вказує: не відкривайте порт 8723 назовні, а reverse proxy перед агентом має зберігати вимогу bearer token. Після встановлення перевірте адресу прив’язки.

sudo ss -tlnp | grep 8723

Адреса має бути 127.0.0.1:8723. Адреса з wildcard, наприклад 0.0.0.0:8723, робить HTTP-маршрути агента доступними з інтернету. Це потрібно виправити до того, як ви передасте боту будь-які приватні дані.

Тому firewall залишається закритим. Перед увімкненням дозвольте SSH, оскільки ufw enable без правила для SSH закриє поточний сеанс.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Що насправді робить однорядковий інсталятор

Головна сторінка проєкту містить одну команду, яка передає скрипт із GitHub до bash через pipe. Спочатку прочитайте цей скрипт, оскільки він робить значно більше, ніж встановлює одну програму.

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

• Він встановлює системні пакети за допомогою визначеного менеджера пакетів: git, gh, python3, ffmpeg, pandoc і poppler-utils.
• Він створює swapfile розміром 2 GB у /swapfile, якщо на сервері менше ніж 1.5 GB RAM і немає swap, оскільки без нього процес збірки завершується примусово.
• Він встановлює nvm, а потім Node 24 — мінімальну версію, на якій працює Iva.
• Він встановлює uv, менеджер пакетів Python, у ~/.local/bin.
• Він клонує репозиторій у ~/iva і запускає npm ci.
• Він встановлює два глобальні npm-пакети: agent-browser, який потім завантажує Chromium, і @googleworkspace/cli.
• Він запускає майстер налаштування, збирає проєкт і створює vault.
• Він записує команду iva у ~/.local/bin і встановлює користувацькі unit-файли systemd.

Для однієї команди це багато програм. Це також пояснює інструкцію в README встановлювати програму від звичайного користувача, а не від root: shell tool агента пізніше працює з тими самими привілеями, які мав інсталятор. Скрипт викликає sudo лише для встановлення пакетів і створення swapfile, використовуючи один допоміжний механізм, який виконує команди безпосередньо, якщо ви вже працюєте від root.

Створіть окремого користувача перед встановленням

Створіть для Iva окремий обліковий запис. Агент виконує команди shell на хості через Node's child_process, без контейнера та sandbox, тому обліковий запис, від імені якого він працює, є межею безпеки.

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 має значення, оскільки Iva працює як user units systemd. Без linger systemd зупиняє служби цього користувача одразу після завершення останнього сеансу. Тому асистент завершить роботу, щойно ви закриєте SSH. Це саме правило стосується будь-яких служб і таймерів, які ви самостійно створюєте в systemd.

Обліковому запису потрібен sudo лише на час, коли інсталятор додає пакети. Після завершення встановлення заберіть цей доступ.

sudo deluser iva sudo

Увійдіть безпосередньо через SSH від імені цього користувача. Shell, який ви запускаєте за допомогою sudo -iu iva, не має встановлених DBUS_SESSION_BUS_ADDRESS і XDG_RUNTIME_DIR, тому кожна команда systemctl --user завершується помилкою Failed to connect to bus. Визначення цієї межі є таким самим завданням, як запуск служб від імені користувачів із мінімальними привілеями.

Встановлення зафіксованого релізу замість передавання скрипту в bash

Інсталятор має корисну властивість. Перш ніж клонувати щось, він перевіряє, чи містить каталог, у якому розташований скрипт, уже наявний package.json із "eve". Якщо так, він збирає цей checkout і пропускає клонування. Тому версію можна вибрати самостійно.

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

Тепер ви знаєте, який код виконується. Якщо скрипт клонуватиме main у тому стані, у якому репозиторій опиниться в цю годину, такої визначеності не буде. Iva випустила п’ять релізів у період із 4 до 6 August 2026, тому main цього ранку та main цього дня після обіду — це різні програми.

Checkout за tag залишає git у стані detached HEAD. Це працює, але потрібно розуміти обмеження: iva update переміщує checkout уперед на гілку оновлень, тому pin є відомою початковою точкою, а не постійним блокуванням версії. iva version виводить версію пакета та git commit, тож завжди можна перевірити поточний стан.

Щоб навмисно перейти до пізнішого релізу, виведіть список tag, задайте IVA_TAG вибраному tag, а потім знову запустіть інсталятор з каталогу 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 не дає майстру повторно запускатися поверх .env, який уже працює.

П’ять кроків майстра та ключі, які він запитує

1. Провайдер моделі та модель. MODEL_PROVIDER приймає opencode, ollama, openrouter або codex. Майстер перевіряє ключ у реальному часі та показує моделі, доступні у вашому тарифному плані.
2. Голосовий ввід і пошук. Ключ Deepgram перетворює голосові повідомлення на текст. Ключ вебпошуку (Tavily, Exa, Parallel або Brave) необов’язковий.
3. Токен Telegram-бота від @BotFather. Майстер перевіряє його через кінцеву точку getMe.
4. Контроль доступу. Надішліть повідомлення своєму боту, і майстер зчитає ваш числовий ID користувача з getUpdates.
5. Системні параметри. Часовий пояс IANA, каталог vault і локальний порт; типовий порт — 8723.

Дві з цих залежностей приховані формулюванням «одна команда». Iva не постачається з моделлю, тому до першої відповіді їй потрібен платний тарифний план моделі або API key. Вона також не транскрибує аудіо самостійно, тому для голосових повідомлень потрібен окремий сервіс. Модель Deepgram nova-3 з параметром DEEPGRAM_LANGUAGE=multi визначає мову, а нові облікові записи Deepgram отримують стартові кредити, яких достатньо для кількох місяців особистого використання. Текст працює лише з ключем моделі. Від Deepgram залежить лише голосовий ввід.

Перевірте, що записав майстер.

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

ls має вивести -rw------- з правами доступу 0600, оскільки цей файл містить усі щойно вставлені ключі. TELEGRAM_ALLOWED_USER_IDS має містити ваш числовий ID. Список дозволених користувачів працює за принципом fail closed, тому порожнє значення означає, що Iva нікому не відповідає.

Модель зчитується один раз під час запуску процесу. Редагування MODEL_PROVIDER або назви моделі у .env нічого не змінить, доки ви не виконаєте iva restart. У openrouter назва моделі має бути vendor slug, наприклад anthropic/claude-sonnet-4.5, а не лише назвою. У codex API key взагалі немає: iva login виконує вхід до наявної підписки ChatGPT.

Скільки коштує щомісяця запуск 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
  }
]

Це опубліковані роздрібні ціни станом на August 2026, а не результати вимірювань. Невеликий VPS за 5 доларів США плюс план OpenCode Go за 5 доларів — найдешевша повна конфігурація, приблизно 10 доларів на місяць. Ollama Cloud — інший варіант із фіксованою оплатою: 20 доларів, а використання frontier models оплачується додатково понад вартість плану. Voice коштує 0, доки діють стартові кредити Deepgram.

OpenRouter не наведено в таблиці, оскільки оплата здійснюється за фактичне використання, тому рахунок залежить від обсягу запитів. Саме цей варіант потребує уваги: асистент, який передає в кожен запит контекстне вікно на 131072 токенів, швидко може перевищити вартість плану з фіксованою оплатою. Установіть для змінної контекстного вікна фактичний розмір моделі, оскільки завищене значення лише витрачає токени.

Два сервіси та два таймери

• iva.service запускає сам агент.
• iva-telegram-poll.service запускає міст довгого опитування, який взаємодіє з Telegram.
• iva-memory-doctor.timer спрацьовує о 05:00 і запускає нічне обслуговування vault.
• iva-update-check.timer спрацьовує о 10:00 і перевіряє наявність новішого релізу.
• iva-telegram-userbot.service існує лише в разі налаштування необов’язкового проксі Telethon.

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

iva status показує стан обох сервісів і обох watchdog-таймерів. systemctl --user list-timers виводить час наступного запуску кожного таймера. Так можна перевірити, що memory doctor справді запуститься сьогодні вночі. Обидва сервіси мають перебувати у стані active (running). Якщо один із них постійно перезапускається, journalctl --user -u iva.service -n 100 показує причину.

Такий поділ важливий під час налагодження. Міст може працювати й виконувати опитування, поки агент недоступний. У такому разі Telegram приймає ваше повідомлення, але відповідь не надходить. iva logs poll відстежує міст, а iva logs — агента. Тому два журнали показують, яка саме частина не працює.

Де зберігається сховище Obsidian і як створювати його резервні копії

ASSISTANT_VAULT_DIR за замовчуванням має значення vault у каталозі встановлення, тому пам’ять зберігається в ~/iva/vault. Це окремий git-репозиторій, відокремлений від коду. Завдяки цьому можна оновлювати Iva, не змінюючи нотатки.

• vault/CORE.md містить довготривалі факти та постійні налаштування. Його розмір обмежено 1200 символами, і він додається до кожного системного промпту.
• vault/daily/YYYY-MM-DD.md містить транскрипт поточного дня. Дані до нього лише додаються.
• vault/cards/ містить типізовані картки для контактів, проєктів, рішень, ідей і нотаток.
• vault/summaries/daily/, weekly/, monthly/ і yearly/ містять зведені дані.
• vault/attachments/ містить файли, упорядковані за датами, а vault/.graph/ — граф зв’язків.
• vault/schema.json визначає типи карток і правила згасання.

Зведені дані формуються за розкладом усередині процесу. Щоденний запуск о 04:00 перетворює транскрипт за вчора на картки та зведення і перезаписує CORE.md. Потім щотижневий, щомісячний і щорічний запуски послідовно стискають ці дані. О 05:00 memory doctor виконує детермінований запуск без залучення моделі: перевіряє схему, перебудовує граф зв’язків, повторно генерує індекс, а потім виконує commit і push.

Цей push є резервною копією. Саме цей крок часто пропускають. Якщо у сховища немає git remote, doctor намагається створити приватний репозиторій GitHub через gh. Для цього потрібен автентифікований GitHub CLI.

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

Commit із сьогоднішньою датою означає, що запуск відбувся і сховище зафіксовано. Попередження gh not available у журналі означають протилежне: сховище обслуговується, але ніколи не залишає сервер. Тому відмова VPS призведе до втрати пам’яті.

Також зберігайте копію, яку контролюєте самостійно.

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

Скопіюйте цей файл із сервера за допомогою scp, а потім видаліть його із сервера. Щоб читати пам’ять в Obsidian, укажіть Obsidian на клон репозиторію сховища. Wikilinks і backlinks працюватимуть без змін, як і подання графа. Картки та CORE.md можна безпечно редагувати вручну. Не змінюйте MOC.md і .graph/, оскільки нічний запуск повторно генерує обидва файли.

Сприймайте vault як журнал свого життя

Цей каталог є датованим записом того, що ви сказали, з ким зустрілися та що вирішили, на сервері, який ви орендуєте. З цього випливають два висновки.

Self-hosting переносить сховище, але не оброблення даних. Кожен запит надходить до вашого провайдера моделі, а кожна голосова нотатка — до Deepgram. vault належить вам. Компанії, які обробляють ці запити, усе одно їх бачать. Самостійний запуск memory layer, як у випадку з memory-сервером Mem0 на власному VPS, має таку саму особливість: сховище локальне, але виклик моделі все одно виходить за межі сервера. Якщо тема надто чутлива для стороннього сервісу, не додавайте її в чат.

Цей обліковий запис має доступ до всього vault. Інструменти Iva запускаються безпосередньо на хості через Node's fs і child_process, без Docker і sandbox, тому перехоплений запит отримує всі права, які має користувач сервісу. Саме тому після інсталяції цей обліковий запис не має sudo, а allowlist заслуговує на більшу увагу, ніж може здаватися: саме він визначає, чиї повідомлення стають командами на вашому сервері. Якщо ви хочете користуватися асистентом зі смартфона, не відкриваючи додаткових доступів, використовуйте ту саму схему, що й для доступу до self-hosted агента Hermes зі смартфона, де клієнт чату виконує роль, яку інакше виконував би публічний endpoint.

Що може зламатися і яке повідомлення ви побачите

Збірку завершено примусово, код завершення 137. OOM killer ядра завершив процес збірки через нестачу пам’яті. Інсталятор додає swap лише тоді, коли обсяг RAM менший за 1.5 GB і swap відсутній. Додайте swap вручну та знову запустіть інсталятор.

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

Failed to connect to bus. Кожна команда systemctl --user виводить це повідомлення, якщо в оболонці немає шини користувацького сеансу. Її надає sudo -iu iva. Відкрийте звичайний SSH-сеанс від імені цього користувача або експортуйте XDG_RUNTIME_DIR=/run/user/$(id -u iva) перед виконанням команди.

Бот ігнорує вас. TELEGRAM_ALLOWED_USER_IDS порожня, а список дозволених користувачів працює за принципом заборони за замовчуванням. Надішліть боту повідомлення. Він відповість лише вашим числовим ідентифікатором. Додайте цей ідентифікатор до .env і виконайте iva restart.

Бот замовкає одразу після iva config. Майстер може перемістити IVA_PORT, не оновивши ASSISTANT_HOST, тому міст підключається до порту, на якому нічого не відповідає. Порівняйте два рядки та перезапустіть служби.

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

Голосова нотатка не отримує відповіді. Bot API Telegram не дозволяє завантажувати файли розміром понад 20 MB, тому міст не отримує довгі аудіофайли й не може передати їх у Deepgram. Розділіть файл перед надсиланням.

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

Хід виконання зависає і не відповідає. Стан workflow, який завис, зберігається після перезапуску й повторно ставиться в чергу, тому самого перезапуску недостатньо. iva reset ізолює цей стан і перезапускає обидві служби. /new у чаті починає нову розмову.

Chromium не запускається в Ubuntu 24.04. Ubuntu 24.04 блокує непривілейовані user namespaces через AppArmor, тому власний sandbox Chromium не може запуститися, а agent-browser завершується помилкою. Інсталятор обходить це обмеження, записуючи "--no-sandbox" до ~/.agent-browser/config.json. Врахуйте наявність цього параметра. Він знижує рівень ізоляції браузера. Це ще одна причина, чому обліковий запис не повинен володіти нічим, крім Iva.

FAQ

Чи потрібен домен або відкритий порт для self-hosting Iva?

Ні. Iva взаємодіє з Telegram за допомогою long polling: iva-telegram-poll.service викликає getUpdates і очікує відповіді, тому кожне з’єднання є вихідним із вашого сервера. До сервера не потрібно приймати з’єднання ззовні, тому DNS-запис і сертифікат не потрібні. Власний HTTP-порт агента, 8723, прив’язаний до 127.0.0.1, а в документації проєкту вказано не відкривати його назовні. Правильною конфігурацією буде firewall, який дозволяє лише SSH і більше нічого.

Скільки коштує запускати Iva щомісяця?

За опублікованими тарифами станом на August 2026 невеликий VPS за 5 доларів плюс найдешевший план моделі з фіксованою ставкою за 5 доларів коштують разом приблизно 10 доларів США на місяць. Ollama Cloud коштує 20 доларів замість цього, а frontier-моделі оплачуються додатково. Стартових кредитів Deepgram спочатку достатньо для голосових функцій, а рівні web search мають безкоштовні ліміти. OpenRouter працює за моделлю pay as you go, тому фіксованої щомісячної суми немає.

Де Iva зберігає мої дані та як створити їхню резервну копію?

Типово дані зберігаються в ~/iva/vault, шлях визначається параметром ASSISTANT_VAULT_DIR. Це окремий приватний git-репозиторій зі звичайними markdown-файлами: CORE.md, daily/YYYY-MM-DD.md, cards/ і summaries/. О 05:00 memory doctor створює commit і виконує push. Це допомагає лише тоді, коли репозиторій має remote, тому під час налаштування виконайте gh auth login або додайте власний remote. Також зберігайте офлайн-копію за допомогою tar czf ~/iva-vault-backup.tgz -C ~/iva vault і перемістіть цей файл із сервера.

Чи приватні мої дані, якщо я самостійно розміщую Iva?

Сховище належить вам. Обробка даних — ні. Vault залишається на вашому диску, доки ви не виконаєте push, а .env має режим 0600 і належить користувачу сервісу. Виклики моделей і транскрибування голосу виконуються через cloud API, тому ці повідомлення передаються вашому постачальнику моделей і Deepgram. Iva поширюється за ліцензією MIT, тому ви можете точно перевірити, які дані вона надсилає, і змінити це. Telegram allowlist працює за принципом fail closed: порожній TELEGRAM_ALLOWED_USER_IDS блокує всіх, зокрема вас.

Яких постачальників моделей підтримує Iva?

MODEL_PROVIDER приймає opencode (OpenCode Go), ollama (Ollama Cloud), openrouter і codex. OpenRouter використовує vendor slug, наприклад anthropic/claude-sonnet-4.5, і пропонує найширший вибір моделей. codex виконує вхід до наявної підписки ChatGPT за допомогою iva login і не використовує API key. Вкажіть постачальника, задайте відповідне context window відповідно до фактичного розміру моделі, а потім виконайте iva restart, оскільки модель зчитується лише один раз під час запуску процесу.