OpenHands auf VPS selbst hosten Anleitung

Was OpenHands ist und das erste Risiko, das man verstehen muss

OpenHands, ehemals OpenDevin, ist ein autonomer Agent für Software Engineering. Sie geben ihm eine Aufgabe in natürlicher Sprache vor. Er plant die Arbeit, schreibt Code, führt Befehle aus, liest die Ausgabe und iteriert, bis die Aufgabe erledigt ist. Sie betreiben ihn auf Ihrem eigenen Server mit Docker und verbinden ihn mit einem Sprachmodell. Auf einem VPS wird er zu einem Coding-Agenten, der arbeitet, während Sie abwesend sind.

Ein Fakt bestimmt Ihr gesamtes Setup. OpenHands schlägt nicht nur Code vor, sondern führt ihn aus. Um dies zu tun, mountet der Controller-Container den Host-Docker-Socket bei /var/run/docker.sock, damit er Sandbox-Container für jede Aufgabe erstellen kann. Alles, was mit dem Docker-Socket kommunizieren kann, kann einen neuen Container starten, der Ihr gesamtes Host-Dateisystem mountet. Das bedeutet, dass der Socket-Zugriff effektiv Root-Rechte auf der Maschine entspricht. Behandeln Sie den OpenHands-Server daher als einen Server, auf dem nicht vertrauenswürdiger Code läuft, da er genau das tut. Alle unten aufgeführten Sicherheitsmaßnahmen leiten sich daraus ab.

Was Sie benötigen

Sie benötigen einen VPS mit Ubuntu 24.04 und einer aktuellen Docker Engine, mindestens 4 GB RAM und einen API-Key für ein Sprachmodell (OpenAI, Anthropic oder Google) oder ein lokales Modell, das über Ollama auf demselben VPS bereitgestellt wird. OpenHands unterstützt Dutzende von Model-Backends; die Wahl liegt bei Ihnen. Wenn Sie noch nie Container eingerichtet haben, decken die Grundlagen von Docker auf einem VPS das ab, was dieser Leitfaden voraussetzt.

Installation mit Docker

OpenHands wird in zwei Images ausgeliefert: dem Application-Image, das Sie ausführen, und einem Agent-Server-Image, das es für die Sandbox jeder Aufgabe herunterlädt. Führen Sie es wie folgt aus und ersetzen Sie die aktuellen Tags durch die Tags aus der Projektdokumentation:

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

Zwei Details ersparen Ihnen eine Stunde Fehlersuche. Das App-Image und das Agent-Server-Image haben absichtlich unterschiedliche Versionsnummern; versuchen Sie nicht, diese anzugleichen. Verwenden Sie das Agent-Server-Tag, das in der Dokumentation für Ihre App-Version vorgesehen ist. Achten Sie zudem auf -p 127.0.0.1:3000:3000 statt -p 3000:3000. Diese eine Änderung ist der Unterschied zwischen einer Web-UI, die nur Sie erreichen können, und einer, die für das gesamte Internet erreichbar ist, worum es im nächsten Abschnitt geht.

Die Web-UI vom öffentlichen Internet fernhalten

OpenHands stellt seine Benutzeroberfläche auf Port 3000 bereit. Diese Schnittstelle steuert einen Agenten, der Code ausführt. Die Veröffentlichung im Internet gibt jedem, der die Adresse findet, einen Remote-Zugriff auf einen Prozess, der Befehle ausführt. Binden Sie den Dienst an Loopback, wie im obigen Befehl gezeigt, und greifen Sie über einen SSH-Tunnel von Ihrem Laptop darauf zu:

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

Öffnen Sie dann http://127.0.0.1:3000 auf Ihrem eigenen Rechner. Der Datenverkehr läuft über Ihre bestehende SSH-Sitzung; es lauscht nichts Neues im öffentlichen Internet. Für ein dauerhafteres Setup nutzen Sie stattdessen ein VPN. In jedem Fall sollten Sie eine Firewall mit einer Default-Deny-Regel vor den Server schalten, damit nichts versehentlich exponiert wird. Denken Sie daran, dass eine Firewall, die nur IPv4 abdeckt, denselben Port auch unter IPv6 offen lässt. Dies ist die IPv6-Firewall-Lücke, die viele Nutzer scheitern lässt.

Model-Keys und Repository-Credentials isolieren

OpenHands benötigt einen API-Key für das Modell und oft ein Token, um Repositories zu klonen und zu pushen. Beide können Kosten verursachen und als Sie agieren, daher behandeln Sie sie wie Passwörter. Speichern Sie diese in einer Environment-Datei, auf die nur das richtige Konto zugreifen kann. Speichern Sie sie niemals im Ausführungsbefehl, da sie sonst in Ihrer Shell-Historie und der Prozessliste landen, und niemals in einer Datei innerhalb eines Git-Repositorys.

Auf einem Server ausführen, den man opfern kann

Da der Controller den Docker-Socket halten muss, können Sie OpenHands nicht vollständig von seinem Host isolieren. Die einzige wirksame Gegenmaßnahme ist die Isolation durch Platzierung: Betreiben Sie OpenHands auf einem dedizierten VPS, der keine weiteren wichtigen Daten enthält. Nutzen Sie nicht den Server, auf dem auch Ihre Datenbank oder Ihre Website läuft. Erstellen Sie einen Snapshot, bevor Sie beginnen, und bauen Sie das System aus diesem Snapshot wieder auf, anstatt einem Server zu vertrauen, auf dem eine Woche lang agenten-generierter Code gelaufen ist. Ein günstiger, wegwerfbarer VPS mit nur einem Zweck ist der richtige Einsatzort.

Den Server absichern

Der Rest entspricht der Standard-Server-Hygiene. Dies ist hier wichtiger als üblich, da die Arbeitslast riskanter ist als gewöhnlich. Erstellen Sie einen unprivilegierten Admin-User, anstatt als Root zu arbeiten; folgen Sie dazu der Ausführung von Diensten als unprivilegierter Benutzer. Stellen Sie die SSH-Authentifizierung auf Key-only um. Führen Sie dann die folgende Checkliste aus und speichern Sie diese an einem Ort, an dem Sie sie wiedersehen.

Um die Funktionsweise zu verstehen, anstatt sie nur auszuführen, lesen Sie Building your own AI agent on a VPS. Für eine Plattform mit weniger Code-Aufwand ist Self-hosting Dify ein einfacherer Einstieg.

FAQ

Ist OpenHands sicher für den Betrieb auf einem Server?

Mit Vorsicht ist es möglich, aber es ist riskanter als eine gewöhnliche Web-App, da es Code schreibt und ausführt und der Controller den Host-Docker-Socket hält, was effektiv Root-Rechte auf der Maschine bedeutet. Betreiben Sie es auf einem dedizierten, wegwerfbaren VPS ohne andere wertvolle Daten, halten Sie die Web-UI über einen SSH-Tunnel oder ein VPN auf Loopback, isolieren Sie die Keys und sichern Sie den Server ab. Betreiben Sie es nicht neben Ihren wichtigen Diensten.

Warum benötigt OpenHands den Docker-Socket?

OpenHands führt jede Aufgabe in einem frischen Sandbox-Container aus. Es weist den Host-Docker-Daemon an, diese Container zu erstellen, indem es /var/run/docker.sock in den Controller mountet. Dies gibt dem Controller-Container die Kontrolle über Docker auf dem Host. Das ist leistungsstark, aber riskant, weshalb der Host selbst als ein System behandelt werden muss, auf dem nicht vertrauenswürdiger Code läuft.

Kann OpenHands ein lokales Modell anstelle einer kostenpflichtigen API verwenden?

Ja. OpenHands unterstützt lokale Modelle, die über Ollama oder vLLM bereitgestellt werden. Sie können es also vollständig selbst gehostet betreiben, ohne Token-Kosten und ohne dass Daten Ihren Server verlassen. Sie benötigen eine Maschine mit ausreichend Arbeitsspeicher für ein leistungsfähiges Coding-Modell; dies entspricht der Hardware-Anforderung aus dem Ollama-Leitfaden.

Sollte ich OpenHands auf meinem Hauptserver ausführen?

Nein. Da es agenten-generierten Code ausführt und den Docker-Socket hält, behalten Sie es auf einem separaten, zweckgebundenen VPS, den Sie bereit sind neu aufzusetzen. Die gemeinsame Nutzung mit einer Datenbank, einer Website oder anderen Diensten bedeutet, dass ein Fehler des Agenten oder ein Bug im System auf Ressourcen zugreifen kann, die es niemals berühren sollte.