Как развернуть Iva: self-hosted AI-ассистент в Telegram

Что вы создаете

Iva — это self-hosted AI-ассистент для Telegram. Это одно из немногих решений, которое можно развернуть, не открывая входящие порты и не привязывая доменное имя. Сертификаты также не требуются, так как ни один компонент системы не ожидает подключений извне. Сервис сам инициирует соединение с Telegram, поддерживает его в активном состоянии и считывает ваши сообщения из ответов. Все остальные функции работают на основе этого исходящего соединения.

Iva распространяется по лицензии MIT и написана на Node. Память ассистента представляет собой папку с обычными markdown-файлами, которые можно открыть напрямую через Obsidian, поэтому заметки остаются доступными для чтения даже без самого приложения. В этом руководстве используется релиз v0.3.13, выпущенный 6 августа 2026 года.

Большинство self-hosted решений требуют настройки DNS-записи и сертификата Let's Encrypt, выпущенного с помощью Certbot. Iva полностью исключает этот уровень, поэтому для развертывания достаточно небольшого VPS за межсетевым экраном, который разрешает только SSH-трафик.

Почему Iva не требует открытых портов

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

Сам агент действительно прослушивает порт 127.0.0.1 8723. Документация проекта прямо указывает: не открывайте порт 8723 во внешний мир, а любой reverse proxy, установленный перед агентом, должен требовать bearer token. Проверьте адрес привязки (bind address) после установки.

sudo ss -tlnp | grep 8723

Адрес должен выглядеть как 127.0.0.1:8723. Использование wildcard-адреса, такого как 0.0.0.0:8723, означает, что HTTP-маршруты агента доступны из Интернета. Исправьте это, прежде чем передавать боту какие-либо конфиденциальные данные.

Таким образом, файрвол должен оставаться закрытым. Разрешите SSH перед его включением, так как ufw enable без правила для SSH немедленно разорвет текущую сессию.

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Что на самом деле делает однострочный установщик

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

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 оперативной памяти и отсутствует swap, так как без него процесс сборки будет принудительно завершен.
• Устанавливает nvm, а затем Node 24 — минимальную версию, необходимую для работы Iva.
• Устанавливает uv, менеджер пакетов Python, в директорию ~/.local/bin.
• Клонирует репозиторий в ~/iva и выполняет npm ci.
• Устанавливает два глобальных npm-пакета: agent-browser (который затем загружает Chromium) и @googleworkspace/cli.
• Запускает мастер настройки, выполняет сборку проекта и создает хранилище (vault).
• Записывает команду iva в ~/.local/bin и устанавливает пользовательские юниты systemd.

Это большой объем программного обеспечения для одной команды. Это также объясняет рекомендацию в README выполнять установку от имени обычного пользователя, а не root: оболочка агента впоследствии будет работать с теми же привилегиями, что были у установщика. Скрипт вызывает sudo только для установки пакетов и создания файла подкачки через вспомогательный инструмент, который выполняет команды напрямую, если вы уже работаете под root.

Создание выделенного пользователя перед установкой

Выделите для Iva отдельную учетную запись. Агент выполняет shell-команды на хосте через child_process Node, без использования контейнеров или песочниц, поэтому учетная запись, от имени которой он работает, является границей безопасности.

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-юнит systemd. Без включенного linger systemd останавливает сервисы пользователя сразу после завершения его последней сессии, поэтому ассистент завершит работу при закрытии SSH-соединения. Это же правило действует для любых сервисов и таймеров, которые вы создаете в systemd самостоятельно.

Учетной записи требуются права sudo только на время установки пакетов. Отозвите их после завершения установки.

sudo deluser iva sudo

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

Установка закрепленного релиза вместо передачи скрипта в bash

Установщик обладает полезным свойством. Перед клонированием он проверяет, содержит ли директория, в которой находится скрипт, package.json с файлом "eve". Если это так, он выполняет сборку из этого каталога и пропускает этап клонирования. Таким образом, вы можете самостоятельно выбрать версию.

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 августа 2026 года, поэтому main сегодня утром и main сегодня днем — это не одна и та же программа.

Переключение на тег оставляет git в состоянии detached HEAD. Это работает корректно, но учитывайте ограничение: iva update переводит рабочую копию на ветку обновлений, поэтому закрепление версии является лишь известной отправной точкой, а не постоянной фиксацией. iva version выводит версию пакета и git commit, чтобы вы всегда могли определить текущее состояние.

Чтобы намеренно перейти на более поздний релиз, выведите список тегов, установите IVA_TAG на выбранный вами вариант, а затем снова запустите установщик изнутри каталога с кодом.

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, директория хранилища и локальный порт (по умолчанию 8723).

Два из этих пунктов являются зависимостями, которые скрыты за формулировкой «одна команда». Iva не поставляется с предустановленными моделями, поэтому для работы ей требуется платный тариф или API-ключ. Она также не выполняет транскрибацию аудио самостоятельно, поэтому для голосовых заметок необходим отдельный сервис. Модель nova-3 от Deepgram с параметром 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. Список доступа работает по принципу «запрещено по умолчанию», поэтому пустое значение означает, что Iva никому не будет отвечать.

Модель считывается один раз при запуске процесса. Редактирование MODEL_PROVIDER или имени модели в .env не даст эффекта до тех пор, пока вы не выполните iva restart. В openrouter имя модели представляет собой идентификатор вендора, например anthropic/claude-sonnet-4.5, а не просто название. В codex API-ключ отсутствует: 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
  }
]

Это опубликованные прейскурантные цены по состоянию на август 2026 года, а не фактические затраты. Небольшой VPS за 5 долларов США плюс план OpenCode Go за 5 долларов — это самый дешевый вариант полноценной настройки, составляющий около 10 долларов в месяц. Ollama Cloud — это другой вариант с фиксированной ставкой за 20 доллара, при этом использование передовых моделей оплачивается дополнительно сверх стоимости плана. Голосовые функции стоят 0, пока действуют стартовые кредиты Deepgram.

OpenRouter здесь не указан, так как оплата производится по факту использования, поэтому ваш счет зависит от объема потребления. Это вариант, за которым нужно следить: ассистент, который использует контекстное окно в 131072 токена для каждого запроса, может быстро превысить стоимость фиксированного плана. Установите переменную контекстного окна в соответствии с реальным размером модели, так как завышенное значение приводит лишь к избыточному расходу токенов.

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

• iva.service запускает сам агент.
• iva-telegram-poll.service запускает мост для long polling, который взаимодействует с Telegram.
• iva-memory-doctor.timer срабатывает в 05:00 и выполняет ночное обслуживание хранилища.
• iva-update-check.timer срабатывает в 10:00 и проверяет наличие более новой версии (release).
• 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 выводит состояние обоих сервисов и обоих таймеров. systemctl --user list-timers показывает время следующего запуска для каждого таймера; так вы можете убедиться, что процедура очистки памяти действительно выполнится сегодня ночью. Оба сервиса должны находиться в состоянии active (running). Если один из них перезапускается в цикле, journalctl --user -u iva.service -n 100 укажет причину.

Разделение важно при отладке. Мост может работать и опрашивать серверы, пока агент неактивен; в этом случае Telegram примет ваше сообщение, но ответа на него не последует. iva logs poll позволяет отслеживать логи моста, iva logs — логи агента, поэтому два лога помогут понять, какая именно часть системы неисправна.

Где находится Obsidian vault и как выполнять его резервное копирование

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/ содержат сводные данные (rollups).
• vault/attachments/ хранит файлы по датам, а vault/.graph/ — граф связей.
• vault/schema.json определяет типы карточек и правила их устаревания.

Сводные данные формируются по расписанию внутри процесса. Ежедневный проход в 04:00 преобразует вчерашний транскрипт в карточки и краткое содержание, после чего перезаписывает CORE.md. Затем еженедельные, ежемесячные и ежегодные проходы последовательно сжимают эти данные. В 05:00 запускается «доктор памяти» — детерминированный процесс без участия языковой модели: он проверяет схему, перестраивает граф связей, обновляет индекс, а затем выполняет commit и push.

Этот push является вашей резервной копией, и это тот шаг, который часто упускают из виду. Если у vault нет git-ремоута, «доктор» пытается создать приватный репозиторий на GitHub через gh, для чего требуется аутентифицированный GitHub CLI.

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

Коммит с сегодняшней датой означает, что проход выполнен успешно и данные сохранены. Предупреждения gh not available в логе означают обратное: vault поддерживается в актуальном состоянии, но не покидает сервер, поэтому в случае выхода VPS из строя вы потеряете свою память.

Храните копию, которую вы контролируете самостоятельно.

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

Скопируйте этот файл с сервера с помощью scp, а затем удалите его с сервера. Чтобы просматривать память в Obsidian, укажите Obsidian путь к клону репозитория vault. Wikilinks и обратные ссылки работают в исходном виде, как и режим просмотра графа. Редактирование карточек и CORE.md вручную безопасно. Не трогайте MOC.md и .graph/, так как ночной проход каждый раз пересоздает их заново.

Относитесь к хранилищу как к журналу своей жизни

Этот каталог — датированная запись того, что вы сказали, с кем встретились и что решили, на арендованной вами машине. Из этого следуют два вывода.

Self-hosting переносит хранение данных, а не их обработку. Каждый запрос уходит провайдеру модели, а каждая голосовая заметка — в Deepgram. Хранилище принадлежит вам. Но запросы не являются приватными от компаний, которые их обслуживают. Запуск уровня памяти на собственном оборудовании, как в случае с сервером памяти Mem0 на вашем VPS, имеет ту же особенность: хранилище локально, но вызов модели всё равно покидает пределы сервера. Если тема слишком конфиденциальна для третьей стороны, не обсуждайте её в чате.

Область доступа этой учётной записи — всё хранилище целиком. Инструменты Iva работают на хосте напрямую через fs и child_process среды Node, без Docker и песочницы, поэтому в случае компрометации запроса злоумышленник получает все права пользователя, от имени которого запущен сервис. Именно поэтому учётная запись не содержит sudo после установки, и именно поэтому списку разрешённых адресов (allowlist) стоит уделить больше внимания, чем кажется: это шлюз, который определяет, чьи сообщения станут командами на вашем сервере. Если вы хотите иметь ассистента под рукой, не открывая порты наружу, используйте ту же схему, что и для доступа к self-hosted агенту Hermes с телефона, где клиент чата выполняет ту работу, которую в ином случае делала бы публичная точка входа.

Что может сломаться и какие сообщения вы увидите

Build killed, exit 137. Ядро завершило процесс сборки из-за нехватки оперативной памяти (OOM killer). Установщик добавляет swap только в том случае, если объем RAM менее 1.5 GB и 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-сессию от имени этого пользователя или выполните export для XDG_RUNTIME_DIR=/run/user/$(id -u iva) перед запуском команды.

Бот игнорирует сообщения. Файл TELEGRAM_ALLOWED_USER_IDS пуст, а список разрешенных пользователей (allowlist) работает по принципу запрета по умолчанию. Отправьте боту любое сообщение: в ответ он пришлет ваш числовой ID. Добавьте этот ID в .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

Очередь зависает и не отвечает. Состояние зависшего рабочего процесса сохраняется после перезагрузки и автоматически встает в очередь снова, поэтому простая перезагрузка не помогает. Команда iva reset изолирует это состояние и перезапускает оба сервиса. Команда /new в чате начинает новый диалог.

Chromium не запускается в Ubuntu 24.04. Ubuntu 24.04 блокирует пространства имен непривилегированных пользователей через AppArmor, поэтому песочница Chromium не может запуститься, и agent-browser завершается с ошибкой. Установщик обходит это ограничение, записывая "--no-sandbox" в ~/.agent-browser/config.json. Учтите наличие этого файла. Он снижает уровень изоляции браузера, что является еще одной причиной, по которой учетная запись не должна владеть ничем, кроме Iva.

FAQ

Нужен ли мне домен или открытый порт для самостоятельного хостинга Iva?

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

Сколько стоит ежемесячное использование Iva?

Согласно опубликованным в августе 2026 года ценам, небольшой VPS за 5 долларов плюс самый дешевый тарифный план за 5 долларов составляют около 10 долларов США в месяц. Ollama Cloud стоит 20 долларов, плюс дополнительная оплата за использование передовых моделей. Начальные кредиты Deepgram покрывают расходы на голосовые функции на первое время, а уровни поиска в сети имеют бесплатные лимиты. 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, что работает только при наличии настроенного удаленного репозитория, поэтому выполните gh auth login или добавьте свой удаленный репозиторий во время настройки. Также храните офлайн-копию с помощью tar czf ~/iva-vault-backup.tgz -C ~/iva vault и перемещайте этот файл за пределы сервера.

Являются ли мои данные приватными при самостоятельном хостинге Iva?

Хранилище принадлежит вам, но обработка — нет. База данных остается на вашем диске до тех пор, пока вы не выполните push, а файл .env имеет права доступа 0600 и принадлежит пользователю сервиса. Запросы к моделям и транскрипция голоса проходят через облачные API, поэтому эти сообщения передаются вашему провайдеру моделей и в Deepgram. Iva распространяется по лицензии MIT, поэтому вы можете изучить код, чтобы увидеть, что именно отправляется, и изменить его. Список разрешенных пользователей Telegram работает по принципу «запрещено по умолчанию»: пустой файл TELEGRAM_ALLOWED_USER_IDS блокирует доступ всем, включая вас.

Какие провайдеры моделей поддерживает Iva?

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