Если вам нужен быстрый первый запуск OpenHands Agent Canvas, выбирайте десктопную preview-версию или npx; если Agent должен менять локальный проект в заданных границах — используйте Docker, а для постоянной работы, общего доступа и более мощных ресурсов подключайте удалённый бэкенд. Это правило сохраняется и тогда, когда установка OpenHands Agent Canvas выполняется на macOS, Windows или Linux: Desktop App упрощает запуск, но сама по себе не создаёт полноценную песочницу.

Эта статья предназначена тем, кто впервые хочет проверить Agent Canvas и не уверен в требованиях Node.js или uv. Она также пригодится пользователям Docker, которым нужно ограничить доступ Agent к файлам, и платформенным инженерам, готовящим постоянно работающий бэкенд для команды.

Последнее обновление — 6 сентября 2026 года; сведения сверены с официальными руководствами по установке, подключению бэкенда и выпуску Agent Canvas 1.16.0.

Сначала определите место выполнения Agent

У Agent Canvas есть как минимум три разных слоя, которые нельзя смешивать:

  • Canvas-клиент — интерфейс, открываемый в Desktop App, браузере или локальном процессе;
  • активный бэкенд — служба, принимающая задания и управляющая сессией Agent;
  • среда исполнения — локальная машина, Docker-контейнер, виртуальная машина или удалённый хост, где Agent действительно читает файлы и запускает команды.

Именно третий слой определяет реальный уровень доступа. Архитектура этих компонентов описана в официальной схеме Agent Canvas. Если клиент работает на вашем ноутбуке, а бэкенд находится на удалённой VM, Agent не получает доступ к рабочей папке ноутбука только потому, что интерфейс открыт локально. И наоборот: удобное окно Desktop App не ограничивает права процесса, если сам бэкенд запускается непосредственно от вашей учётной записи.

Решение по условиям: что выбрать до установки

Отметьте первое условие, которое соответствует вашей задаче:

  • [ ] Нужно только быстро проверить интерфейс и выполнить безопасную пробную задачу. Выбирайте Desktop App. Если приложение недоступно для вашей платформы, переходите на npx.
  • [ ] Нужно запустить короткий эксперимент без постоянного управления пакетом. Выбирайте npx, но используйте отдельную тестовую папку и заранее проверьте версию Node.js.
  • [ ] Agent должен изменять локальный репозиторий, а доступ к остальным файлам нужно ограничить. Выбирайте Docker с монтированием только нужного каталога.
  • [ ] Нужно повторять одну и ту же среду после переустановки или передавать её другому инженеру. Выбирайте Docker с зафиксированным образом и отдельным постоянным томом.
  • [ ] Задача должна продолжаться после закрытия ноутбука, сна или смены устройства. Поднимайте Remote Backend на отдельной VM или удалённом хосте.
  • [ ] Несколько разработчиков должны работать с общей средой. Сначала разделите общий интерфейс, общий бэкенд и общую среду исполнения; затем настройте права и восстановление.
  • [ ] Задача требует Xcode, симулятора iOS или другого macOS-инструмента. Выделяйте отдельный пул Mac и не рассчитывайте, что обычный Linux-бэкенд заменит macOS.

Если одновременно подходят два условия, выбирайте вариант по более строгому ограничению. Например, для короткого теста достаточно Desktop App, но если тест выполняется над чувствительным репозиторием, приоритет получает Docker. Если нужна постоянная работа и ограниченный доступ к файлам, выбирайте удалённый Docker-бэкенд, а не просто удалённый Desktop App.

Быстрый первый запуск: Desktop App, npx и npm

Официальная документация указывает для Agent Canvas несколько путей, включая npm, npx, Docker, исходный код и подключение внешнего бэкенда. Десктопные приложения для macOS, Windows и Linux на указанную дату всё ещё имеют статус раннего preview, поэтому их стоит рассматривать как наиболее простой способ знакомства, а не как окончательную корпоративную платформу. Проверяйте актуальные команды на официальной странице установки Agent Canvas, а не переносите команды из старого обсуждения или локального скрипта.

Для первого запуска варианты различаются следующим образом:

  • Desktop App уменьшает число ручных действий и быстрее приводит вас к экрану Canvas. Его преимущество — низкий порог входа, а не дополнительная изоляция.
  • npx удобен для разового запуска или проверки текущего пакета без отдельного глобального управления установкой. При этом вам всё равно придётся учитывать версию Node.js, права текущего пользователя и процесс обновления.
  • npm-установка лучше подходит, если вы хотите явно контролировать пакет, запускать его из проекта и включать установку в собственный сценарий разработки. За это вы платите дополнительным обслуживанием зависимостей.
  • Сборка из исходного кода оправдана, когда вы меняете сам Canvas или тестируете ветку разработки. Для первого знакомства она добавляет лишние точки отказа.

Нужно ли устанавливать Node.js для Agent Canvas Desktop App?

Для готового Desktop App отдельная установка Node.js обычно не является главным шагом: приложение поставляется как клиент, а необходимые действия описаны в официальной инструкции для конкретной платформы. Для запуска через npx или npm Node.js уже относится к обязательной части локального окружения. Установщик Node.js и способы установки по менеджеру пакетов приведены в официальной документации Node.js.

Последовательность проверки выглядит следующим образом.

  1. Откройте страницу установки и выберите инструкцию для вашей операционной системы. Сверьте, указана ли нужная вам Desktop App как preview, и не смешивайте команды от разных вариантов запуска.
  2. Если вы выбрали npx или npm, проверьте наличие Node.js способом, указанным в официальной документации, и убедитесь, что терминал видит именно установленную версию, а не старую копию из другого менеджера пакетов.
  3. Запустите Canvas без доступа к рабочему репозиторию. Создайте отдельную тестовую папку с небольшим текстовым файлом.
  4. Откройте интерфейс и проверьте, какой бэкенд активен. Если Canvas предлагает подключить существующий сервер, не считайте локальным тот процесс, который фактически работает на удалённой машине.
  5. Дайте Agent минимальное задание: прочитать тестовый файл, создать вторую версию с очевидным именем и сообщить, где она сохранена.
  6. Сверьте результат в файловой системе, а не только в окне чата. Успешный ответ Agent не доказывает, что он использовал именно ту папку, которую вы предполагали.
  7. Остановите процесс, снова откройте Canvas и проверьте, что происходит с сессией и созданными файлами. Это покажет разницу между сохранёнными данными, историей интерфейса и реально продолжающейся задачей.

Критерий успешной установки здесь не «окно открылось», а подтверждённая цепочка: Agent получил задание, прочитал разрешённый файл, создал ожидаемый результат, а после остановки вы понимаете, что сохранилось и где именно.

Важно. Не начинайте проверку с рабочего репозитория, SSH-ключей, файла окружения или каталога с персональными документами. При первом локальном запуске вы ещё не проверили границу прав процесса.

Локальный проект требует явной границы файлов

Безопасна ли локальная установка OpenHands?

Она может быть приемлемой для изолированной тестовой папки, но сам факт локальной установки не означает автоматической безопасности. Если бэкенд запускается от вашей учётной записи, Agent потенциально наследует доступ, которым обладает этот процесс. Риск зависит не от того, насколько аккуратно выглядит интерфейс, а от разрешений пользователя, подключённых каталогов, секретов в окружении и разрешённых команд.

Здесь есть несколько скрытых ограничений:

  • рабочий каталог может оказаться шире, чем вы думаете, если вы открыли родительскую папку или смонтировали весь домашний каталог;
  • секреты могут попасть в проект через файлы конфигурации, переменные окружения, SSH-агент или инструменты командной строки;
  • остановка Canvas не обязательно отменяет уже запущенный дочерний процесс;
  • восстановление сессии не равно восстановлению состояния команды: часть данных может находиться в контейнере, часть — в томе, а часть — в рабочей папке;
  • у Desktop App нет основания считаться серверной изоляцией только потому, что это отдельное приложение.

Для небольшого несекретного проекта прямой локальный запуск может быть разумным. Перед этим создайте отдельную рабочую копию, удалите ключи и токены, ограничьте права каталога и запишите, какие процессы запускает Agent. Если изменение легко отменить через Git, цена ошибки ниже, чем в незакоммиченном или единственном экземпляре проекта.

Docker предпочтительнее, когда требуется зафиксировать границы. В контейнер можно смонтировать конкретную папку проекта, а не весь домашний каталог, отдельно хранить конфигурацию и удалить среду после неудачного эксперимента. Но контейнер не равен полноценной изоляции арендаторов: Docker требует правильной настройки сокетов, прав, томов и сетевого доступа. Ограничения и модель безопасности раскрыты в документации Docker Engine.

Сравнивайте варианты по фактическим границам:

  • при прямом запуске Agent работает в локальной среде пользователя и видит то, что доступно этому процессу;
  • при Docker-запуске Agent работает внутри контейнера, но видит все каталоги, которые вы явно смонтировали;
  • при удалённом бэкенде Agent видит файловую систему удалённого хоста, а не автоматически локальный диск вашего компьютера.

Docker делает запуск воспроизводимым, но не магически безопасным

Docker полезен не только как способ спрятать установку. Его главное преимущество — повторяемость: одинаковый образ, одинаковый набор подключённых каталогов и предсказуемая процедура запуска. Это особенно важно, если вы несколько раз переустанавливаете Agent Canvas или передаёте проект другому инженеру.

Для контейнерного сценария действуйте по следующей схеме:

  1. Прочитайте официальное руководство Agent Canvas для Docker и зафиксируйте используемый способ запуска, имя образа и параметры подключения.
  2. Создайте отдельную папку для проекта и отдельное место для постоянных данных. Не объединяйте исходный код, секреты и служебное состояние в один общий каталог.
  3. Перед запуском проверьте монтирования: путь проекта должен быть явным, а доступ к домашнему каталогу, Docker socket и системным директориям следует исключить, если задача без них обходится.
  4. Определите, где хранятся настройки и история. Если они находятся только в файловом слое контейнера, удаление контейнера может уничтожить их.
  5. Используйте Docker volume либо другой документированный механизм постоянного хранения для данных, которые должны пережить остановку. В документации Docker о томах объясняется, почему жизненный цикл тома отделён от жизненного цикла контейнера.
  6. Запустите минимальное задание и проверьте не только результат, но и доступ: попросите Agent прочитать файл внутри разрешённой папки, затем убедитесь, что файл за пределами монтирования недоступен.
  7. Остановите контейнер, запустите его снова и проверьте три отдельных факта: сохранился ли проект, сохранились ли настройки, восстановилась ли активная задача.
  8. После проверки удалите тестовые токены, неиспользуемые контейнеры и временные тома, если они больше не нужны.

В чём различие между Desktop App и Docker на практике?

Desktop App быстрее для первого знакомства: меньше ручной настройки, проще открыть интерфейс и быстрее получить первый результат. Docker требует больше решений до запуска, зато позволяет формально описать рабочий каталог, постоянные данные и процедуру повторного старта. Ни один вариант не следует выбирать только по количеству команд в инструкции: для локального кода важнее, что Agent может прочитать и что произойдёт после остановки.

Для команды контейнер также не решает вопрос доверия автоматически. Если несколько пользователей получают доступ к одному бэкенду, им могут быть видны общие задания, журналы или файлы, а ошибочная публикация Docker-порта способна сделать сервис доступным из нежелательной сети. Поэтому перед совместным использованием нужны отдельные учётные записи или прокси с аутентификацией, ограничение сетевого доступа и контроль секретов.

Постоянная работа начинается с отдельного бэкенда

Локальный ноутбук удобен до тех пор, пока он включён, не ушёл в сон, не потерял сеть и не требуется освободить ресурсы для другой работы. Долгая задача, запущенная из терминала, может зависеть от жизненного цикла терминала, локального процесса и текущего соединения с Canvas. Закрытие окна не должно считаться безопасным способом остановки, а оставленный процесс — гарантией продолжения.

Когда нужен Agent Canvas Remote Backend?

Переносите бэкенд на отдельную VM или удалённый хост, если задача должна переживать закрытие ноутбука, смену устройства, временный обрыв сети или регулярный доступ нескольких разработчиков. В таком сценарии Canvas остаётся клиентом, а Agent и рабочая директория находятся на сервере. Базовая схема VM описана в официальной инструкции по самохостингу.

Проверяйте удалённую схему по таким шагам:

  1. Подготовьте отдельную VM или удалённый хост с необходимыми инструментами и дисковым пространством.
  2. Установите бэкенд строго по текущей официальной инструкции, не копируя старые параметры порта из чужого примера.
  3. Проверьте локальное подключение на самом сервере до публикации сервиса в интернет.
  4. Настройте Canvas на адрес удалённого бэкенда и убедитесь, что запрос уходит именно на ожидаемый хост.
  5. Запустите тестовую задачу, отключите локальный клиент и вновь подключитесь после восстановления сети.
  6. Проверьте, восстановилась ли сессия, остались ли файлы и какие журналы доступны после повторного входа.
  7. Только после этого добавляйте командный доступ, прокси, доменное имя и внешний маршрут.

Публичное размещение требует дополнительного слоя защиты: аутентификации, TLS, сетевых ограничений, обновления компонентов и контроля журналов. Нельзя считать URL с нестандартным портом достаточной защитой. Если удалённый сервис принимает команды Agent, открытый в интернет порт становится частью поверхности атаки, а не просто удобным способом подключения.

Командный сценарий требует разделить интерфейс, бэкенд и среду

Для команды часто говорят «нужен общий Canvas», хотя на деле могут иметься в виду три разные задачи:

  • общий интерфейс, через который участники видят задания;
  • общий бэкенд, который принимает и распределяет работу;
  • общая среда исполнения, где лежат проект, инструменты и секреты.

Это не одно и то же. Можно предоставить общий интерфейс, но разделить бэкенды по проектам. Можно подключить один удалённый бэкенд, но запускать независимые контейнеры с разными каталогами. Можно использовать один сервер, но отказаться от общей рабочей директории, чтобы ошибка одного задания не затронула другое.

Может ли Desktop App подключиться к командному самохостингу?

Если версия Canvas и ваш бэкенд поддерживают подключение внешнего сервера, Desktop App может выступать клиентом для такого подключения. Однако это нужно подтвердить текущей схемой подключения и проверить на практике: статус preview, формат URL, аутентификация и совместимость компонентов могут измениться. Не делайте вывод о поддержке только потому, что клиент умеет открываться локально.

Для платформенной команды критерии выбора должны быть следующими:

  • Права: кто может создать задачу, открыть результат, изменить файлы или посмотреть журналы.
  • Восстановление: что произойдёт после перезапуска контейнера, VM или самого бэкенда.
  • Воспроизводимость: можно ли повторить среду из описания, образа и фиксированного набора монтирований.
  • Разделение инструментов: Linux-проекты можно размещать в общем пуле, а задачи, требующие macOS, Xcode или iOS Simulator, — в отдельном пуле Mac.
  • Секреты: токены CI, SSH-ключи и файлы окружения не должны попадать в общий каталог только ради удобства Agent.
  • Наблюдаемость: должны быть понятны активные задания, владелец сессии, состояние процесса и причина неудачного восстановления.

Для Apple-зависимого проекта удалённый Mac — это не просто более мощный Linux-бэкенд. Требуются физическая или виртуальная macOS-среда, нужная версия Xcode, доступ к симуляторам и корректная политика учётных записей. Перед переносом такого процесса изучите условия аренды Mac mini в SSHMac, а не обещайте команде совместимость на основании одного успешного запуска интерфейса.

Оценка вариантов по сценарию, а не по простоте установки

Для первого запуска оценка Desktop App самая высокая: он быстрее приводит к проверке интерфейса и минимального задания. По изоляции он получает низкую оценку, если бэкенд работает с правами локального пользователя. npx удобен для короткого эксперимента, но уступает контейнеру в воспроизводимости. Docker получает высокую оценку за границы каталогов и повторяемость, однако требует дисциплины при настройке томов, сети и прав. Remote Backend выигрывает в постоянной работе и командном доступе, но добавляет TLS, аутентификацию, обслуживание хоста и сетевую задержку.

Используйте следующий порядок выбора:

  • Если вы не готовы обслуживать Node.js и хотите только проверить Agent на безопасной папке — начинайте с Desktop App.
  • Если Desktop App недоступен для вашей платформы или нужно быстро протестировать пакет — используйте npx.
  • Если Agent должен менять код, который нельзя выпускать за пределы рабочей папки, переходите на Docker.
  • Если задачу нужно продолжать без ноутбука — запускайте бэкенд на VM или удалённом хосте.
  • Если команда работает с разными ОС — разделяйте Linux- и macOS-пулы вместо попытки сделать одну универсальную среду.
  • Если вам нужны стабильные длительные нагрузки, физические интерфейсы или полный контроль над машиной, аренда либо собственная выделенная Mac-среда может быть разумнее временного локального запуска; условия стоит сверить через русскоязычный раздел SSHMac.

Где заканчивается удобство локальной схемы

Локальная Desktop App быстрее запускается, но оставляет вас зависимым от состояния ноутбука, его сна, локальных прав и текущей сессии. Прямой npx или npm-запуск добавляет управление версиями Node.js и зависимостями. Docker требует более тщательной настройки, зато даёт явную границу проекта и понятный путь к повторному старту. Удалённый бэкенд снимает зависимость от личного компьютера, но переносит ответственность на VM, сеть, TLS, аутентификацию, резервирование и обновления.

Поэтому переход на удалённую схему не является автоматическим улучшением для каждого пользователя. Если вы лишь проверяете Agent на безопасной папке, серверная инфраструктура будет избыточной. Если же локальный ноутбук регулярно прерывает долгие задачи, команда должна подключаться к одной среде, а проект требует ресурсов или macOS-инструментов, локальная установка становится слабым долгосрочным вариантом: она хуже переживает отключение устройства, сложнее стандартизируется и не даёт ясного разделения доступа.

В таком случае SSHMac может быть полезнее как временная или проектная удалённая Mac-среда: вы получаете отдельный хост для задач, которым нужен macOS, вместо того чтобы держать постоянный Agent на личном компьютере и вручную восстанавливать процесс после каждого прерывания. Для краткого теста оставайтесь на Desktop App или Docker; для постоянной командной работы сначала подготовьте удалённый бэкенд и только затем подключайте Canvas.