Удалённая разработка в ZCode: SSH и Docker для AI-агента GLM-5.2
Удалённая разработка в ZCode позволяет запустить воркспейс внутри удалённого хоста или локального контейнера. После успешного подключения чтение файлов, выполнение терминальных команд, Git-операции и работа ZCode Agent происходят в целевом окружении — при этом десктопный клиент продолжает управлять аккаунтом, настройками моделей, точками входа задач и интерфейсом.
Это удобно для проектов, которым нужен сервер, внутренняя машина, GPU-бокс для разработки или контейнерное окружение. Вы сохраняете десктоп-опыт ZCode на своей машине, а агент напрямую работает с кодом, зависимостями и командной строкой в целевой среде.
Когда это нужно
- Код проекта и зависимости существуют только на удалённом Linux-сервере.
- Нужны GPU-ресурсы, внутренние сервисы, базы данных или специализированный тулчейн на удалённой машине.
- Хочется изолировать зависимости внутри локального Docker-контейнера вместо изменения хост-окружения.
- Локальная машина — неподходящее место для запуска проекта, но вы хотите, чтобы ZCode Agent мог разрабатывать, отлаживать и проверять его.
Перед подключением
Перед использованием SSH убедитесь, что:
- Ваша машина достижима через SSH до целевого хоста.
- Вы знаете адрес хоста, порт и имя пользователя.
- Целевой хост поддерживает вход по паролю, либо у вас готов файл приватного ключа и (опционально) passphrase к нему.
- Если вы используете
~/.ssh/config, выполнитеssh <HostAlias>в терминале заранее, чтобы убедиться, что алиас работает.
Перед использованием Docker убедитесь, что:
- Локальный Docker-демон запущен.
- Целевой контейнер уже стартовал.
- Контейнер имеет доступ к директории проекта и содержит shell, Git, Node.js или иной тулчейн, нужный проекту.
- Если контейнер не появился в списке, имя контейнера или его ID можно ввести вручную.
Открытие удалённого подключения из ZCode
В главном окне ZCode нажмите на текущее имя проекта в правом нижнем углу, чтобы открыть меню воркспейса, и выберите Remote Connection. Мастер сначала предложит выбрать тип подключения: SSH — к удалённому хосту, Docker — к локальному контейнеру.
После выбора типа нажмите Next — откроется соответствующая страница конфигурации. Слева мастер показывает текущие шаги: выбор типа, заполнение конфигурации, подключение и выбор директории. Если подключение затягивается, используйте лог, чтобы понять текущий прогресс.
Подключение к удалённому хосту по SSH
Страница SSH — место, где вы вводите параметры подключения к удалённому хосту.
Настраивайте в таком порядке:
- SSH config alias (опционально): ZCode читает доступные алиасы из локального SSH-конфига. Выбор алиаса автоматически подставляет host, port, username и путь к приватному ключу. Если алиас не нужен — оставьте «Do not use alias» и заполните поля вручную.
- Host: введите адрес или IP удалённого хоста, например
192.168.1.100илиdev.example.com. - Port: по умолчанию
22. Если сервер использует кастомный порт — введите реальный. - Username: логин на удалённом хосте, например
root,ubuntuилиdeploy. - Аутентификация: выберите Password или Private key. Пароли не сохраняются в истории подключений. Для приватного ключа укажите путь к файлу ключа; если у ключа есть passphrase — введите и её.
- Способ загрузки ресурсов: при первом подключении ZCode готовит компоненты на удалённой стороне. Download locally then upload — десктоп скачивает ресурсы и загружает их на хост. Download on remote server — удалённый хост обращается к CDN ZCode напрямую, что может ускорить процесс, но требует у хоста доступа к сети и инструментов скачивания, распаковки и проверки контрольной суммы.
После заполнения нажмите Start connection. При успехе ZCode перейдёт к выбору удалённой директории — её откроют как воркспейс.
Подключение к локальному контейнеру через Docker
Страница Docker — место, где вы выбираете или вводите работающий локальный контейнер.
Если ZCode обнаруживает работающие контейнеры — выберите один из Select a running container. Открытие выпадающего списка обновляет перечень контейнеров, чтобы вы не выбрали остановленный.
Если список пуст или Docker не возвращает полный перечень, введите имя контейнера или его ID вручную в поле Container, например:
zcode-dev
7f3a8c2d9e10Docker-подключения используют docker exec и docker cp для входа в локальный контейнер. Это оптимально для dev-контейнеров с уже подготовленным окружением проекта. Если контейнер не запущен, выполните docker ps в терминале и убедитесь, что он виден.
Первое подключение и логи
После нажатия Start connection мастер переходит на страницу Connecting. Здесь показывается живой лог подключения: проверки окружения, подготовка удалённых ресурсов, инициализация рантайма и причины сбоев.
Первое подключение обычно медленнее последующих, так как ZCode должен подготовить удалённый сервис и рантайм агента в целевой среде. Последующие подключения переиспользуют подготовленные ресурсы, если только не изменилась версия или ресурсы отсутствуют.
При неудаче внизу страницы появится сводка ошибок. Нажмите Back, чтобы поправить конфигурацию и повторить, либо Feedback, чтобы ZCode приложил текущий лог и скриншот для диагностики.
После входа в удалённый воркспейс
После успешного подключения и выбора директории ZCode открывает её как удалённый воркспейс. Работать можно почти как с локальным:
- Просматривать и редактировать удалённые файлы в дереве.
- Просить агента прочитать код, поправить файлы, прогнать тесты или выполнить команды.
- Использовать терминал для shell внутри удалённого хоста или контейнера.
- Работать с Git: статус, ветки, коммиты.
- Заново входить в недавние удалённые воркспейсы из списка.
Файлы проекта, выполнение команд и рантайм агента остаются в целевой среде. Провайдеры моделей, логин, глобальные настройки и статистика использования — на десктоп-клиенте.
FAQ
Почему не появляется мой SSH config alias?
ZCode читает только те алиасы, которые может распарсить из локального SSH-конфига. Если список пуст, проверьте, что ~/.ssh/config существует и корректно отформатирован, а затем выполните ssh <alias> в терминале для проверки. Даже если алиас не появился, host, port, username и данные аутентификации можно заполнить вручную.
Когда выбирать «Download on remote server»?
Выбирайте Download on remote server, когда удалённый хост быстрее достукивается до CDN ZCode или когда загрузка с локальной машины медленная. Серверу нужны curl или wget, tar и хотя бы один инструмент контрольной суммы — sha256sum, shasum или openssl. Если у хоста нет доступа в публичный интернет — используйте Download locally then upload.
Что делать, если на странице Docker нет контейнеров?
Выполните в терминале:
docker psЕсли работающих контейнеров нет — сначала запустите нужный. Если терминал показывает контейнер, а список ZCode пуст, введите имя или ID контейнера вручную и подключитесь.
Где искать причину сбоя подключения?
Начните с последней строки ERROR в Connection log или со сводки ошибок внизу страницы. Частые причины: недостижимый SSH-хост, неверный порт, логин/пароль, неправильная passphrase приватного ключа, отсутствие инструментов скачивания/распаковки на сервере или незапущенный Docker-контейнер. Если ошибка неинформативна — нажмите Feedback и приложите лог.
Может ли Mobile Remote Control создать новое SSH- или Docker-подключение?
Нет. Mobile Remote Control управляет воркспейсом, уже открытым на десктопе. Удалённые воркспейсы SSH и Docker нужно сначала создать с десктопа; затем с телефона можно через Remote Control войти в открытый воркспейс и продолжить проверку или давать инструкции.
Дальнейшие шаги
Remote Control
Открывайте текущий воркспейс ZCode с телефона и управляйте десктоп-сессией агента удалённо.
ADE Tools
Как задачи, файлы, терминальные процессы, контекст браузера и инструменты ревью работают вместе в единой среде разработки.
Заметка практика: связка ZCode + SSH — это ровно то, чего мне не хватало в Cursor. Cursor держит проект локально и SSH-тулчейн там — скорее костыль, тогда как ZCode нативно поднимает рантайм агента прямо на сервере: команды
npm test, миграции БД и сборка идут на месте, без пересылки файлов. Для клиентских проектов на Битриксе я завожу отдельный Docker-контейнер с нужной версией PHP, подключаю ZCode по Docker — и агент работает в среде, идентичной прод-серверу. Один важный нюанс: первый коннект реально медленный (закачка компонентов), поэтому заведи себе привычку держать dev-контейнер запущенным постоянно, а не поднимать его под каждую задачу.
Локализованный гайд по официальной документации ZCode. Оригинал на английском.
