Исполнение: профили и пулы¶
Команды и файловые операции агента можно выполнять двумя способами: в процессе самого сервера или в отдельных изолированных исполнителях. Способ задаётся при запуске инстанса, а профили и пулы определяют, какой именно исполнитель получит работу конкретной сессии.
Зачем разделять исполнение¶
| Топология | Где выполняется | Когда подходит |
|---|---|---|
inline |
в процессе сервера, вместе с ним | одна машина, локальная работа, простая установка |
remote |
в отдельных исполнителях; сервер остаётся управляющим слоем | командная работа, изоляция инструментов, разные окружения под разные задачи |
В режиме remote на исполнителе выполняются все инструменты агента:
чтение и запись файлов, правка, поиск, git, shell, вложения, браузер и
терминал. Сервер не читает файлы проекта сам — он только передаёт вызовы.
Топология — параметр запуска. Переключить её из интерфейса нельзя: нужен перезапуск с другой конфигурацией (см. Конфигурация).
Профили исполнения¶
Профиль — именованное описание исполнителя. Один инстанс может держать несколько профилей: например, «обычный» с полным набором инструментов, «лёгкий» для чтения и поиска и «devops» с дополнительным окружением.
Профиль задаёт:
- адрес исполнителя (для статических пулов) и параметры вызова — таймаут и предел одновременных команд;
- режим отказа — что делать, если исполнитель недоступен;
- образ — какое окружение поднимается под задачу;
- сетевой класс —
none,restrictedилиfull; - ресурсы — запросы и пределы CPU, памяти, а также расширенные ресурсы, например GPU;
- MCP-серверы, которые исполнитель поднимает у себя (для браузерного профиля — сервер браузера);
- размещение — отбор узлов, tolerations, affinity, метки и аннотации (для кластерных развёртываний);
- описание — человекочитаемая подпись для карточек в интерфейсе.
execution:
mode: "remote"
remote:
provider: "static"
defaultProfile: "default"
profiles:
default:
url: ["http://synth-executor:5100"]
timeoutMs: 30000
concurrency: 4
failMode: "fail"
description: "Основной исполнитель"
light:
url: ["http://synth-executor-light:5100"]
timeoutMs: 60000
network: "restricted"
resources:
requests: { cpu: "500m", memory: "1Gi" }
limits: { cpu: "2", memory: "4Gi" }
Значения профиля задаются поверх общих параметров секции: незаполненное поле наследует значение из общего блока.
Каталог профилей¶
Каталог профилей — это список доступных исполнителей, которым пользуются проекты, агенты и сессии. Он собирается из трёх источников:
- профили, описанные при развёртывании (конфигурация инстанса или Helm-значения чарта);
- профили, добавленные или переопределённые администратором в разделе Настройки → Исполнение;
- профили, отключённые администратором (они не удаляются, а перестают предлагаться).
Переопределение из интерфейса заменяет профиль целиком; профили из поставки при этом не исчезают — их можно только отключить. Сброс настроек раздела возвращает каталог к состоянию «как в конфигурации».
Изменения применяются после перезапуска
Каталог профилей, режим пулов и профиль по умолчанию — параметры запуска. Раздел «Исполнение» показывает, что сохранено и что реально работает сейчас, и предлагает перезапустить инстанс. До перезапуска проекты и агенты видят работающий каталог, а не сохранённый.
Какой профиль получит сессия¶
Профиль наследуется по цепочке; побеждает первый заполненный и разрешённый источник:
- Сессия — профиль можно сменить в настройках сессии.
- Агент — форма агента в разделе «Агенты»: «Профиль исполнения» и «Разрешённые профили». Пустой профиль означает «наследовать».
- Проект — вкладка «Проект»: профиль и список разрешённых профилей.
- Профиль по умолчанию — точка отката инстанса.
Ограничения работают как потолок: если у проекта или агента задан список разрешённых профилей, выбрать профиль вне списка нельзя. Явно пустой список означает «профилей не разрешено»; незаполненное поле ограничения не задаёт. Запрещённый или неизвестный профиль не выбирается — инстанс откатывается к разрешённому варианту и пишет предупреждение в журнал.
Профиль передаётся и дочерним сессиям саб-агентов: если профиль запрошен явно, он проверяется до создания дочерней сессии, чтобы работа не ушла в чужое окружение.
Пулы¶
Пул — набор исполнителей, который обслуживает группу работы. Область пула определяет, кто с кем делит окружение:
| Область | Что означает |
|---|---|
instance |
один общий пул на весь инстанс; профили не разделяются |
project |
отдельный пул на проект — проекты не видят окружение друг друга |
session |
отдельный пул на сессию — самое строгое разделение |
Классы пулов:
| Класс | Для чего | Особенность |
|---|---|---|
exec |
обычные команды и файловые операции | профиль выбирается по цепочке наследования |
browser |
встроенный браузер агента | всегда на проект: cookies и сессии не перетекают между проектами |
sandbox |
разовый запуск команд в отдельном окружении | до пяти команд подряд; обычные права и проверки путей к нему не применяются |
Браузерный пул остаётся проектным даже при области session: изоляция нужна
между проектами, а не между сессиями одного проекта. Профиль браузерного пула
выбирается отдельной цепочкой (сессия → агент → проект → браузерный профиль
инстанса) и не наследует профиль команд.
Песочница — отдельный образ и отдельный пул: команда уходит туда целиком, без переноса прав и ограничений рабочего каталога. Она подходит для проверки чужих инструментов, но не заменяет обычное исполнение.
Прогрев образов
Первый пул с новым образом ждёт, пока образ скачается на узлы. Админ может прогреть образы заранее — из раздела «Исполнение» или командой API: сервис пулов поднимает временную нагрузку на узлы, ждёт готовности и убирает её. Образ остаётся в кэше, лишних объектов в кластере не остаётся. Прогрев доступен только в кластерном развёртывании.
Изоляция¶
Исполнитель — это не «тот же сервер в другом контейнере», а отдельная граница:
- процессы работают не от root, с запретом повышения привилегий и сброшенными возможностями;
- корневая файловая система доступна только на чтение; для временных файлов и домашнего каталога выдаются отдельные записываемые тома;
- сеть ограничивается классом пула через политики кластера:
none— без выхода вообще,restricted— только DNS и явно разрешённые адреса,full— без ограничений; - токен доверия между сервером и исполнителем хранится в Secret или в файле; в конфигурации указывается путь, а не значение;
- при недоступном исполнителе работа не выполняется — инструмент возвращает понятную ошибку, а не тихо уходит в процесс сервера.
inline-fallback — обход изоляции
Режим отказа inline-fallback разрешает серверу выполнить команду самому,
если исполнитель недоступен. Это удобно при миграции и локальной отладке,
но в управляемом контуре это означает потерю изоляции: включайте только
осознанно и никогда не оставляйте по умолчанию.
Отдельно от изоляции работает аудит исполнений и, при необходимости, внешний чекер команд: журнал фиксирует запущенные команды, а чекер может запретить вызов до запуска. Это меры контроля, а не граница безопасности — shell по-прежнему исполняет произвольный код.
Provisioner: сервис, который создаёт пулы¶
В кластерном развёртывании пулы создаёт отдельный процесс — provisioner. Он не хранит сессий и не знает моделей: по запросу сервера он выдаёт адрес и токен пула, следит за жизненным циклом и убирает простаивающие пулы.
- Источники пулов: статический список адресов (внешние исполнители) или Kubernetes — тогда под пула создаётся по требованию, с образом из профиля.
- Срок жизни: простаивающий пул снимается по таймауту (проектный и общий — 15 минут, сессионный — 5 минут), предельное время жизни пула — 12 часов; после рестарта provisioner находит свои пулы по меткам и продолжает ими пользоваться.
- Лимиты: число одновременно живых пулов ограничено (по умолчанию 50); сверх лимита запрос получает отказ с причиной «нет ёмкости».
- Наблюдаемость: у сервиса есть проба
/healthи метрики/metrics; ошибки выдачи пула видны в журнале сервера и в статусе пулов. - Доступ: все операции — по токену; сам токен и адреса пулов не показываются в интерфейсе и не попадают в тексты ошибок.
Порядок обновления
Provisioner обновляется раньше сервера: сервер новой версии передаёт ему описание профиля, которого старый provisioner не понимает. Обратный порядок даст отказ «некорректный запрос» на новых профилях.
Что видно в интерфейсе¶
Раздел Настройки → Исполнение показывает:
- сводку: провайдер пулов, режим пулов, профиль по умолчанию;
- карточки профилей: образ, сетевой класс, ресурсы, имена MCP-серверов и описание; неизвестные поля показываются прочерком;
- список пулов с состоянием:
configured(настроен),ready(готов),draining(выводится); адреса и токены не раскрываются; - действия: слить или удалить пул, прогреть образы, перезапустить инстанс;
- предупреждение, если сохранённые настройки ещё не применены.
В локальном и гибридном режиме без профилей раздел честно сообщает, что профили исполнителей не применимы: исполнение идёт в процессе. Те же поля в настройках проекта, сессии и агента при этом скрыты, а не показаны пустыми.
Выбор профиля доступен трём уровням: настройки проекта (вкладка «Проект»), форма агента и настройки сессии. Полный список профилей читает любой участник — профиль выбирается в проекте, а управление каталогом и пулами доступно администратору (обзор пулов — ещё и ведущему).
Ограничения¶
- Сборка образов удалённо только описана. Собирать образы из сессии можно лишь через внешний builder; собственной автоматизации сборки и публикации образов у платформы нет.
- Сквозной проверки на кластере нет. Создание пулов, права и сетевые политики проверяются по частям; полный сценарий на живом кластере автоматически не прогоняется.
- Отдельного класса пулов для MCP нет. MCP-серверы живут внутри профиля исполнителя и браузерного пула; выделение их в самостоятельный класс — предложение, а не реализованная возможность.
- Живой пул не пересоздаётся сам. Смена образа, сети или ресурсов профиля видна только новым пулам: чтобы применить её к работающему пулу, его нужно снять.
- Один namespace. Поды и секреты пулов создаются в namespace релиза; сетевые политики действуют только там.
Что дальше¶
- Конфигурация — секция
executionи параметры запуска. - Kubernetes / Helm — provisioner, сетевые классы и общий том workspace.
- Безопасность — изоляция, аудит и фильтрация недоверенного контента.
- Фоновая работа — что происходит с длинными командами.