Instalacja OpenHands na VPS przez Docker

Czym jest OpenHands i jakie ryzyko należy zrozumieć w pierwszej kolejności

OpenHands (dawniej OpenDevin) to autonomiczny agent inżynierii oprogramowania. Zadanie podaje się mu w języku naturalnym, a agent planuje pracę, pisze kod, wykonuje polecenia, odczytuje wyniki i iteruje aż do zakończenia zadania. Program uruchamia się na własnym serwerze za pomocą Docker i łączy z modelem językowym. Na maszynie VPS staje się agentem programistycznym działającym w tle.

Kluczowy aspekt konfiguracji: OpenHands nie tylko sugeruje kod, ale go wykonuje. Aby to umożliwić, kontener kontrolera montuje gniazdo Docker hosta w /var/run/docker.sock, co pozwala na tworzenie kontenerów typu sandbox dla każdego zadania. Każdy proces mający dostęp do gniazda Docker może uruchomić nowy kontener montujący cały system plików hosta. Oznacza to, że dostęp do gniazda jest równoważny uprawnieniom root na maszynie. Należy traktować serwer z OpenHands jako maszynę uruchamiającą niezaufany kod. Wszystkie poniższe kroki zabezpieczające wynikają z tego faktu.

Wymagania

Wymagany jest VPS z systemem Ubuntu 24.04, aktualnym silnikiem Docker, minimum 4 GB pamięci RAM oraz klucz API dla modelu językowego (OpenAI, Anthropic lub Google) lub lokalnego modelu obsługiwanego przez Ollama na tym samym VPS. OpenHands obsługuje wiele backendów modeli. Jeśli nie pracowano wcześniej z kontenerami, podstawy Docker na VPS wyjaśniają założenia niniejszego przewodnika.

Instalacja za pomocą Docker

OpenHands składa się z dwóch obrazów: obrazu aplikacji oraz obrazu agent-server, który pobiera do obsługi piaskownicy (sandbox) każdego zadania. Należy użyć poniższej komendy, stosując aktualne tagi z dokumentacji projektu:

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

Dwie uwagi pozwalają uniknąć błędów. Obrazy aplikacji i agent-server mają celowo różne numery wersji; nie należy próbować ich wyrównywać. Należy użyć tagu agent-server, który dokumentacja przypisuje do danej wersji aplikacji. Należy również zwrócić uwagę na -p 127.0.0.1:3000:3000 zamiast -p 3000:3000. Ta zmiana decyduje o tym, czy interfejs Web UI jest dostępny tylko lokalnie, czy przez cały internet (szczegóły w następnej sekcji).

Odcięcie interfejsu Web UI od publicznego internetu

OpenHands udostępnia interfejs na porcie 3000. Interfejs ten steruje agentem wykonującym kod, więc wystawienie go do internetu daje każdemu użytkownikowi zdalną ścieżkę do procesu wykonującego polecenia. Należy przypisać interfejs do pętli zwrotnej (loopback), tak jak w powyższej komendzie, i łączyć się z nim z laptopa przez tunel SSH:

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

Następnie należy otworzyć http://127.0.0.1:3000 na własnej maszynie. Ruch odbywa się w ramach istniejącej sesji SSH, a na publicznym internecie nie działa żadne nowe nasłuchiwanie. W celu uzyskania trwałej konfiguracji zaleca się użycie VPN. W każdym przypadku należy zastosować firewall typu default-deny, aby uniknąć przypadkowego wystawienia usług. Należy pamiętać, że firewall ograniczający tylko IPv4 pozostawia ten sam port otwarty w IPv6, co stanowi lukę w firewallu IPv6, na którą wpada wielu użytkowników.

Izolacja klucza modelu i poświadczeń do repozytoriów

OpenHands wymaga klucza API dla modelu oraz często tokena do operacji git (clone/push). Oba te elementy mogą generować koszty lub działać w imieniu użytkownika, dlatego należy traktować je jak hasła. Należy przechowywać je w pliku środowiskowym dostępnym tylko dla uprawnionego konta. Nie należy umieszczać ich bezpośrednio w komendzie uruchomieniowej (zostają w historii powłoki i liście procesów) ani w plikach wewnątrz repozytorium git.

Uruchamianie na maszynie przeznaczonej do utylizacji

Ze względu na konieczność trzymania gniazda Docker, nie można w pełni odizolować OpenHands od hosta. Skuteczną metodą mitygacji jest izolacja poprzez lokalizację: należy uruchamiać OpenHands na dedykowanym VPS, który nie przechowuje żadnych innych istotnych danych. Nie należy uruchamiać go na serwerze, na którym działają bazy danych lub strony internetowe. Przed rozpoczęciem należy wykonać migawkę (snapshot) systemu, a następnie przywracać system z tej migawki zamiast ufać maszynie, na której przez tydzień działał kod wygenerowany przez agenta. Tani, jednorazowy VPS o jednym przeznaczeniu jest optymalnym rozwiązaniem.

Zabezpieczenie maszyny

Pozostałe kroki to standardowa higiena serwera. Jest ona tutaj ważniejsza niż zwykle ze względu na wyższe ryzyko operacji. Należy utworzyć nieuprzywilejowanego użytkownika administratora zamiast pracować na koncie root, stosując zasady uruchamiania usług jako użytkownik nieuprzywilejowany. Należy skonfigurować SSH tak, aby dopuszczało wyłącznie uwierzytelnianie kluczem. Następnie należy wykonać poniższą listę kontrolną i zachować ją do późniejszego użytku.

Aby zrozumieć mechanizmy działania, a nie tylko je uruchamiać, należy zapoznać się z budowaniem własnego agenta AI na VPS; dla platform wymagających mniej kodowania rozwiązaniem jest self-hosting Dify.

FAQ

Czy uruchamianie OpenHands na serwerze jest bezpieczne?

Może być bezpieczne przy zachowaniu odpowiednich środków ostrożności, ale jest bardziej ryzykowne niż w przypadku standardowych aplikacji webowych. Agent pisze i wykonuje kod, a jego kontroler posiada dostęp do gniazda Docker hosta, co daje mu de facto uprawnienia root. Należy używać dedykowanego, przeznaczonego do utylizacji VPS bez innych ważnych danych, trzymać interfejs Web UI na loopback (przez tunel SSH lub VPN), izolować klucze i zabezpieczyć system. Nie należy uruchamiać go obok kluczowych usług.

Dlaczego OpenHands wymaga gniazda Docker?

OpenHands uruchamia każde zadanie w nowym kontenerze typu sandbox. Wymaga to od hosta (poprzez zamontowanie /var/run/docker.sock w kontrolerze) utworzenia tych kontenerów. Daje to kontenerowi kontrolera władzę nad Dockerem na hoście, co jest potężne, ale ryzykowne. Dlatego host musi być traktowany jako system uruchamiający niezaufany kod.

Czy OpenHands może używać lokalnego modelu zamiast płatnego API?

Tak. OpenHands obsługuje lokalne modele serwowane przez Ollama lub vLLM. Pozwala to na pełną samowystarczalność bez kosztów za tokeny i bez wysyłania danych poza serwer. Wymagana jest maszyna z odpowiednią ilością pamięci RAM dla wybranego modelu programistycznego (szczegóły w przewodniku Ollama).

Czy powinienem uruchamiać OpenHands na głównym serwerze?

Nie. Ze względu na wykonywanie kodu przez agenta oraz dostęp do gniazda Docker, należy używać do tego oddzielnego, jednorazowego VPS, który można łatwo przebudować. Współdzielenie zasobów z bazą danych, stronami internetowymi lub innymi usługami oznacza, że błąd agenta lub błąd w kodzie może dotknąć zasoby, do których agent nie powinien mieć dostępu.