# 02 — Быстрый старт

**Русский** · [English](../02-quickstart.md)

Четыре шага — от пустого хоста до агента, которому можно написать. Каждый шаг это одна команда; под ней разобрано, что она делает.

## Требования

- **macOS.** Присутствием процессов управляет launchd, поэтому пока поддерживается только macOS.
- **[bun](https://bun.sh)** на `PATH`. Нужен для установки и обновлений: пакет ставится из исходников (готового скомпилированного JS в нём нет), а бинарь `iapeer` собирается через `bun build --compile`. Сам установленный `~/.local/bin/iapeer` — самостоятельный бинарь и при работе bun уже не требует.
- **`~/.local/bin` на `PATH`.** Сюда ставится бинарь `iapeer`. Если каталога нет в `PATH`, после установки команда `iapeer` не найдётся — добавьте его: `export PATH="$HOME/.local/bin:$PATH"` в профиль оболочки.
- **Хотя бы один агентский рантайм** — Claude Code или Codex CLI. Каждый AI-пир это живая сессия одного из них; если не установлен ни один, `iapeer create` и `iapeer init` скажут об этом ошибкой, а не упадут молча позже.

## Шаг 1. Установите ядро

```bash
npx @agfpd/iapeer
```

Вызов без аргументов — это установка. Она делает три вещи и ничего не запускает:

1. Собирает бинарь `iapeer` и кладёт в `~/.local/bin/iapeer` (предыдущая версия остаётся рядом как `iapeer.prev` — на случай отката).
2. Создаёт раскладку `~/.iapeer/` — каталоги реестра, состояния, логов, кеша и рантаймов.
3. Пишет плист демона в `~/Library/LaunchAgents/com.agfpd.iapeer.plist`, но **не загружает** его — это сделает `iapeer onboard` на шаге 2.

Установка идемпотентна: повторный запуск обновит бинарь и пересоберёт раскладку, ничего не сломав.

## Шаг 2. Подготовьте хост

```bash
iapeer onboard
```

`onboard` готовит хост к появлению агентов и обязателен: первым делом он поднимает демон-роутер, без которого сообщения не доставляются. Что он делает по порядку:

- **Демон.** Загружает плист в launchd (идемпотентно) и проверяет, что роутер отвечает. Дальше launchd поднимает демон сам — после падения и после перезагрузки машины. Это запуск постоянного фонового сервиса, поэтому macOS покажет уведомление «iapeer added a background item» — так и должно быть.
- **Marketplace.** Регистрирует marketplace расширений agfpd в Claude и Codex, чтобы агенты потом ставили capability-плагины.
- **notifier.** Разворачивает инфраструктурный рантайм планировщика: появляются служебные пиры `timer` (срабатывает по расписанию) и `watcher` (следит за событиями).
- **Telegram.** Заводит пир-человека — это вы, владелец, — присутствующего через Telegram. Шаг интерактивный: понадобится ваш Telegram user-id.
- **Память.** Ставит провайдера памяти по умолчанию, если слот свободен.

Старт демона идёт всегда; остальные шаги включены по умолчанию, но любой выключается флагом — `--no-notifier`, `--no-telegram`, `--no-memory`. Чтобы увидеть, что команда сделает, ничего не меняя:

```bash
iapeer onboard --dry-run
```

Проверьте, что демон жив и хост готов:

```bash
iapeer status
```

Вы увидите снимок хоста: версию ядра, здоровье демона, состояние слота памяти.

## Шаг 3. Создайте первого агента

```bash
iapeer create assistant --runtime claude
```

Так появляется пир `assistant` на рантайме Claude. Что заводит команда:

- рабочую папку — по умолчанию `~/.iapeer/peers/assistant`;
- профиль пира `peer-profile.json` — имя, рантаймы, описание, природа;
- запись в реестре, чтобы демон знал о пире;
- подключение к демону по MCP — через него агент получит инструмент `send_to_peer`;
- файл доктрины `IAPEER.md` — роль и характер агента (аналог `CLAUDE.md` для пира), который вы потом наполните;
- общую память, если слот памяти занят.

Агент создан, но сессия ещё не запущена — она поднимется на первом сообщении.

`IAPEER.md` для пира — то же, что `CLAUDE.md` для проекта: его инструкции и характер. Тот, что в `~/.iapeer/`, действует на всех пиров хоста; тот, что в папке пира, — только на этого пира. А любой другой `.md`, который вы положите в корень папки `.iapeer/` пира (или хоста, `~/.iapeer/`), тоже едет в системный промпт — так что выдать агенту дополнительный контекст можно просто добавив файл. Подробности — в [05 — Идентичность и системный промпт](05-системный-промпт.md).

Создать агента можно и из его рабочей папки, без указания пути, командой `iapeer init`. Разницу между `create` и `init` разбирает [08 — Управление пирами](08-управление-пирами.md).

**Хотите, чтобы агент отвечал в Telegram?** Подключите к нему бота — и пишите агенту прямо из мессенджера; см. [быстрый старт telegram-runtime](https://github.com/agfpd/telegram-runtime/blob/main/docs/ru/02-быстрый-старт.md).

## Шаг 4. Отправьте первое сообщение

```bash
iapeer send assistant --message "привет, ты на связи?"
```

Живой сессии ещё нет, поэтому демон поднимает её и доставляет сообщение. В ответ вы увидите `delivered to assistant (claude)` — или `queued …`, если агент оказался занят.

Посмотреть, какие есть пиры и кто сейчас жив:

```bash
iapeer list
```

Каждая строка — пир, его рантаймы и состояние: `●` живой, `○` спит, `✕` остановлен.

Подключиться к сессии агента вживую, как к обычному терминалу:

```bash
iapeer attach assistant
```

Сессия откроется под супервизором; отсоединиться — `Ctrl-]` или просто закрыть терминал. В любом случае сессия продолжает работать в фоне, а переподключиться можно командой `iapeer attach`, когда понадобится.

## Что дальше

Базовый круг замкнут: хост готов, агент создан, сообщение доставлено. Дальше по задаче:

- Что происходит при пробуждении и усыплении — [04 — Жизненный цикл и демон](04-жизненный-цикл-и-демон.md).
- Наполнить роль агента и разобраться с системным промптом — [05 — Идентичность и системный промпт](05-системный-промпт.md).
- Подключить агента к Telegram, добавить второй рантайм, переключить всех пиров на другой рантайм — [09 — Рантаймы](09-рантаймы.md).
- Поставить агенту расширение или память — [11 — Расширения и память](11-расширения-и-память.md).