Soul

Агент на управляемом хосте — один статический исполняемый файл на Go без рантайм-зависимостей. Применяет Destiny через core-модули; работает в двух режимах одним и тем же набором модулей.

Два режима — один исполняемый файл

• pull (демон). Агент запущен как systemd-сервис, сам инициирует долгоживущий gRPC-стрим к Keeper-у поверх mTLS и применяет задачи, которые Keeper доставляет по стриму. На хосте не нужно открывать входящие порты.
• push (oneshot по SSH). Без постоянного демона: Keeper доставляет исполняемый файл и модули на хост по SSH и запускает разовое применение. Модули кешируются на хосте по SHA-256.

Один и тот же исполняемый файл и один и тот же набор модулей работают в обоих режимах — применение задачи не зависит от того, демон это или oneshot.

Идентичность

• SID (Soul ID) агента равен FQDN хоста. SID должен резолвиться и быть валидным lower-case FQDN.
• Онбординг идёт через CSR: при soul init агент генерирует приватный ключ и CSR — приватный ключ никогда не покидает хост. В обмен на одноразовый bootstrap-токен Keeper подписывает и возвращает mTLS-идентичность агента, которая раскладывается в стейт-каталог.
• На bidi-стриме (EventStream) авторитет идентичности — клиентский mTLS-сертификат; SID в сообщениях используется как echo для логов.

Soulprint — факты о хосте

Агент собирает Soulprint — типизированный набор фактов о системе (семейство ОС, дистрибутив и версия, архитектура, пакетный менеджер и init-система, ядро, CPU, память, сеть). Эти факты:

• доступны в сценариях для таргетинга и шаблонизации (например, выбрать пакетный менеджер по семейству ОС);
• читаются core-модулями напрямую (core.pkg.* / core.service.* опираются на собранные pkg_mgr / init_system).

Модули

Применение конфигурации делают core-модули — статически встроенные в исполняемый файл шаги вида core.<module>.<state> (например core.pkg.installed, core.file.present). Каталог встроенных модулей — Модули. Custom-модули подключаются как отдельные плагины (sub-process по gRPC-over-stdio) и кешируются на хосте по SHA-256.

Подкоманды

Команда	Что делает
soul init	онбординг: генерирует ключ + CSR, обменивает bootstrap-токен на mTLS-идентичность
soul run	запуск демона: держит EventStream к Keeper-у и применяет задачи (pull-режим)
soul version	версия сборки

Bootstrap-токен для soul init передаётся через переменную окружения SOUL_BOOTSTRAP_TOKEN (предпочтительно — не светит в ps/history) или из stdin.

Требования к хосту

Агент — один статический исполняемый файл: на хосте не нужны интерпретаторы, рантаймы или сторонние зависимости (в отличие от агент-less-инструментов, требующих Python/SSH-обвязку). Нужен лишь доступ к Keeper-у по сети (исходящий, на bootstrap- и EventStream-порты) и привилегии для применения Destiny.

Установка

Агент ставится из пакета soul-stack-soul, бинарного релиза или сборки. Онбординг (регистрация хоста, выпуск токена, soul init, запуск демона) — Установка из пакетов → Онбординг агента.