Настройка агента
Агент читает флаги, переменные окружения и необязательный .env в рабочем каталоге (загружается автоматически). Флаги важнее окружения.
Флаги
| Флаг | Переопределяет | Значение |
|---|---|---|
--agency-url | CHERRYPI_AGENCY_URL | URL agency для туннеля. Обязателен. |
--token | CHERRYPI_AGENT_TOKEN | Personal access token (pat_…). |
--display | DISPLAY | X-дисплей для моста рабочего стола. |
--xauthority | XAUTHORITY | X authority для --display. |
Переменные окружения
| Переменная | По умолчанию | Значение |
|---|---|---|
CHERRYPI_AGENCY_URL | — | URL agency (обязателен). |
CHERRYPI_AGENT_TOKEN | — | Personal access token (pat_…). --token важнее; токен важнее кэшированного файла. |
CHERRYPI_AGENT_TOKEN_FILE | $CHERRYPI_DIR/agent.token | Файл кэша токена; встроенные инструменты Pi читают его на каждом вызове. |
CHERRYPI_DIR | ~/.cherrypi | Каталог данных: SQLite, токен, рабочие пространства задач. |
CHERRYPI_DATABASE_DSN | $CHERRYPI_DIR/cherrypi.sqlite3 | Локальная база агента. |
CHERRYPI_AGENT_TUNNEL_TRANSPORT | auto | auto, http2 или websocket. Только диагностика. |
CHERRYPI_LOG_FORMAT | text | text или json, по строке на запись. |
CHERRYPI_LOG_LEVEL | info | debug, info, warn, error. |
PI_BIN | pi | Исполняемый файл Pi. |
PI_ARGS | — | Дополнительные args через пробел после --mode rpc --session-id. |
PI_SESSION_DIR | по умолчанию Pi | Переопределить хранилище сессий Pi. |
PI_CODING_AGENT_DIR | ~/.pi/agent | Каталог Pi: память, settings.json, креденшелы провайдеров. |
DISPLAY | — | X-дисплей для рабочего стола. |
XAUTHORITY | — | X authority. |
SHELL_BIN | $SHELL, затем /bin/bash | Shell для root-терминалов. |
Токены
Personal access token — единственный креденшел агента. Путей два, в порядке приоритета:
--token/CHERRYPI_AGENT_TOKEN— явный токен. Он фиксирован: ротация файла токена его не переопределяет. Для нового токена перезапустите агента.- Кэшированный токен —
CHERRYPI_AGENT_TOKEN_FILE, по умолчанию$CHERRYPI_DIR/agent.token. Агент проверяет его при старте и удаляет, если agency его отвергла. Встроенные инструменты Pi перечитывают файл на каждом вызове, поэтому ротация применяется без перезапуска Pi.
Username/password fallback нет. Если оба источника пусты, агент завершается с инструкцией.
Считайте каталог данных секретом: кэшированный токен даёт доступ агента.
Каталог данных
$CHERRYPI_DIR/
cherrypi.sqlite3 # локальный кэш задач/использования
agent.token # кэш personal access token (0600)
sessions/<task id>/ # рабочие пространства задач и вложенияРабочие пространства могут разрастаться. Держите CHERRYPI_DIR на диске с местом под репозитории, зависимости и build-выход. Agency хранит историю сессии Pi, поэтому workspace можно пересоздать повторным запуском задачи; но незакоммиченные файлы, не прикреплённые и не опубликованные как артефакты, пропадут при удалении каталога.
Конфигурация Pi
Агент не настраивает модели. Это делает Pi через PI_CODING_AGENT_DIR (по умолчанию ~/.pi/agent). В контейнере монтируйте этот каталог с хоста, чтобы креденшелы и память Pi переживали перезапуск.
-v /srv/cherrypi/pi:/root/.pi/agentОбраз уже содержит расширения Pi, нужные CherryPi. При самостоятельном запуске бинарника установите совместимую версию Pi и расширения из release notes.
Логи
Логи идут в stdout, а зеркало не-локальных записей отправляется в agency для вкладки Logs на странице агента.
CHERRYPI_LOG_FORMAT=json
CHERRYPI_LOG_LEVEL=debugStderr самого Pi остаётся локальным и попадает в agency как вывод консоли задачи.
Лимиты параллельности
Сколько задач может выполнять агент, решает agency, а не агент. В Agents → Limits задаются:
- общий лимит параллельных задач;
- лимит на проект;
- лимиты по тегам и тегам внутри проекта.
Значения по умолчанию намеренно консервативны (1 всего, 1 на проект). Повышайте их, только если у машины есть CPU, RAM и запас по лимитам провайдера.
Транспорт туннеля
В обычном развёртывании CHERRYPI_AGENT_TUNNEL_TRANSPORT не задавайте. auto пробует HTTP/2 и откатывается на WebSocket поверх HTTP/1.1. Явные значения (http2, websocket) — диагностика.
Если reverse proxy ломает туннель, не форсируйте h2c перед agency; настройте прокси на WebSocket и отключите read timeout.
Рабочий стол
Задайте DISPLAY (и обычно XAUTHORITY), чтобы показать существующую X-сессию. Без них рабочий стол отключён. См. Доступ к рабочему столу.