Як запустити OpenHands на VPS через Docker

Що таке OpenHands і який ризик потрібно зрозуміти насамперед

OpenHands, раніше OpenDevin, — це автономний агент для розроблення програмного забезпечення. Ви ставите йому завдання звичайною мовою, а він планує роботу, пише код, виконує команди, читає результати та повторює ці кроки, доки не завершить завдання. Ви запускаєте його на власному сервері за допомогою Docker і підключаєте до мовної моделі. На VPS він стає агентом для написання коду, який працює, поки вас немає.

Один факт має визначати всю конфігурацію. OpenHands не лише пропонує код, а й виконує його. Для цього його controller container монтує Docker socket хоста за адресою /var/run/docker.sock, щоб створювати sandbox containers для кожного завдання. Будь-який процес, який може взаємодіяти з Docker socket, здатен запустити новий контейнер із монтуванням усієї файлової системи хоста. Це означає, що доступ до socket фактично дає права root на машині. Тому сприймайте сервер з OpenHands як сервер, на якому виконується ненадійний код, адже саме це він і робить. Усі наведені нижче заходи hardening випливають із цього.

Що вам потрібно

Вам потрібен VPS під керуванням Ubuntu 24.04 із нещодавно випущеною версією Docker Engine, щонайменше 4 GB RAM і API key для мовної моделі (OpenAI, Anthropic або Google) або локальна модель, яку обслуговує Ollama на тому самому VPS. OpenHands підтримує десятки бекендів моделей, тому вибір залишається за вами. Якщо ви ще не налаштовували контейнери, основи Docker на VPS охоплюють матеріал, потрібний для цього посібника.

Встановлення за допомогою Docker

OpenHands постачається у вигляді двох образів: образу застосунку, який ви запускаєте, та образу agent-server, який він завантажує для запуску sandbox кожного завдання. Запустіть його так, замінивши теги на актуальні з документації проєкту:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands \
  docker.openhands.dev/openhands/openhands:1.8

Два моменти допоможуть уникнути зайвої плутанини. Образ застосунку та образ agent-server навмисно мають різні номери версій, тому не намагайтеся зробити їх однаковими: використовуйте тег agent-server, який документація вказує для вашої версії застосунку. Також зверніть увагу на -p 127.0.0.1:3000:3000, а не на -p 3000:3000. Ця єдина зміна визначає, чи буде Web UI доступний лише вам, чи всьому інтернету. Саме про це йдеться в наступному розділі.

Не відкривайте Web UI у публічному інтернеті

OpenHands обслуговує свій інтерфейс на порту 3000. Цей інтерфейс керує агентом, який виконує код, тому публікація інтерфейсу в інтернеті дає кожному, хто його знайде, віддалений доступ до процесу, що виконує команди. Прив’яжіть його до loopback, як у наведеній вище команді запуску, і підключайтеся до нього зі свого ноутбука через SSH-тунель:

ssh -L 3000:127.0.0.1:3000 you@your-vps

Потім відкрийте http://127.0.0.1:3000 на власному комп’ютері. Трафік проходить через наявний SSH-сеанс, і в публічному інтернеті не з’являється новий порт, що прослуховується. Не кожному агенту взагалі потрібен порт: сеанси Claude Code на тому самому VPS обмінюються повідомленнями через термінал, тому назовні ви відкриваєте лише сам SSH. Такий самий підхід із loopback і тунелем варто застосовувати до кожної панелі агента, яку ви розміщуєте; доступ до інтерфейсу сканування open-kritt через тунель працює так само, лише через порт 5173. Для постійнішої конфігурації розмістіть його за VPN. У будь-якому разі встановіть перед сервером firewall із політикою default-deny, щоб нічого не стало доступним випадково. Пам’ятайте, що firewall, який охоплює лише IPv4, залишає той самий порт відкритим через IPv6. Саме цей пропуск у правилах IPv6 firewall часто стає причиною проблем.

Ізолюйте ключ моделі та облікові дані репозиторіїв

OpenHands потребує API key для своєї моделі, а часто й token для клонування та push до ваших репозиторіїв. Обидва секрети можуть спричинити витрати та діяти від вашого імені, тому поводьтеся з ними як із паролями. Зберігайте їх у файлі середовища, який може читати лише потрібний обліковий запис. Ніколи не додавайте їх до команди запуску: у такому разі вони потраплять до історії shell і списку процесів. Також ніколи не зберігайте їх у файлі всередині git-репозиторію. Якщо оригінальні секрети зберігаються у self-hosted password manager, захистіть і цей сервер, оскільки слабкими місцями vault зазвичай є admin token і backup file, а не самі зашифровані елементи, як описано в матеріалі про посилене налаштування Vaultwarden.

Запускайте його на сервері, який можна безпечно знищити

Оскільки контролер має доступ до Docker socket, повністю ізолювати OpenHands від хоста неможливо. Реальний спосіб зменшити ризик — ізоляція розміщенням: запускайте OpenHands на окремому VPS, де немає інших важливих для вас даних або сервісів. Не запускайте його на сервері, де також працює база даних або вебсайт. Створіть snapshot перед початком роботи. Після цього відновлюйте сервер із цього snapshot, а не покладайтеся на систему, яка тиждень виконувала код, написаний агентом. Недорогий одноцільовий VPS, який можна безпечно утилізувати, — відповідне середовище для OpenHands. OpenHands фактично дає вам лише один регулятор — місце розміщення. Якщо ви також хочете контролювати, скільки дій агент може виконати до зупинки для запиту підтвердження, режими дозволів Claude Code показують, як працює цей другий механізм на сервері, за яким ніхто не стежить.

Захистіть сервер

Решта — стандартна гігієна сервера. Але тут вона важливіша, ніж зазвичай, оскільки це робоче навантаження ризикованіше, ніж зазвичай. Створіть непривілейованого адміністративного користувача замість роботи від імені root, дотримуючись інструкцій запуск сервісів від імені непривілейованого користувача. Переведіть SSH на автентифікацію лише за ключами. Потім виконайте наведений нижче контрольний список і збережіть його там, де ви знову його побачите.

Щоб зрозуміти складові системи, а не просто виконати команди, перегляньте матеріал створення власного AI-агента на VPS; для платформи з меншим обсягом коду підійде self-hosting Dify як простіший початковий варіант.

FAQ

Чи безпечно запускати OpenHands на сервері?

Це можливо за умови обережного налаштування, але ризик вищий, ніж для звичайного вебзастосунку, оскільки OpenHands записує та запускає код, а його контролер має доступ до Docker socket хоста, що фактично означає права root на машині. Запускайте його на виділеному одноразовому VPS, де немає інших цінних даних, залишайте його Web UI доступним лише через loopback і використовуйте SSH tunnel або VPN, ізолюйте його ключі та посильте захист системи. Не запускайте його поруч із важливими сервісами.

Навіщо OpenHands потрібен Docker socket?

OpenHands запускає кожне завдання в новому sandbox container і просить Docker daemon хоста створити цей контейнер, монтувавши /var/run/docker.sock у свій контролер. Це дає controller container контроль над Docker на хості. Такий доступ потужний і ризикований, тому сам хост потрібно вважати системою, на якій запускається недовірений код.

Чи може OpenHands використовувати локальну модель замість платного API?

Так. OpenHands підтримує локальні моделі, доступні через Ollama або vLLM, тому його можна повністю розгорнути на власній інфраструктурі без оплати за кожен токен і без передавання даних за межі сервера. Потрібна машина з достатнім обсягом пам’яті для продуктивної coding model. Це те саме питання щодо підбору ресурсів, яке розглянуто в посібнику з Ollama.

Чи варто запускати OpenHands на основному сервері?

Ні. Оскільки OpenHands запускає код, створений агентом, і має доступ до Docker socket, розміщуйте його на окремому VPS для однієї задачі, який ви готові перебудувати. Спільне розміщення з базою даних, вебсайтом або іншими сервісами означає, що помилка агента або вразливість у ньому може надати доступ до ресурсів, яких він не повинен був торкатися.