Свой раннер (zubrcode remote)

«Свой раннер» — это ZubrCode на вашей машине под управлением из чата. Код никуда не уезжает: агент работает в папке проекта на сервере, ноутбуке или ВМ, а вы ставите задачи, смотрите ленту и подтверждаете команды в zubriq.by/sandbox — хоть с телефона.

Отличие от обычной сессии: там платформа сама поднимает контейнер и клонирует репозиторий; здесь окружение ваше — свои зависимости, базы, доступы, любой git-хостинг.

Что нужно

Установленный ZubrCode — одна команда, см. установку. Нужна версия 1.18.32-4 или новее: zubrcode --version.
Аккаунт ZubrIQ. Ключ руками не нужен: если вы уже входили (zubrcode auth login или в zq), zubrcode remote возьмёт этот ключ; если нет — напечатает ссылку на вход (zubriq.by). Откройте её на любом устройстве, хоть с ноутбука, пока ZubrCode крутится на сервере по SSH, — ключ сам придёт и сохранится. Можно задать и руками: ZUBRIQ_API_KEY (zubriq.by/chat → Настройки → API-ключи).
Выход в интернет с машины (исходящий HTTPS/WSS до console.zubriq.by). Входящие порты, белый IP, VPN — не нужны, работает за NAT.

Запуск

cd /path/to/project
zubrcode remote

Что произойдёт:

Регистрирую сессию в https://console.zubriq.by…
Раннер готов: /path/to/project
Сессия в чате: https://zubriq.by/sandbox/01m1…
Ctrl+C — остановить.
[relay] туннель поднят

Откройте ссылку — сессия уже в списке «Код» с пометкой свой раннер, хостом и папкой. Напишите агенту, что сделать. Пока zubrcode remote запущен, страницу можно закрывать и открывать снова, в том числе с другого устройства.

Перенести разговор из терминала

Начали в zubrcode на машине и хотите продолжить с телефона — возьмите id сессии (zubrcode session list) и запустите с ним:

zubrcode remote --resume ses_…

Чат подключится к этой сессии вместе с историей.

Параметры

Ключ	По умолчанию	Зачем
`--resume`	—	id сессии терминала, чтобы продолжить её в чате
`--port`	`4180`	порт локального сервера (слушает только 127.0.0.1)
`--console`	`https://console.zubriq.by`	адрес консоли (регистрация сессии)
`--relay`	из ответа консоли	адрес relay, если нужен другой

Что видно в чате

Лента: размышления, чтение файлов, правки диффом, команды и их вывод.
Разрешения: правки файлов агент делает без вопросов, а перед командами оболочки спрашивает — «Разрешить», «Разрешать всегда», «Запретить».
Вопросы: если агенту нужно ваше решение, он спросит карточкой с вариантами.
На ходу: можно дописать агенту во время хода; «Стоп» прерывает ход.
Ссылок «Ветка» и «Открыть MR» у своего раннера нет — git у вас свой; попросите агента закоммитить и запушить, куда настроен origin.

Остановка

Ctrl+C в терминале — сессия снимается с регистрации и пропадает из списка живых, локальный сервер гасится.
Кнопка «Остановить» в чате — закрывает сессию на платформе; процесс на машине увидит обрыв туннеля и будет переподключаться, пока вы его не остановите.
Без открытой вкладки сессия гасится через 2 часа простоя.

Безопасность

Локальный сервер слушает только 127.0.0.1 и требует пароль сессии; снаружи к нему ходит только relay платформы, и только с паролем вашей сессии. Чужой запрос по адресу сессии получит 401.
Пароль и ключ ZubrIQ уходят серверу через окружение процесса, в аргументах команд не светятся.
Агент выполняет то, что вы подтверждаете в чате, с правами вашего пользователя на этой машине. Не запускайте zubrcode remote от root и не в каталогах с секретами, которые не должен видеть агент.

Если что-то не так

Симптом	Причина и что делать
`Вход не удался`	вход не подтверждён за 10 минут или нажата «Отмена» — запустите снова и откройте напечатанную ссылку (на любом устройстве) либо задайте `ZUBRIQ_API_KEY`
`Регистрация не удалась: консоль ответила 401`	ключ отозван или чужой — `zubrcode auth login -p zubriq` или новый ключ в кабинете
`… ответила 409`	у вас уже 3 живых сессии — остановите лишнюю в чате
`… ответила 503`	раннеры выключены в этой среде (стейдж) — используйте zubriq.by
`[relay] relay отверг подключение` в цикле	сессию остановили в чате или истёк её срок — перезапустите `zubrcode remote`
`локальный zubrcode serve не поднялся за минуту`	порт `4180` занят — задайте другой: `--port 4181`
в чате `403 key not allowed to access model`	ключ выпущен на уровень без `zubr-coder` — проверьте уровень ключа

Пользуетесь ещё zq remote — он работает как раньше, сессии в чате выглядят так же.