ИИ-агент

Как развернуть песочницу OpenHands в 2026 году, чтобы изолировать задачи ИИ-кодирования от хоста macOS?

Агент запускает скрипт из незнакомого репозитория, а в рабочей области видны файлы Mac и конфигурации, которые к задаче не относятся.

Самый безопасный вариант для обычного кодирования — развертывание песочницы OpenHands в поддерживаемом официальной документацией контейнерном режиме и монтирование только каталога проекта; Docker socket и учётные данные хоста не следует открывать без конкретной необходимости. Контейнер ограничивает среду выполнения, но не превращает доступные ему файлы и полномочия в недоступные.

Руководство для разработчиков, которые впервые запускают OpenHands на Mac и хотят отделить проект от остальной файловой системы.
Команды, которым нужно разводить разные репозитории, учётные данные и сетевой доступ по отдельным задачам.
Технические руководители, оценивающие, где заканчивается контейнерная среда и начинается нативная сборка для macOS.

Сначала определите, где будут выполняться задачи OpenHands

До установки важно развести понятия «запуск приложения OpenHands» и «запуск кода, который агент пишет или проверяет». Это связанные, но не тождественные части системы: интерфейс и управляющий компонент могут запускаться отдельно от среды, где исполняются команды задачи. В документации OpenHands описаны режимы песочницы и отдельный путь для Docker; актуальный выбор следует делать по текущему обзору режимов песочницы OpenHands, а не по заголовку старого примера, который случайно оказался первым в поиске.

Для работы с незнакомым репозиторием предпочтительнее контейнерная среда: в ней можно ограничить видимые каталоги, а исполняемые команды не запускаются напрямую в обычном окружении пользователя Mac. Это не абсолютная гарантия безопасности. Если контейнеру доступны чувствительные файлы, полномочия Docker daemon или открытая сетевая связность, агент всё равно может использовать эти возможности в пределах предоставленных прав.

Вариант запуска Когда уместен Основная граница риска
Непосредственный запуск на Mac Только если задача доверенная и заранее понятны права процесса и область доступа Команды исполняются в окружении хоста; ошибочная команда может затронуть доступные ему файлы
Docker sandbox OpenHands Изменение кода, тестирование и работа с репозиторием, которому нельзя безоговорочно доверять Изоляция зависит от монтирований, полномочий контейнера, сетевой конфигурации и доступа к Docker daemon
Отдельная среда для сборки под macOS Когда нужны Xcode или другие нативные инструменты Apple Это самостоятельная среда сборки; контейнерная песочница сама по себе не предоставляет macOS toolchain

Не смешивайте современные инструкции установки с материалами для V0. В репозитории документации отдельно обозначен старый путь Docker Runtime для V0; он не является универсальной инструкцией для текущей версии. Для развёртывания сверяйте команды, способ запуска и параметры с текущим руководством OpenHands по локальной установке и актуальным разделом Docker sandbox.

Условие выбора режима

  • Если агент должен править код, запускать тесты или исполнять скрипты из репозитория, выбирайте поддерживаемый Docker sandbox и заранее ограничивайте доступные ему каталоги.
  • Если задача требует только чтения, разделите код и справочные материалы: проект предоставьте в соответствии с необходимыми правами, а документацию подключите без записи, если конфигурация это допускает.
  • Если команда намерена исполнять агентские команды прямо на macOS, сначала обоснуйте, почему контейнерный режим не подходит, и отдельно проверьте права процесса на файлы и секреты.
  • Если задача требует Xcode или нативного компонента macOS, не считайте Docker-контейнер заменой такой среды. Разделите генерацию и проверку кода в контейнере и нативную сборку в отдельном окружении.

Подготовьте проектную область до запуска

Создайте отдельную папку для конкретного репозитория или задачи и поместите туда только те файлы, которые агенту действительно нужны. Не предоставляйте весь домашний каталог пользователя, корень диска и общие папки с настройками «на всякий случай». При работе с несколькими кодовыми базами разделение каталогов помогает обнаружить ошибку в монтировании до того, как она превратится в случайный доступ между проектами.

Сам факт, что агент работает в контейнере, не означает, что содержимое bind mount защищено от изменений. Docker описывает bind mount как способ сделать путь хоста доступным контейнеру; режим только для чтения задаётся настройкой монтирования. Поэтому, если агенту передан проект с правом записи, его команды могут менять или удалять содержимое этого каталога. Для справочных данных используйте режим без записи, когда он подходит сценарию; параметры и ограничения сверяйте с документацией Docker о bind mounts и режиме read-only.

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

Проверка рабочей области перед монтированием:

  • [ ] В отдельной папке находится только текущий проект и нужные ему файлы.
  • [ ] Рабочая папка не является домашним каталогом или корнем файловой системы.
  • [ ] Справочные материалы отделены от файлов, которые агент должен менять.
  • [ ] В конфигурации нет дополнительных путей к ключам, настройкам пользователя и посторонним репозиториям.
  • [ ] Права записи соответствуют задаче, а не удобству первоначальной настройки.

Настройте контейнер, сокет и сетевой вход

Следуйте актуальной процедуре запуска Docker sandbox из документации OpenHands. Именно там следует сверить имя и тег образа, параметры запуска и текущие требования к Docker; здесь намеренно не приведена неизменяемая команда, поскольку она может устареть или не соответствовать выбранному режиму. Проверьте, какие части системы являются приложением OpenHands, какие — контейнером для выполнения задач, а какие — Docker daemon на хосте.

Особое внимание требуется Docker socket. Он служит точкой доступа к Docker daemon, а значит, его передача контейнеру — это не эквивалент монтирования папки проекта. Docker отдельно предупреждает, что доступ к daemon следует защищать: возможности клиента зависят от выданных ему полномочий и не ограничиваются чтением одного исходного каталога. Практическое правило простое: если в документации выбранного режима нет требования передавать управление Docker приложению, не добавляйте socket по собственной инициативе. Если требование есть, проверьте, какой компонент его получает и почему, по официальному руководству Docker по защите доступа к daemon.

Сетевой вход в интерфейс также задаётся отдельно от рабочей папки. Локальная разработка и публичная доступность — разные сценарии: перед публикацией порта выясните, на каком адресе хоста он доступен. Документация Docker объясняет, как публикация порта и привязка к адресу хоста влияют на доступность сервиса; ориентируйтесь на описание привязки опубликованных портов. Не переносите параметры локального запуска на сервер, доступный извне, без проверки адреса привязки, сетевых правил и требований к аутентификации.

У OpenHands, Docker sandbox и Docker socket разные роли. Агент может управлять рабочим процессом через приложение; среда выполнения исполняет команды; socket, если он предоставлен, даёт доступ к управлению Docker daemon. Если эти роли свести к общему понятию «контейнер», легко незаметно расширить полномочия агента — например, добавить возможность создавать контейнеры, хотя задаче достаточно изменять файлы одного проекта.

Выдайте отдельные и минимальные учётные данные

Контейнер не отзывает полномочия, которые вы передали самому агенту. Для настройки отдельно рассмотрите секреты модели, доступ к репозиторию и права на рабочую папку. Эти секреты решают разные задачи и не должны автоматически становиться взаимозаменяемыми: доступ для чтения к коду не обязан разрешать публикацию изменений, а ключ внешнего API не должен предоставлять доступ к личным ресурсам, не связанным с работой.

Для приватного репозитория или внешнего API используйте специально подготовленные учётные данные с ограниченными правами и сроком действия, если сервис это поддерживает. Документация GitHub рекомендует защищать API-учётные данные и не раскрывать их в приложениях или журналах; ориентируйтесь на рекомендации GitHub по защите API credentials. После завершения задачи отзовите временный токен, если он больше не нужен. Порядок истечения и отзыва токенов GitHub описан в руководстве по срокам действия и отзыву токенов.

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

Проведите пробный запуск по всей цепочке

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

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

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

Завершите задачу и разделите нативную сборку

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

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

Контейнерная среда предназначена для выполнения агентских команд в выбранном окружении. Она не становится macOS-системой и не предоставляет автоматически Xcode или другие нативные инструменты Apple. Если задаче нужна сборка приложения для macOS, отделите подготовку или проверку исходного кода в Docker sandbox от нативного этапа сборки. Документация Apple описывает App Sandbox как механизм ограничения приложений и предоставления им разрешённых возможностей; это не основание считать его синонимом контейнера или доказательством того, что любая команда, запущенная на Mac, автоматически изолирована. Сверяйте назначение механизма по официальному описанию App Sandbox для macOS.

Частые вопросы о развёртывании

Можно ли считать контейнер OpenHands полной защитой Mac?

Нет. Контейнер помогает отделить среду выполнения от обычного окружения хоста, но доступные bind mounts, сеть и переданные полномочия остаются значимыми. Если агент может записывать в каталог проекта, он может менять его содержимое; если ему передан Docker socket, круг доступных операций меняется. Поэтому проверяйте фактические монтирования и разрешения, а не делайте вывод о безопасности только по наличию Docker.

Надо ли запускать агент прямо на macOS ради доступа к файлам?

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

Сопоставьте текущий способ работы с задачей на Mac

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

Выберите подходящую среду для нативных задач

Когда задача ограничивается редактированием и тестированием кода в контейнере, отдельный Mac может быть не нужен. Но если требуется Xcode или другой нативный инструментариум macOS, оцените самостоятельную среду Mac для этапа сборки, сохраняя отдельные границы доступа для OpenHands. Информацию о вариантах KuzCloud можно начать изучать с описания сервиса, а вопросы по подготовке среды уточнить через раздел помощи KuzCloud. Такой Mac — возможная среда для нативной работы, а не дополнительная гарантия безопасности контейнера OpenHands.

Запустите OpenHands на отдельном облачном Mac

В KuzCloud вы получаете выделенный Mac mini M4, чтобы запускать задачи OpenHands отдельно от локального хоста macOS.

Подключайтесь к машине по SSH или через VNC и проверяйте настройки среды, доступов и монтирования на отдельном узле.