OpenHands Agent Canvas: удалённое развёртывание VM

По официальному руководству OpenHands, для одного пользователя подходит типовая VM с 2 vCPU и 4 ГБ RAM; при этом Agent Canvas запускает на машине не только интерфейс, но также Agent Server и автоматизационный бэкенд. Требования к VM и архитектура

Ноутбук засыпает — длинная задача обрывается.
Самое быстрое решение — перенести Agent Canvas на отдельную, постоянно включённую VM, сначала закрыть доступ через приватную сеть или SSH-туннель, а затем добавить API Key, TLS, постоянный запуск процесса и песочницу.

Эта статья предназначена для трёх групп:

• независимых разработчиков, у которых OpenHands прерывает работу после сна ноутбука;
• платформенных и DevOps-инженеров, которым нужен общий удалённый Agent Server для команды;
• руководителей разработки, планирующих запуск Xcode, симуляторов или других macOS-инструментов на отдельном узле.

Последняя проверка: 14 августа 2026 года. Команды, режим публичного запуска, модель бэкендов, переменная LOCAL_BACKEND_API_KEY, схема портов и актуальные материалы сверены с официальным руководством самохостинга, документацией VM-развёртывания, описанием архитектуры и журналом релизов Agent Canvas.

Сначала определите границу выполнения

Главная ошибка — установить OpenHands Agent Canvas прямо на личный компьютер, а затем пытаться закрыть все риски настройками интерфейса. Agent Server выполняет команды, читает и изменяет файлы, использует окружение машины и может обращаться к сети. Если сервис запущен без песочницы, агент фактически получает права среды, в которой работает. Это прямо отмечено в официальном README проекта.

Отдельная VM обычно лучше личного MacBook по четырём причинам:

1. Сон и закрытие крышки не влияют на процесс. Долгий агент продолжает работать после завершения SSH-сессии, если процесс запущен через systemd или другой менеджер.
2. Проще ограничить секреты. На VM можно не хранить личные SSH-ключи, пароли от рабочих сервисов и файлы из домашнего каталога.
3. Проще восстановление. VM можно пересоздать из образа или снимка, не затрагивая рабочую машину.
4. Проще разделить роли. Linux VM подходит для анализа кода, веб-тестов и большинства серверных сборок; macOS-узел добавляется только для Apple-инструментов.

У вас есть три возможные границы:

Архитектурно Agent Canvas — это фронтенд. Основное выполнение делает Agent Server, а автоматизации обслуживает отдельный automation backend. Один интерфейс может переключаться между локальным, удалённым и другими бэкендами. Документированная схема компонентов

Можно ли установить OpenHands Agent Canvas на облачный сервер?
Да. Официальная модель предусматривает облачную VM или выделенное оборудование, включая Mac Mini. Но устанавливать сервис на публичный адрес без сетевого фильтра и ключа нельзя: Agent Server предоставляет агенту доступ к файловой системе, командам и сети.

Этап 1. Подготовьте отдельную VM и закройте публичный доступ

Для стандартного Linux-сценария официальная инструкция использует Ubuntu 24.04 LTS как подходящий вариант по умолчанию, Node.js 22.x, uv, curl и git. Указанная конфигурация 2 vCPU и 4 ГБ RAM относится к сценарию одного пользователя, а не к гарантированному ресурсу для параллельных тяжёлых задач. Не переносите её автоматически на командную нагрузку.

Установите базовые зависимости:

sudo apt-get update
sudo apt-get install -y curl git
curl -LsSf https://astral.sh/uv/install.sh | sh

Node.js установите через выбранный вами менеджер версий, пакетный репозиторий или официальный способ дистрибутива. Перед запуском проверьте:

node --version
npm --version
uv --version
git --version

Сетевой firewall должен применяться на уровне облачной сети, а не только внутри операционной системы. Для первого запуска оставьте доступным только SSH с вашего IP-адреса или VPN-сети.

В официальной схеме внутренний ingress слушает 127.0.0.1:8000, а отдельные компоненты используют внутренние порты 3001, 18000 и 18001. Они не должны быть доступны из Интернета; наружу публикуется только обратный прокси. Это параметры текущей документированной схемы, а не обещание, что порты никогда не изменятся.

Этап 2. Запустите минимальный стек только через SSH-туннель

Сгенерируйте отдельный ключ для этого экземпляра:

export LOCAL_BACKEND_API_KEY="$(openssl rand -base64 32)"
printf '%s\n' "$LOCAL_BACKEND_API_KEY"

Команда openssl rand -base64 32 создаёт 32 случайных байта, то есть 256 бит случайности. Сохраните значение в менеджере секретов или защищённом локальном хранилище. Не помещайте его в Git, .env, который попадает в репозиторий, статический фронтенд или диагностический лог.

Запустите Canvas в публичном режиме:

npx @openhands/agent-canvas --public

В этом режиме ключ не встраивается во фронтенд: пользователь вводит его на стартовом экране, а API-запросы передают проверочный заголовок. Без --public ключ автоматически передаётся фронтенду, что удобно для локального использования, но не подходит для публично доступного сервиса. Описание режима запуска и API Key

С локального компьютера создайте туннель:

ssh -N \
  -L 8000:127.0.0.1:8000 \
  user@your-vm-host

После этого откройте в браузере http://127.0.0.1:8000. Если используется Docker-образ, путь интерфейса может отличаться: в официальном README для Docker указан адрес http://localhost:8000/canvas. Проверяйте именно тот способ запуска, который выбран в вашей VM.

Минимальная приёмка состоит не из одного открытия страницы:

На этом этапе не открывайте 8000, 18000, 18001 или статический порт в облачном firewall. SSH-туннель одновременно проверяет сервис и не создаёт преждевременную точку входа.

Этап 3. Добавьте ключи, права и изоляцию

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

Минимальный набор ограничений:

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

Docker-песочница меняет границу доступа: агент работает не непосредственно в основной файловой системе, а внутри контейнерного окружения с явно смонтированным каталогом проекта. В официальном Docker-сценарии нужно заранее создать PROJECTS_PATH, после чего только проекты из этого каталога становятся доступными контейнеру. Руководство по Docker Sandbox

Пример базового запуска контейнерного варианта:

export PROJECTS_PATH="$HOME/projects"
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

docker run -it --rm \
  -p 8000:8000 \
  -v "$HOME/.openhands:/home/openhands/.openhands" \
  -v "${PROJECTS_PATH}:/projects" \
  ghcr.io/openhands/agent-canvas:1.7.0

Тег образа должен быть сверен с текущим README и журналом релизов перед запуском. Не заменяйте его на latest без причины: фиксированный тег упрощает воспроизводимость и откат. Если вы используете прямой запуск через npx, это другая модель обновления — команда скачивает опубликованный пакет.

Проверьте границу намеренно:

• создайте файл за пределами разрешённого рабочего каталога и убедитесь, что агент не может его прочитать;
• отправьте запрос без X-Session-API-Key и подтвердите отказ;
• проверьте, что секрет не появляется в ps, журнале запуска или собранных статических файлах;
• попросите агента выполнить безопасную команду, которая должна быть запрещена политикой;
• проверьте, что рабочая директория после перезапуска остаётся ожидаемой.

Важно: Docker не превращает небезопасную конфигурацию в безопасную автоматически. Смонтированный каталог, Docker-сокет, переменные окружения и права пользователя нужно рассматривать как часть реального периметра.

Этап 4. Настройте постоянный процесс и HTTPS

tmux подходит для короткой проверки:

export LOCAL_BACKEND_API_KEY="<сохранённый-ключ>"
tmux new-session -d -s canvas \
  'npx @openhands/agent-canvas --public'

Для постоянной работы используйте systemd:

[Unit]
Description=Agent Canvas
After=network.target

[Service]
Environment=LOCAL_BACKEND_API_KEY=<сохранённый-ключ>
ExecStart=/usr/bin/npx @openhands/agent-canvas --public
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Путь к npx проверьте командой command -v npx; в разных способах установки он может отличаться. Сохраните unit, затем выполните:

sudo systemctl daemon-reload
sudo systemctl enable --now agent-canvas
sudo systemctl status agent-canvas

Проверьте восстановление после трёх событий:

1. закрытия SSH-сессии;
2. аварийного завершения процесса;
3. перезагрузки VM.

Для публичного доступа добавьте доменное имя и обратный прокси. В документированной архитектуре nginx принимает HTTPS, а затем передаёт запросы единому ingress на 127.0.0.1:8000. Это уменьшает количество наружных точек и позволяет централизованно управлять сертификатом.

Проверьте не только загрузку HTML:

• HTTPS открывается без ошибки сертификата;
• API-запросы проходят с правильным ключом;
• потоковые события и WebSocket не обрываются через несколько секунд;
• HTTP-запросы не обходят прокси и не попадают напрямую на внутренние порты;
• журнал не растёт бесконтрольно;
• сертификат продлевается автоматически;
• после перезапуска nginx и Agent Canvas порядок запуска сохраняется.

Как не потерять задачу после разрыва SSH?
Не связывайте жизненный цикл агента с интерактивным терминалом. tmux сохраняет процесс при закрытии сессии, но для VM, которая должна переживать перезагрузку и сбои, используйте systemd с Restart=on-failure. Состояние проекта и историю задач дополнительно проверяйте после восстановления, потому что постоянный запуск процесса не означает автоматическую синхронизацию всех локальных файлов.

Какие порты действительно нужны удалённому Agent Server

Наружу не следует открывать все порты, которые встречаются в схеме. В описанном официальном режиме самохостинга внешнему клиенту нужен адрес обратного прокси, а не прямое подключение к Agent Server или automation backend.

Какие порты открывать для удалённого Agent Server?
В безопасной схеме — только SSH для администрирования и 443 для внешнего HTTPS-доступа. 8000, 18000, 18001 и 3001 оставляйте локальными либо доступными только из приватной сети. Если вы используете SSH-туннель, публичный 443 вообще не требуется.

Этап 5. Подключите удалённый бэкенд к локальному Canvas

Если локальный интерфейс уже настроен, не обязательно переносить фронтенд на VM. В Agent Canvas откройте управление бэкендами и добавьте удалённый экземпляр:

• имя — понятный идентификатор, например team-vm;
• адрес — HTTPS-URL прокси или http://localhost:8000 для SSH-туннеля;
• ключ — значение LOCAL_BACKEND_API_KEY.

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

Переключение бэкенда не синхронизирует автоматически незакоммиченные изменения с ноутбука. Перед запуском задачи выберите один из процессов:

• закоммитить и отправить изменения в Git;
• передать рабочую ветку на VM;
• использовать отдельный транспорт файлов;
• работать с репозиторием, который изначально клонирован на VM.

Проверьте после переключения:

Когда к VM нужно добавить удалённый Mac

Для большинства задач Linux VM достаточно: анализа исходников, рефакторинга, тестирования веб-сервиса, сборки серверного приложения, запуска линтеров и работы с контейнерами.

Удалённый Mac нужен, если задача зависит от macOS-инструментов:

• Xcode и xcodebuild;
• iOS или macOS SDK;
• симулятора;
• Apple-кодов подписи и профилей provisioning;
• нативных фреймворков macOS;
• проверки поведения приложения на реальном Apple-окружении.

Когда OpenHands следует переводить на удалённый Mac?
Только когда Linux VM не может выполнить конкретный шаг toolchain. Не направляйте весь поток разработки на Mac из-за одного этапа: оставьте анализ, подготовку изменений и серверные тесты на Linux, а сборку Apple-проекта передавайте на изолированный macOS-бэкенд. Для выбора такого окружения используйте руководство по удалённой аренде Mac, сопоставляя инструменты проекта, способ подключения и требования к постоянной работе.

Перед долгосрочной эксплуатацией выполните полный тест на реальном репозитории:

1. запустите задачу на VM;
2. закройте SSH-клиент;
3. дождитесь завершения или восстановите подключение;
4. перезапустите сервис;
5. повторите задачу на отдельном рабочем каталоге;
6. передайте Apple-часть на Mac;
7. проверьте артефакт, подпись и историю событий.

Финальная проверка перед постоянной эксплуатацией

Используйте этот список как условие перехода от эксперимента к рабочему сервису:

• [ ] VM не является вашим личным ноутбуком и может быть пересоздана.
• [ ] Входящий трафик ограничен firewall на уровне сети.
• [ ] Внешние пользователи не видят 8000, 18000, 18001 и 3001.
• [ ] Для Agent Canvas задан отдельный LOCAL_BACKEND_API_KEY.
• [ ] Ключ не находится в Git, фронтенде, командной истории или логах.
• [ ] Рабочий каталог агента отделён от домашнего каталога администратора.
• [ ] Для недоверенных задач выбрана Docker-песочница или отдельная VM.
• [ ] SSH-туннель успешно открывает интерфейс до настройки публичного доступа.
• [ ] Через HTTPS проходят потоковые события и длительные ответы.
• [ ] systemd запускает сервис после перезагрузки.
• [ ] Логи ротируются и не содержат секретов.
• [ ] Незакоммиченные локальные изменения не принимаются за синхронизированные удалённые файлы.
• [ ] Для задач Xcode создан отдельный маршрут на удалённый Mac.
• [ ] Выполнена хотя бы одна проверка восстановления и одна полная сборка из реального репозитория.

Если текущая схема — личный ноутбук, открытый через SSH или удалённый рабочий стол, у неё остаются три системных недостатка: сон прерывает длительные задачи, локальные секреты оказываются рядом с агентом, а доступ к macOS-инструментам зависит от состояния одной физической машины. Отдельная VM снимает проблему непрерывности, но не заменяет Mac для Xcode и не решает сама по себе вопрос изоляции.

Поэтому разумная схема обычно двухуровневая: Linux VM для постоянного Agent Canvas и серверных задач, а удалённый Mac — только для Apple-сборок, симуляторов и подписи. Если вам нужно проверить, хватит ли существующей VM или пора добавлять постоянно работающий Mac-узел, начните со среды SSHMac для удалённой разработки и сопоставьте её с приведённым чек-листом, а не переносите на macOS задачи, которым достаточно Linux.