OpenHands auf einem VPS selbst hosten mit Docker

Was OpenHands ist und welches Risiko Sie zuerst verstehen müssen

OpenHands, früher OpenDevin, ist ein autonomer Agent für Softwareentwicklung. Sie geben ihm eine Aufgabe in Alltagssprache, und er plant die Arbeit, schreibt Code, führt Befehle aus, liest die Ausgabe und wiederholt diese Schritte, bis die Aufgabe erledigt ist. Sie betreiben ihn mit Docker auf Ihrem eigenen Server und verbinden ihn mit einem Sprachmodell. Auf einem VPS wird er zu einem Coding-Agenten, der arbeitet, während Sie nicht anwesend sind.

Ein Punkt sollte Ihre gesamte Einrichtung bestimmen. OpenHands schlägt nicht nur Code vor, sondern führt ihn auch aus. Dafür bindet der Controller-Container den Docker-Socket des Hosts unter /var/run/docker.sock ein, damit er für jede Aufgabe Sandbox-Container starten kann. Alles, was mit dem Docker-Socket kommunizieren kann, kann einen neuen Container starten, der das gesamte Dateisystem des Hosts einbindet. Der Zugriff auf den Socket entspricht daher faktisch root-Zugriff auf dem Rechner. Behandeln Sie den OpenHands-Server deshalb wie einen Server, auf dem nicht vertrauenswürdiger Code ausgeführt wird. Genau das geschieht dort. Alle folgenden Härtungsmaßnahmen ergeben sich daraus.

Was Sie benötigen

Sie benötigen einen VPS mit Ubuntu 24.04 und einer aktuellen Docker Engine, mindestens 4 GB RAM sowie einen API-Schlüssel für ein Sprachmodell (OpenAI, Anthropic oder Google) oder ein lokales Modell, das von Ollama auf demselben VPS bereitgestellt wird. OpenHands unterstützt Dutzende Modell-Backends, daher können Sie frei wählen. Wenn Sie bisher noch keine Container eingerichtet haben, vermitteln die Docker-Grundlagen auf einem VPS das für diese Anleitung vorausgesetzte Wissen.

Mit Docker installieren

OpenHands wird als zwei Images bereitgestellt: das Anwendungs-Image, das Sie ausführen, und ein Agent-Server-Image, das OpenHands abruft, um die Sandbox für jede Aufgabe auszuführen. Starten Sie es wie folgt. Ersetzen Sie die Tags durch die aktuellen 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 Anwendungs-Image und das Agent-Server-Image haben absichtlich unterschiedliche Versionsnummern. Versuchen Sie daher nicht, sie anzugleichen. Verwenden Sie den Agent-Server-Tag, den die Dokumentation Ihrer Anwendungsversion zuordnet. Beachten Sie außerdem -p 127.0.0.1:3000:3000 statt -p 3000:3000. Diese einzelne Änderung entscheidet darüber, ob nur Sie die Weboberfläche erreichen können oder ob sie aus dem gesamten Internet erreichbar ist. Darum geht es im nächsten Abschnitt.

Die Weboberfläche nicht im öffentlichen Internet bereitstellen

OpenHands stellt seine Oberfläche auf Port 3000 bereit. Diese Oberfläche steuert einen Agenten, der Code ausführt. Wenn Sie sie im Internet veröffentlichen, erhält jeder, der sie findet, einen entfernten Zugang zu einem Prozess, der Befehle ausführt. Binden Sie sie an die Loopback-Adresse, wie es der obige Startbefehl tut, und greifen Sie von Ihrem Laptop über einen SSH-Tunnel darauf zu:

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

Öffnen Sie anschließend http://127.0.0.1:3000 auf Ihrem eigenen Rechner. Der Datenverkehr läuft über Ihre bestehende SSH-Sitzung. Im öffentlichen Internet lauscht dadurch kein weiterer Dienst. Nicht jeder Agent benötigt überhaupt einen Port: Claude-Code-Sitzungen auf demselben VPS kommunizieren über das Terminal, sodass Sie ausschließlich SSH öffentlich erreichbar machen müssen. Diese Kombination aus Loopback-Bindung und Tunnel sollten Sie auch für jedes andere Agent-Dashboard verwenden, das Sie bereitstellen. Die Scan-Oberfläche von open-kritt über einen Tunnel zu erreichen funktioniert auf dieselbe Weise, allerdings über Port 5173. Für eine dauerhafte Einrichtung können Sie die Oberfläche stattdessen hinter einem VPN bereitstellen. Setzen Sie in beiden Fällen eine Firewall mit einer standardmäßigen Deny-Regel vor den Server, damit nichts versehentlich öffentlich erreichbar ist. Beachten Sie außerdem, dass eine Firewall, die nur IPv4 abdeckt, denselben Port über IPv6 offen lässt. Das ist die IPv6-Firewall-Lücke, die viele Benutzer übersehen.

Isolieren Sie den Modellschlüssel und alle Repository-Zugangsdaten

OpenHands benötigt einen API-Schlüssel für sein Modell und häufig ein Token, um Ihre Repositories zu klonen und Änderungen dorthin zu übertragen. Mit beiden können Kosten entstehen, und beide können in Ihrem Namen Aktionen ausführen. Behandeln Sie sie daher wie Passwörter. Bewahren Sie sie in einer Umgebungsdatei auf, die nur das richtige Konto lesen kann. Geben Sie sie niemals im Startbefehl an, da sie sonst in Ihrer Shell-Historie und in der Prozessliste erscheinen. Speichern Sie sie außerdem niemals in einer Datei innerhalb eines Git-Repositorys. Wenn Sie die Originale in einem selbst gehosteten Passwortmanager aufbewahren, sichern Sie auch diesen Server ab. Die Schwachstellen eines Tresors sind nicht die verschlüsselten Einträge selbst, sondern sein Admin-Token und seine Sicherungsdatei, wie der Leitfaden zur Absicherung von Vaultwarden erläutert.

Führen Sie es auf einem entbehrlichen System aus

Da der Controller Zugriff auf den Docker-Socket benötigt, können Sie OpenHands nicht vollständig von seinem Host isolieren. Die sinnvolle Gegenmaßnahme ist die Isolation durch die Platzierung: Betreiben Sie OpenHands auf einem dedizierten VPS, auf dem sich keine anderen wichtigen Daten oder Dienste befinden. Verwenden Sie nicht den Server, auf dem auch Ihre Datenbank oder Ihre Website läuft. Erstellen Sie vor dem Start einen Snapshot. Bauen Sie das System anschließend aus diesem Snapshot neu auf, statt einem System zu vertrauen, auf dem eine Woche lang vom Agenten erzeugter Code ausgeführt wurde. Ein günstiger, entbehrlicher VPS mit nur einem Zweck ist dafür die richtige Umgebung. Die Platzierung ist der einzige Stellhebel, den OpenHands Ihnen hier wirklich bietet. Wenn Sie außerdem festlegen möchten, wie viel der Agent ausführen darf, bevor er eine Bestätigung anfordert, zeigen die Berechtigungsmodi von Claude Code, wie dieser zweite Stellhebel auf einem Server aussieht, den niemand überwacht.

Den Server absichern

Die übrige Server-Hygiene ist Standard. Hier ist sie jedoch wichtiger als üblich, weil die Workload ein höheres Risiko darstellt. Erstellen Sie ein nicht privilegiertes Administratorkonto, statt als root zu arbeiten. Folgen Sie dazu der Anleitung Dienste als nicht privilegierter Benutzer ausführen. Stellen Sie SSH auf die ausschließliche Authentifizierung per Schlüssel um. Arbeiten Sie anschließend die folgende Checkliste durch und bewahren Sie sie an einer Stelle auf, an der Sie sie wiederfinden.

Wenn Sie die einzelnen Komponenten verstehen möchten, statt die Befehle nur auszuführen, lesen Sie Ihren eigenen AI-Agenten auf einem VPS erstellen. Für eine Plattform mit weniger Code bietet Dify selbst hosten einen leichteren Einstieg.

FAQ

Ist OpenHands sicher auf einem Server auszuführen?

Das ist bei sorgfältiger Konfiguration möglich. OpenHands ist jedoch riskanter als eine gewöhnliche Webanwendung, weil es Code schreibt und ausführt und sein Controller Zugriff auf den Docker-Socket des Hosts hat. Dieser Zugriff entspricht praktisch root auf dem System. Führen Sie OpenHands auf einem dedizierten, jederzeit ersetzbaren VPS aus, auf dem keine anderen wichtigen Daten liegen. Binden Sie die Weboberfläche nur an loopback und greifen Sie über einen SSH-Tunnel oder ein VPN darauf zu. Isolieren Sie die Schlüssel und härten Sie das System ab. Führen Sie OpenHands nicht neben wichtigen Diensten aus.

Warum benötigt OpenHands den Docker-Socket?

OpenHands führt jede Aufgabe in einem neuen Sandbox-Container aus. Dazu fordert es den Docker-Daemon des Hosts auf, diese Container zu erstellen, indem es /var/run/docker.sock in seinen Controller einbindet. Dadurch kann der Controller-Container Docker auf dem Host steuern. Das ist leistungsfähig und riskant. Der Host muss daher als System behandelt werden, auf dem nicht vertrauenswürdiger Code ausgeführt wird.

Kann OpenHands anstelle einer kostenpflichtigen API ein lokales Modell verwenden?

Ja. OpenHands unterstützt lokale Modelle, die von Ollama oder vLLM bereitgestellt werden. Dadurch können Sie OpenHands vollständig selbst betreiben, ohne Kosten pro Token und ohne dass Daten Ihren Server verlassen. Sie benötigen ein System mit ausreichend Arbeitsspeicher für ein leistungsfähiges Coding-Modell. Das ist dieselbe Dimensionierungsfrage, die im Ollama-Leitfaden behandelt wird.

Sollte ich OpenHands auf meinem Hauptserver ausführen?

Nein. OpenHands führt von einem Agenten erstellten Code aus und hat Zugriff auf den Docker-Socket. Betreiben Sie es daher auf einem separaten VPS mit nur einer Aufgabe, den Sie bei Bedarf neu aufsetzen können. Wenn Sie OpenHands zusammen mit einer Datenbank, einer Website oder anderen Diensten betreiben, kann ein Fehler des Agenten oder ein Bug in OpenHands auf Systeme zugreifen, die davon nicht betroffen sein sollten.