Programmieren mit OpenHands: Installation, Voraussetzungen und Tipps

IRC-Mania Die Seite rund um Sicherheit und Programmierung

Internet, Sicherheit , Internet Relay Chat

Gesponsert

Ausgangslage

Als Anwendungsentwickler nutze ich KI-Coding-Tools täglich, von CLI-Agenten wie Claude Code bis zu IDE-Integrationen. Ein Tool fällt dabei aus der Reihe: OpenHands (früher OpenDevin). Es ist kein Autocomplete-Assistent, sondern ein autonomer Software-Agent mit eigener Web-Oberfläche, der in einer isolierten Sandbox Code schreibt, Tests ausführt, im Browser recherchiert und ganze Tickets abarbeitet.

Der entscheidende Unterschied zu Cursor oder Windsurf: OpenHands läuft nicht in Deiner IDE, sondern in einem Docker-Container mit eigenem Terminal, Editor und Browser. Du gibst eine Aufgabe, der Agent plant und führt sie selbstständig aus. Das ist näher an einem Junior-Entwickler im Team als an einem Plugin.

In diesem Artikel zeige ich Dir, wie Du OpenHands installierst, was Du vorher brauchst und welche Tipps mir in der Praxis am meisten gebracht haben. Wer den Hintergrund zu dieser Tool-Kategorie sucht, findet ihn in meinem Artikel zu Vibecoding und den Best Practices für Agenten-Orchestrierung.

OpenHands in a Nutshell

OpenHands ist ein Open-Source-Projekt von All Hands AI (MIT-Lizenz), das einen agentenbasierten Entwicklungsworkflow bereitstellt. Du beschreibst eine Aufgabe in natürlicher Sprache, „behebe den Fehler im Login-Flow” oder „baue eine REST-API mit FastAPI”, und der Agent arbeitet sie in einer Sandbox ab:

• Terminal: führt Befehle aus, installiert Dependencies, startet Tests
• Code-Editor: erstellt und bearbeitet Dateien
• Browser: recherchiert Dokumentation und prüft laufende Apps
• Git-Integration: erstellt Branches, Commits und Pull Requests

Der Standard-Agent heißt CodeActAgent und kommuniziert über Aktionen (Befehl ausführen, Datei schreiben, browsen) statt nur Text zu generieren. Das macht ihn deutlich handlungsfähiger als reine Chat-Tools, aber auch komplexer im Setup.

Voraussetzungen

Bevor Du startest, brauchst Du:

• Docker: das wichtigste Requirement. OpenHands führt den Agenten in eigenen Sandbox-Containern aus und braucht Zugriff auf /var/run/docker.sock. Wer Docker noch nicht kennt: mein Artikel zu Docker-Container-Grundlagen deckt Installation und Basics ab.
• LLM-API-Key: OpenHands ist model-agnostisch und spricht über LiteLLM mit Dutzenden Providern. Empfohlen werden Anthropic Claude (z.B. anthropic/claude-sonnet-4-5), aber auch OpenAI, Gemini oder Mistral funktionieren.
• RAM: realistisch mindestens 8 GB freier Speicher. OpenHands startet neben dem Haupt-Container einen Sandbox-Container pro Session, dazu kommt Deine IDE und Docker selbst.
• Internet-Zugang: beim ersten Start werden mehrere GB an Images gezogen (App-Image plus Agent-Server/Runtime-Image).
• Optional: lokales Modell: via Ollama oder LM Studio möglich, aber die Ergebnisse mit kleinen lokalen Modellen sind beim agentischen Coding spürbar schwächer. Mehr dazu im Abschnitt zu lokalen LLMs.

Installation

Schritt 1: Docker prüfen

docker version
docker info | grep -i "server version"

Wenn beide Befehle eine Version ausgeben, ist Docker bereit. Unter Linux muss Dein User in der docker-Gruppe sein, sonst scheitert der Socket-Zugriff später.

Schritt 2: OpenHands starten (Web-UI)

Der offizielle Startbefehl sieht so aus:

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 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8

Die wichtigsten Teile:

• docker.sock-Mount: der Agent braucht Docker-Zugriff, um seine Sandbox-Container zu starten
• ~/.openhands: persistenter Ordner für Einstellungen, Secrets und Conversations
• -p 3000:3000: die Web-UI läuft danach unter http://localhost:3000
• AGENT_SERVER_IMAGE_TAG: das Runtime-Image für die Sandbox; Tag und App-Version müssen zusammenpassen, also immer die aktuelle Doku prüfen
• --pull=always: zieht automatisch die aktuelle Version

Für eine bestimmte Version ersetzt Du den Tag (z.B. openhands:0.9 für den letzten 0.9.x-Stand), für Entwicklungszwecke gibt es main, instabil, nur zum Testen.

Schritt 3: LLM konfigurieren

Beim ersten Start landest Du in den Settings. Dort trägst Du Provider und Key ein:

• LLM Model: anthropic/claude-sonnet-4-5 (oder openai/gpt-4o, gemini/gemini-2.5-pro, …)
• API Key: Dein Provider-Key
• Base URL: nur nötig für Proxys oder lokale Server

Alternativ legst Du die Konfiguration direkt in ~/.openhands/settings.json ab, praktisch für Versionierung oder automatisierte Setups.

Schritt 4: Projekt-Workspace einbinden

Damit der Agent in Deinem lokalen Projekt arbeiten kann, mountest Du das Verzeichnis über SANDBOX_VOLUMES:

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 SANDBOX_USER_ID=$(id -u) \
  -e SANDBOX_VOLUMES=/pfad/zu/deinem/projekt:/workspace:rw \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8

Zwei Details sind hier wichtig:

• SANDBOX_USER_ID=$(id -u): sorgt dafür, dass der Agent Dateien mit Deiner User-ID anlegt. Ohne diese Variable gehören alle generierten Dateien root, ein Klassiker für Berechtigungs-Chaos im gemounteten Ordner.
• :rw: Read-Write-Mount, damit der Agent committen kann. Für reine Analyse reicht auch :ro.

CLI-Modus (Headless)

Neben der Web-UI gibt es einen CLI-Modus, gut für Remote-Sessions, CI oder Terminal-Puristen:

pip install uv
uv tool install openhands --python 3.12
openhands

Vorher muss ~/.openhands/settings.json mit der LLM-Konfiguration existieren, sonst startet die CLI nicht sauber. Der Docker-Ansatz für die CLI erwartet SANDBOX_VOLUMES und SANDBOX_USER_ID wie oben, die CLI läuft dann vollständig im Container.

Tipps aus der Praxis

1. Aufgaben klein schneiden

„Baue mir eine komplette Web-App” endet fast immer im Token-Friedhof. Besser: „Erstelle die FastAPI-Grundstruktur mit Health-Endpoint”, dann iterieren. Der Agent verliert bei riesigen Scopes den Überblick und produziert Duplikate, genau wie beim Vibecoding beschrieben.

2. repo.md als Projekt-Gedächtnis

OpenHands liest automatisch .openhands/microagents/repo.md im Workspace, vergleichbar mit CLAUDE.md bei Claude Code. Dort gehören rein:

• Build- und Test-Befehle (npm test, pytest -x)
• Code-Konventionen (Linting, Naming, Ordnerstruktur)
• Was der Agent NICHT tun soll (z.B. „keine Dependencies ohne Nachfrage hinzufügen”)

Eine gute repo.md halbiert gefühlt die falschen Starts.

3. Stärke der Modelle realistisch einschätzen

Die Wahl des Modells macht bei agentischem Coding mehr aus als bei jeder IDE-Integration:

• Claude Sonnet/Opus: beste Ergebnisse bei komplexen Refactorings und Multi-File-Änderungen
• GPT-4o / GPT-5: solide Allrounder, schnell
• Lokale Modelle (Ollama): funktionieren technisch über ollama/<modell> als Provider, aber bei autonomen Multi-Step-Tasks brechen sie häufiger ab oder verlieren den Kontext. Für ernsthafte Arbeit rate ich ab; als Experiment ok.

4. Kosten im Blick behalten

Ein Agent, der selbstständig arbeitet, verbraucht deutlich mehr Tokens als ein Chat: Jede Terminal-Ausgabe, jede gelesene Datei, jede Browser-Aktion landet im Kontext. Eine mittelgroße Aufgabe kommt schnell auf mehrere hunderttausend Tokens. Meine Faustregel:

• Kleine, klar umrissene Tasks: wenige Cents bis ca. 1 Dollar
• Feature-Implementierung mit Tests: 2 bis 10 Dollar je nach Modell
• Immer das Provider-Dashboard offen haben, besonders bei den ersten Sessions

5. Sandbox bedeutet nicht risikofrei

Der docker.sock-Mount gibt dem Agenten faktisch Root-Zugriff auf Dein Docker, das ist bewusst so designt, aber Du solltest es wissen. Konsequenzen:

• Keine Secrets in Umgebungsvariablen, die der Agent nicht braucht
• SANDBOX_VOLUMES nur auf das Projektverzeichnis setzen, nie auf $HOME
• Bei Prompts von außen (z.B. GitHub-Issue-Resolver auf fremden Repos): Vorsicht vor Prompt-Injection: ein bösartiger Issue-Text kann den Agenten zu ungewollten Aktionen bewegen
• Generierten Code trotz Sandbox reviewen: der Artikel zu KI-Programmierung Best Practices geht tiefer auf dieses Thema ein

6. Git nutzen als Sicherheitsnetz

Ich lasse OpenHands immer auf einem eigenen Branch arbeiten (git checkout -b openhands/feature-x). Wenn der Agent Unsinn baut, ist der Weg zurück ein git reset --hard, und Du kannst den Diff sauber reviewen, bevor etwas in main landet.

7. Browser-Preview nutzen

In der Web-UI siehst Du live, was der Agent tut: Terminal-Output, Dateiänderungen, Browser-Aktivität. Nicht nur unterhaltsam, wenn er in eine falsche Richtung läuft, kannst Du früh eingreifen und korrigieren statt Tokens zu verbrennen.

Häufige Fehler

• Problem: Cannot connect to the Docker daemon beim Start. Lösung: Docker läuft nicht oder der User ist nicht in der docker-Gruppe (sudo usermod -aG docker $USER, dann neu einloggen). Unter macOS muss Docker Desktop laufen.

• Problem: Generierte Dateien im Workspace gehören root. Lösung: -e SANDBOX_USER_ID=$(id -u) setzen (siehe Schritt 4).

• Problem: Agent startet, aber der Sandbox-Container schlägt fehl. Lösung: Der AGENT_SERVER_IMAGE_TAG passt nicht zur App-Version, beide Werte gemeinsam aus der aktuellen Doku übernehmen.

• Problem: ~/.openhands wird im Container nicht gefunden. Lösung: Beim CLI-Docker-Start heißt der Mount -v ~/.openhands:/root/.openhands, der Pfad im Container unterscheidet sich je nach Image-User.

• Problem: Lokales Modell via Ollama liefert nur Fehler oder Abbrüche. Lösung: Base-URL auf host.docker.internal setzen (dafür ist der --add-host-Flag da), Modellname mit ollama/-Prefix, und Erwartungen senken, siehe Tipp 3.

• Problem: Der Agent editiert außerhalb des Workspaces. Lösung: Prompt explizit machen („arbeite nur in /workspace”) und SANDBOX_VOLUMES eng fassen.

Fazit

OpenHands ist das spannendste Open-Source-Projekt im AI-Coding-Bereich, weil es zeigt, wohin die Reise geht: weg vom Code-Vorschlag, hin zum autonomen Agenten mit eigener Umgebung. Die Installation ist mit Docker in fünf Minuten erledigt, die Kunst liegt danach: kleine Tasks, gute repo.md, passendes Modell, Budget im Blick.

• Docker-Pflicht: ohne laufenden Docker-Daemon geht nichts
• LLM-Key entscheidet: Qualität und Kosten hängen komplett am Provider
• Sandbox ≠ Bedenkenlos: docker.sock-Mount verstehen und Volumes eng fassen
• Klein denken: Tickets für den Agenten schreiben wie für einen Junior-Kollegen

FAQ: OpenHands

Quellen und weiterführende Links

• OpenHands auf GitHub
• OpenHands Dokumentation
• OpenHands Website (All Hands AI)
• OpenHands Cloud

Premium VPS Hosting

Schnelle und sichere VPS Server

Gesponsert