Jak bezpiecznie zainstalować OpenHands na serwerze VPS

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

OpenHands, dawniej znany jako OpenDevin, to autonomiczny agent inżynierii oprogramowania. Użytkownik zleca mu zadanie w języku naturalnym, a agent planuje pracę, pisze kod, wykonuje polecenia, analizuje wyjście i iteruje, aż zadanie zostanie ukończone. Narzędzie uruchamia się na własnym serwerze przy użyciu Docker, wskazując model językowy. Na serwerze VPS staje się ono agentem programistycznym, który pracuje pod nieobecność użytkownika.

Jeden fakt powinien determinować całą konfigurację. OpenHands nie tylko sugeruje kod, ale również go wykonuje. Aby to osiągnąć, kontener kontrolera montuje gniazdo Docker hosta w /var/run/docker.sock, co pozwala mu na tworzenie kontenerów typu sandbox dla każdego zadania. Każdy proces, który ma dostęp do gniazda Docker, może uruchomić nowy kontener z zamontowanym całym systemem plików hosta, co oznacza, że dostęp do gniazda jest równoznaczny z uprawnieniami root na maszynie. Z tego powodu serwer z OpenHands należy traktować jako środowisko uruchamiające niezaufany kod, ponieważ dokładnie tym się zajmuje. Każda decyzja dotycząca zabezpieczeń opisana poniżej wynika z tego założenia.

Wymagania

Wymagany jest serwer VPS z systemem Ubuntu 24.04, zainstalowanym środowiskiem Docker Engine w aktualnej wersji, co najmniej 4 GB pamięci RAM oraz klucz API do modelu językowego (OpenAI, Anthropic lub Google) albo lokalny model udostępniony przez Ollama na tym samym serwerze VPS. OpenHands obsługuje dziesiątki backendów modeli, więc wybór należy do użytkownika. Jeśli konfiguracja kontenerów jest nowym zagadnieniem, podstawy obsługi Docker na VPS zawierają informacje, na których opiera się ten przewodnik.

Instalacja przy użyciu Docker

OpenHands jest dostarczany jako dwa obrazy: obraz aplikacji, który uruchamiasz, oraz obraz agent-server, który jest pobierany w celu uruchomienia środowiska izolowanego (sandbox) dla każdego zadania. Uruchom go w następujący sposób, podstawiają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

Dwa szczegóły pozwolą uniknąć godziny poszukiwań przyczyny problemów. Obraz aplikacji oraz obraz agent-server celowo posiadają różne numery wersji, więc nie należy próbować ich ujednolicać: użyj tagu agent-server, który w dokumentacji jest przypisany do danej wersji aplikacji. Zwróć również uwagę na -p 127.0.0.1:3000:3000 zamiast -p 3000:3000. Ta pojedyncza zmiana decyduje o tym, czy interfejs WWW będzie dostępny tylko dla Ciebie, czy dla całego Internetu, o czym traktuje kolejna sekcja.

Ograniczenie dostępu do interfejsu Web UI z sieci publicznej

OpenHands udostępnia swój interfejs na porcie 3000. Interfejs ten steruje agentem wykonującym kod, więc wystawienie go do Internetu daje każdemu dostęp do procesu realizującego polecenia. Należy powiązać go z interfejsem zwrotnym (loopback), tak jak w powyższym poleceniu uruchomieniowym, a następnie łączyć się z nim z laptopa za pośrednictwem tunelu SSH:

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

Następnie otwórz http://127.0.0.1:3000 na własnym komputerze. Ruch przesyłany jest w ramach istniejącej sesji SSH, dzięki czemu żadna nowa usługa nie nasłuchuje na publicznym adresie IP. Nie każdy agent wymaga otwartego portu: sesje Claude Code na tym samym VPS komunikują się przez terminal, więc jedyną wystawioną usługą pozostaje SSH. Nawyk korzystania z interfejsu loopback i tunelowania warto stosować w przypadku każdego panelu sterowania agenta; dostęp do interfejsu skanowania open-kritt przez tunel działa w ten sam sposób, z tą różnicą, że wykorzystuje port 5173. W przypadku trwalszej konfiguracji należy umieścić usługę za VPN. W każdym przypadku należy skonfigurować firewall z domyślną polityką odrzucania połączeń (default-deny), aby uniknąć przypadkowego wystawienia usług. Należy pamiętać, że firewall ograniczony tylko do IPv4 pozostawia ten sam port otwarty dla IPv6, co stanowi lukę w firewallu IPv6, na którą naraża się wielu użytkowników.

Izolacja klucza modelu i poświadczeń repozytorium

OpenHands wymaga klucza API dla modelu oraz często tokena do klonowania i wypychania zmian do repozytoriów. Oba te elementy mogą generować koszty i działać w Twoim imieniu, dlatego należy traktować je jak hasła. Przechowuj je w pliku środowiskowym, do którego dostęp ma tylko odpowiednie konto. Nigdy nie umieszczaj ich w poleceniu uruchomieniowym, gdzie trafiają do historii powłoki i listy procesów, ani w plikach wewnątrz repozytorium git. Jeśli przechowujesz oryginały w samodzielnie hostowanym menedżerze haseł, zabezpiecz również ten serwer. Słabymi punktami sejfu są bowiem token administratora i plik kopii zapasowej, a nie same zaszyfrowane elementy, co szczegółowo opisuje utwardzanie Vaultwarden.

Uruchomienie na serwerze przeznaczonym do utylizacji

Ponieważ kontroler musi mieć dostęp do gniazda Docker, nie można w pełni odizolować OpenHands od hosta. Jedynym skutecznym zabezpieczeniem jest izolacja poprzez lokalizację: należy uruchomić OpenHands na dedykowanym serwerze VPS, który nie zawiera żadnych innych istotnych danych, a nie na maszynie obsługującej bazy danych czy strony WWW. Przed rozpoczęciem pracy należy wykonać snapshot i w razie potrzeby przywrócić system z tego obrazu, zamiast ufać środowisku, w którym przez tydzień wykonywany był kod wygenerowany przez agenta. Tani, jednorazowy serwer VPS o konkretnym przeznaczeniu jest odpowiednim środowiskiem dla tego narzędzia. Lokalizacja to jedyny mechanizm kontroli, jaki oferuje OpenHands w tym zakresie. Jeśli wymagana jest dodatkowa kontrola nad działaniami agenta przed uzyskaniem jego zgody, tryby uprawnień Claude Code pokazują, jak wygląda takie rozwiązanie na serwerze, który nie jest stale monitorowany.

Zabezpieczanie środowiska

Reszta to standardowa higiena serwerowa, która w tym przypadku jest istotniejsza niż zazwyczaj, ponieważ obciążenie wiąże się z wyższym ryzykiem. Utwórz nieuprzywilejowanego użytkownika administracyjnego zamiast pracować jako root, postępując zgodnie z uruchamianie usług jako nieuprzywilejowany użytkownik. Przenieś SSH na uwierzytelnianie wyłącznie za pomocą kluczy. Następnie wykonaj poniższą listę kontrolną i przechowuj ją w miejscu, w którym będziesz mieć do niej łatwy dostęp.

Aby zrozumieć działanie poszczególnych elementów, a nie tylko je uruchamiać, zapoznaj się z budowanie własnego agenta AI na VPS; w przypadku platformy typu low-code, self-hosting Dify stanowi łagodniejszy punkt wejścia.

FAQ

Czy uruchamianie OpenHands na serwerze jest bezpieczne?

Może być bezpieczne przy zachowaniu odpowiedniej ostrożności, jednak wiąże się z większym ryzykiem niż typowa aplikacja webowa. OpenHands tworzy i uruchamia kod, a jego kontroler posiada dostęp do gniazda Docker hosta, co jest równoznaczne z uprawnieniami root na maszynie. Aplikację należy uruchamiać na dedykowanym, tymczasowym serwerze VPS, na którym nie znajdują się żadne inne cenne dane. Interfejs webowy powinien być dostępny wyłącznie przez loopback za tunelem SSH lub VPN. Należy odizolować klucze dostępowe i odpowiednio zabezpieczyć system. Nie należy uruchamiać OpenHands obok ważnych usług produkcyjnych.

Dlaczego OpenHands wymaga dostępu do gniazda Docker?

OpenHands wykonuje każde zadanie w odizolowanym kontenerze typu sandbox. Aby to osiągnąć, aplikacja wymaga dostępu do demona Docker na hoście poprzez zamontowanie /var/run/docker.sock wewnątrz kontenera kontrolera. Daje to kontenerowi kontrolera możliwość zarządzania usługą Docker na hoście, co jest funkcją potężną, ale i ryzykowną. Z tego powodu host musi być traktowany jako środowisko uruchamiające kod niezaufany.

Czy OpenHands może korzystać z modelu lokalnego zamiast płatnego API?

Tak. OpenHands wspiera modele lokalne udostępniane przez Ollama lub vLLM. Dzięki temu można uruchomić aplikację w pełni samodzielnie, bez ponoszenia kosztów za tokeny i bez przesyłania danych poza serwer. Wymagana jest maszyna z odpowiednią ilością pamięci RAM dla wydajnego modelu programistycznego, zgodnie z wytycznymi dotyczącymi doboru zasobów zawartymi w poradniku Ollama.

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

Nie. Ponieważ aplikacja uruchamia kod generowany przez agenta i posiada dostęp do gniazda Docker, należy ją utrzymywać na oddzielnym, dedykowanym serwerze VPS, który w razie potrzeby można szybko odtworzyć. Współdzielenie zasobów z bazami danych, stronami WWW lub innymi usługami oznacza, że błąd agenta lub luka w jego zabezpieczeniach mogą doprowadzić do nieautoryzowanego dostępu do kluczowych komponentów systemu.