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

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

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

Что нужно

Установленный zq — одна команда, см. установку. Нужна версия 0.22.3-5 или новее: zq --version.
Аккаунт ZubrIQ. Ключ руками не нужен: при первом запуске zq remote напечатает ссылку на вход (zubriq.by) — откройте её на любом устройстве, хоть с ноутбука, пока zq крутится на сервере по SSH. После «Выдать токен» ключ сам придёт в CLI и сохранится — как при первом запуске самого zq. Если вы уже входили в zq на этой машине, он возьмёт сохранённый ключ. Ключ можно задать и руками: ZUBRIQ_API_KEY (my.zubriq.by → API-ключи) или --api-key.
Выход в интернет с машины (исходящий HTTPS/WSS до console.zubriq.by). Входящие порты, белый IP, VPN — не нужны, работает за NAT.

Запуск

cd /path/to/project
zq remote

Что произойдёт (первый раз — с входом через браузер):

Вход через браузер — откройте ссылку (можно на другом устройстве) и подтвердите:
  https://zubriq.by/cli/auth?state=…
Вход выполнен, ключ сохранён — дальше zq входа не попросит.
Регистрирую сессию в https://console.zubriq.by…
Раннер готов: /path/to/project
Сессия в чате: https://zubriq.by/sandbox/01m1…
Ctrl+C — остановить.
[relay] туннель поднят

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

Параметры

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

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

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

Остановка

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

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

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

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

Симптом	Причина и что делать
`Вход не удался`	вход не подтверждён за 10 минут или нажата «Отмена» — запустите снова и откройте напечатанную ссылку (на любом устройстве) либо задайте `ZUBRIQ_API_KEY`
в браузере `127.0.0.1 … ERR_CONNECTION_REFUSED`	старая сборка `zq` (до 0.22.3-5) ждала ответ на самой машине — обновите: `curl -fsSL https://zubriq.by/install \| bash`
`консоль не приняла регистрацию: HTTP 401`	ключ отозван или чужой — выпустите новый в кабинете
`HTTP 409 too_many_sessions`	у вас уже 3 живых сессии — остановите лишнюю в чате
`HTTP 503 code_disabled`	раннеры выключены в этой среде (стейдж) — используйте zubriq.by
`[relay] relay отверг подключение` в цикле	сессию остановили в чате или истёк её срок — перезапустите `zq remote`
`zq: command not found`	установщик кладёт `zq` в `~/.local/bin` — добавьте его в `PATH` или откройте новый терминал
в чате `403 key not allowed to access model`	ключ выпущен на уровень без `zubr-coder` — проверьте уровень ключа