Як встановити OpenHands на VPS через Docker

Що таке OpenHands та головний ризик, який слід зрозуміти насамперед

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

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

Що вам знадобиться

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

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

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

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-сесійне з'єднання, і в публічному інтернеті нічого не прослуховується. Для постійного використання краще використовувати VPN. У будь-якому разі встановіть фаєрвол з політикою "заборонено все за замовчуванням" (default-deny), щоб нічого не було відкрито випадково. Пам'ятайте, що фаєрвол, що налаштований лише для IPv4, залишає той самий порт відкритим для IPv6 — це прогалина у фаєрволі IPv6, на якій часто помиляються.

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

OpenHands потрібен API-ключ для моделі та часто токен для клонування та пушу у ваші репозиторії. Обидва ресурси можуть витрачати гроші та діяти від вашого імені, тому ставтеся до них як до паролів. Зберігайте їх у файлі середовища (environment file), до якого має доступ лише відповідний обліковий запис. Ніколи не передавайте їх безпосередньо в команді запуску, оскільки вони потраплять у історію команд (shell history) та список процесів, і ніколи не зберігайте їх у файлах всередині git-репозиторію.

Запускайте на машині, яку не шкода видалити

Оскільки контролер повинен мати доступ до Docker socket, ви не можете повністю ізолювати OpenHands від хоста. Єдиний дієвий метод — ізоляція шляхом розміщення: запускайте OpenHands на виділеному VPS, на якому немає нічого іншого важливого. Не запускайте його на сервері, де також працюють ваша база даних або вебсайт. Зробіть знімок системи (snapshot) перед початком роботи та відновлюйте систему з цього знімка замість того, щоб довіряти машині, на якій тиждень виконувався код, створений агентом. Дешевий, одноразовий VPS виступає найкращим рішенням.

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

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

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

FAQ

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

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

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

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

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

Так. OpenHands підтримує локальні моделі через Ollama або vLLM, тому ви можете використовувати його повністю self-hosted без витрат за токени та без передачі даних за межі вашого сервера. Вам знадобиться машина з достатньою кількістю пам'яті для повноцінної моделі кодування (питання обсягу пам'яті аналогічне до того, що розглядається в посібнику Ollama).

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

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