OpenHands: установка на свой сервер, термины и чек-лист

Подробности, цифры, термины и чек-лист по теме «OpenHands: установка на свой сервер». Страница справочника целиком: OpenHands.

Коротко о теме

OpenHands установка на VPS: uv и Python 3.12 или docker run с сокетом Docker, от 4 ГБ памяти, модель по OpenAI-совместимому API, вход через SSH.

Подробности по разделам

OpenHands: агент, который работает в своей песочнице

Песочница отличает OpenHands от терминальных агентов вроде Aider: команды агента не выполняются прямо в вашей системе. Цена за это: Docker на сервере и запас памяти и диска под образы.

Установка OpenHands через uv и через docker run

Через Docker напрямую. Команда из документации, где порт привязан только к локальному адресу: Версии образов в этой команде меняются с выпусками, берите актуальные из документации. Готового файла docker compose в инструкции нет, но эти же параметры переносятся в compose один к одному.

Как подключить модель к OpenHands

Внутри работает библиотека LiteLLM. Так подключается AI Gateway Таймвеб Клауд с оплатой в рублях за токены и модель на своём GPU через vLLM. Если модель запущена на том же сервере вне контейнера, используйте адрес host.docker.internal: для этого в команде и стоит параметр --add-host.

Ключевые цифры

Готового файла в документации нет, но параметры команды docker run (сокет Docker, том ~/.openhands, порт 3000, host.docker.internal) переносятся в compose без изменений.
В лаунчере openhands serve порт 3000 не настраивается.
При запуске через docker run меняют левую часть параметра -p, например 127.0.0.1:8300:3000.

Термины на странице

GPU: GPU это видеокарта. На сервере её используют для нейросетей, рендера и расчётов.
LLM: LLM это большая языковая модель. Для запуска на своём сервере ей нужна видеопамять или много оперативной.
SSH: SSH это защищённое подключение к серверу через командную строку. Вход по ключу безопаснее, чем по паролю.
Python: Python это язык программирования. На сервере на нём часто пишут ботов и скрипты.
Docker: Docker запускает программы в контейнерах: всё нужное для работы упаковано в образ.
VPS: VPS это виртуальный сервер: часть физической машины с выделенными ядрами, памятью и диском и собственной операционной системой.

Что проверить

Храните данные контейнеров в томах.
Закрепляйте версии образов, а не latest.
Ограничьте ресурсы контейнеров, чтобы один не съел весь сервер.
Выберите конфигурацию по памяти и диску под задачу, процессор обычно вторичен.
Проверьте тип виртуализации: KVM даёт свою систему и гарантированные ресурсы.
Уточните, входит ли IPv4 и сколько стоит трафик сверх пакета.