> 🇬🇧 [English version](../install.md) — каноническая версия, она может быть новее. # Установка ## Через ИИ-агента Вставьте эту фразу в Claude Code, Codex или Claude Desktop. Агент проверит сервер или Mac, запустит установщик и поможет получить ответ от бота. [Инструкция для агента](https://iva-agent.com/install.txt). ```text Установи мне Иву, инструкция: https://iva-agent.com/install.txt ``` На macOS тот же установщик использует Homebrew и launchd. Метки юнитов имеют вид `app.iva.*`, плисты лежат в `~/Library/LaunchAgents`, журнал в `~/Library/Logs/Iva/`. Перед установкой войдите в систему на экране Mac. Для работы Ивы Mac должен быть включён и не спать. Ночь при выключенном Mac пропускается; после сна launchd запускает пропущенное календарное задание при пробуждении. Проверка установки: `iva status` и `iva logs -f`. Всё, что лежит между `curl` и работающим ботом. Одна команда на чистом сервере: установщик спросит язык, проведёт по пяти ключам и в конце напишет вам из вашего же бота. ## Что понадобится - 🖥️ **Сервер или свой компьютер** — проверенный путь это Ubuntu/Debian (apt); Fedora (dnf) и macOS (brew) тоже работают. Подойдёт любая всегда включённая машина. - 🧠 **512 МБ памяти хватает** — на машинах меньше 1.5 ГБ установщик добавит swap-файл на 2 ГБ, чтобы сборку не убил OOM (нужно ~2.6 ГБ свободного места на диске). - 💾 **Не меньше ~1.5 ГБ свободного места для самой Ивы** — два каталога версий по ~400 МБ и кэш npm; нужно ещё 2 ГБ, когда установщик добавляет swap-файл. - 🔑 **sudo** — спрашивается сразу и только если не хватает системных пакетов или нужен swap-файл; шаг с Chromium может спросить ещё раз. > Никогда не работали с сервером? Хостинг присылает адрес (IP), логин и пароль. На Mac или Linux откройте «Терминал», на Windows — PowerShell, введите `ssh root@YOUR_ADDRESS`, потом пароль. Вы внутри. Первым делом заведите себе обычного пользователя и перейдите в него - `adduser iva && usermod -aG sudo iva && su - iva` - и ставьте уже оттуда. Shell-инструмент Ивы работает с правами того, кто её поставил, так что root ему отдавать не надо. > Если установка заканчивается ошибкой `Failed to connect to bus: No medium found`, выйдите из `su - iva`. Включите linger и подключитесь напрямую: > > ```bash > exit # обратно в root-сессию на сервере > loginctl enable-linger iva > exit # обратно на свой компьютер > ssh iva@YOUR_ADDRESS > ``` > > После этого снова запустите установку. ## Установка ```bash curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh | bash ``` Первый вопрос — язык, English или русский, ещё до того, как скрипт что-то тронет в системе. Ввод читается из `/dev/tty`, поэтому мастер остаётся интерактивным даже через пайп из `curl`. Если терминала нет вовсе (Docker, CI), настройка пропускается, а скрипт печатает, как запустить её позже. ## Мастер настройки Пять шагов. К каждому ключу — прямая ссылка на место, где он лежит, и живая проверка: неверный ключ отклоняется на месте, а не всплывает в рантайме. Enter оставляет текущее значение, так что повторный запуск мастера (`iva config`) меняет только то, что вы хотите. 1. **Провайдер и модель.** Ollama Cloud, OpenCode Go, подписка OpenAI (ChatGPT), OpenRouter или свой OpenAI-совместимый эндпоинт ([сравнение](../providers.md)); ключ (или вход по подписке) проверяется, потом вы выбираете модель. 2. **Голос, поиск, гибридная память.** Ключ Deepgram (дают бесплатный стартовый кредит) — Enter пропускает, голосовые не расшифровываются, пока не добавите ключ в `/menu` → 🎤 Голос; язык распознавания `multi` сам определяет ru/uz/en. Тут же выбирается провайдер веб-поиска — Tavily, Exa, Parallel или Brave; Enter пропускает шаг, и поиск остаётся выключенным, — и предлагается опциональная гибридная память с ключом для эмбеддингов. 3. **Telegram-бот.** Вставьте токен от @BotFather; мастер проверит его через `getMe` и сам определит username бота. 4. **Доступ.** Напишите своему новому боту любое сообщение — «привет» подойдёт. Мастер читает `getUpdates`, показывает, кто написал, и вы выбираете себя. Iva отвечает только этим ID; пустой список — не отвечает никому. 5. **Таймзона, vault, порт.** Таймзона IANA, чтобы ночные задачи шли по вашим часам, директория vault и порт — по умолчанию 8723, с проверкой на конфликты. ## Что делает install.sh - 📦 **Системные пакеты** — `git gh python3 ffmpeg pandoc poppler-utils` (`poppler` в brew): `gh` бэкапит vault в приватный репозиторий на GitHub, pandoc и poppler достают текст из входящих docx/pdf, ffmpeg конвертирует медиа, которые расшифровщик не берёт напрямую. - 🐍 **uv** — запускает Python-скрипты обслуживания vault. - 🟢 **Node 24 через nvm** — root не нужен; 24 — жёсткий минимум, потому что поиск по памяти использует встроенный `node:sqlite`. - 🌐 **agent-browser + Chromium** — headless-браузер для веб-задач; самый долгий шаг, 1–3 минуты видимого вывода загрузки. - 🗂️ **Инициализация vault** — память создаётся из `vault-template/` как отдельный git-репозиторий, так что личные данные никогда не попадают в репозиторий с кодом. - ⚙️ **Фоновый runtime** — два systemd user service, два systemd watchdog-таймера и семь внутрипроцессных eve schedules, с включённым linger, чтобы всё пережило logout. Подробности: [deploy.md](../deploy.md). - 🧰 **Команда `iva`** — ставится в `~/.local/bin`: `iva status`, `iva doctor`, `iva update`. Полный справочник: [cli.md](../cli.md). - ✅ **Подтверждение в Telegram** — последнее, что делает установщик, — пишет вам из вашего же бота: «Iva установлена и на связи. Напишите мне — отвечу». Это и есть сигнал успеха. Запускать ту же команду повторно безопасно: над установкой, которая уже есть, установщик не обновляет ничего сам — он отдаёт установку единственному обновлятору, так же как `iva update` и `repair.sh`. Чекаут сперва возвращается на релиз (правки в коде Ивы удаляются, `.env`, `data/` и vault не трогаются), версионная раскладка идёт сразу к своему обновлятору, а чекаут с вашим файлом `.iva-dev` получает отказ. **Google Workspace CLI (`gws`)** устанавливается и обновляется в `~/.local` без sudo. Сервисы берут `~/.local/bin` раньше прежних глобальных копий. Старые бинарные файлы остаются на месте; конфигурация и авторизация Google остаются у того же пользователя. Каждый шаг сам проверяет, сделан ли он уже, и пропускает себя — поэтому запуск после сбоя занимает секунды, а не минуты: | Шаг | Пропускается, когда | | ---------------- | -------------------------------------------------------------------------------------------- | | Системные пакеты | команда уже есть (`git`, `gh`, `python3`, `ffmpeg`, `pandoc`, `pdftotext`) | | `npm ci` | `node_modules` совпадает с `package-lock.json` по версии, URL и integrity, включая архив eve | | agent-browser | бинарь установлен и реально открывает страницу | | `gws` | бинарь установлен (актуальность держит `iva update`) | | Сборка | в `.output` лежит отметка установщика для текущего коммита, локальных правок и `.env` | Мастер настройки, проверка vault, команда `iva` и systemd-юниты дешёвые, поэтому выполняются каждый раз. Упавший запуск откатывается: копия `.env` возвращается на место, прежняя сборка тоже, а обе копии удаляются — в том числе при Ctrl-C и при обрыве SSH-сессии. Код этот скрипт не двигает вовсе. Если сам откат не смог доехать — checkout только для чтения, кончилось место — ничего сохранённого не выбрасывается. Всё, что осталось единственной копией, остаётся на месте, и установщик перед выходом печатает каждое по имени: копию `.env` в `data/update-backups/` и прежнюю сборку в `.output.iva-install-backup-*`. Прочитайте эти строки прежде, чем запускать что-то ещё. Установка, распакованная из архива, а не склонированная, не имеет коммита для сравнения — она пересобирается каждый раз; так же ведёт себя установка с файлом, который сборка не может прочитать. В одной установке одновременно работает только один установщик: второй получает отказ с pid того, кто уже работает. Лок, оставшийся от несуществующего процесса, забирается — отключение питания не сделает установку неработоспособной. ### Флаги и переопределения Флаги проходят через пайп с помощью `bash -s --`: ```bash curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh | bash -s -- --skip-setup ``` | Опция | Действие | | ------------------- | ------------------------------------------------------------------------ | | `--skip-setup` | поставить всё, но не запускать мастер | | `--non-interactive` | вообще без вопросов — только значения по умолчанию, мастер пропущен | | `-h`, `--help` | показать встроенную справку и выйти | | `REPO_URL=…` | ставить из форка (по умолчанию `https://github.com/smixs/iva-agent.git`) | | `BRANCH=…` | ставить и дальше обновлять эту ветку (по умолчанию `main`) | | `INSTALL_DIR=…` | куда положить код (по умолчанию `~/iva`) | Последние три — переменные окружения, скрипт читает их на старте. ## Если мастер не запустился Пропустили настройку или при установке не было терминала: ```bash cd ~/iva && npm run setup ``` Потом повторите обычную команду установки: ```bash curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh | bash ``` Пока автозапуск ожидает настройки, установщик продолжает первую установку. Он переиспользует готовые этапы, открывает мастер с сохранёнными значениями по умолчанию, включает автозапуск и отправляет подтверждение в Telegram. На Linux он также включает linger, чтобы Ива работала после выхода из SSH-сессии. После настройки автозапуска следующие запуски передаются обновлятору. ## Что дальше - Каждая переменная `.env`, значения по умолчанию и предупреждения — [configuration.md](configuration.md) - Серверный CLI `iva` и команды в Telegram — [cli.md](../cli.md) - Транспорт, таймеры, режим webhook и эксплуатация — [deploy.md](../deploy.md)