Anleitung: OpenHands/Agent Canvas auf Windows (Laptop, PC)
Ziel: OpenHands/Agent Canvas auf Windows als lokalen KI-Agenten mit LLMs (= große Sparchmodelle) von Mistral installieren und konfigurieren. OpenHands/Agent Canvas wird dabei einem sogenannten Docker-Container installiert. Dadurch läuft es isoliert von Windows und hat dadurch keinen Zugriff auf die eigenen Dateien. Um dies Umzusetzen wird Docker Desktop und WSL2 installiert.
Was ist OpenHands (und was nicht)?
OpenHands (früher OpenDevin, inzwischen als “Agent Canvas” für den lokalen Einstieg beworben) ist ein quelloffenes sogen. Framework für autonome „KI-Agenten“, d.h. ein System oder ein Bausatz aus mehreren Komponenten, das im Einsatzweck prinzipiell offen angelegt ist. Entwickelt wird es eigentlich für Programmierung („Coding“), kann aber auch direkt für andere Aufgaben eingesetzt werden. Komponenten des Systems:
Web-Interface für Chats mit mehreren parallelen Agenten-Sessions.
Pro Session ein eigener Sandbox-Container, d.h. isoliertes Dateisystem, eigene Ausführungsumgebung (Shell).
Freigabe-System (Approval-Gates): riskante Aktionen (destruktive Befehle, Zugriff auf Passwörter und andere Geheimnisse) sollen pausiert werden und warten dann auf Bestätigung
Freie Modell-Auswahl (Model-agnostisch, mittels LiteLLM): es können große Sprachmodelle und andere KI-Dienste von vielen verschiedenen Anbietern direkt genutzt werden. Dieser Anleitung fokussiert sich auf die Modelle von Mistral (Anbieter aus und mit Rechenzentren in Europa, also dem Anwendungsbereich der DSGVO).
Abgrenzung
OpenHands bringt seine eigene Agenten-Logik mit. Der Agent darin ist nicht das von Mistral selbst angebotene Produkt „Vibe“ oder „Le Chat“. Nur das Modell/LLM dahinter ist von Mistral.
Voraussetzungen
WICHTIG
Eine ausführliche Liste mit Anleitung zum Prüfen der Voraussetzungen finden Sie hier, bitte vorher aufmerksam durchlesen: Anleitung Voraussetzungen überprüfen.
Gerät/Windows muss während Installation neu gestartet werden.
Windows 11 (alle Editionen außer S-Mode). Funktioniert vermutlich auch mit Windows 10 64-bit (Vorsicht: Für Windows 10 bereits jetzt oder demnächst keine Updates mehr; siehe Abschnitt „Windows-Version” unten).
Virtualisierung im BIOS/UEFI aktiviert (Intel VT-x oder AMD-V)
Mindestens 8 GB RAM, empfohlen 16 GB (es kommt Docker Desktop + WSL2 + OpenHands-Sandbox zum Einsatz)
TODOA Wie viel Speicherplatz benötigt die Installation
Administratorrechte für die Installation (einmalig, für die Installation)
Internetverbindung mit etwas Bandbreite für die Downloads.
flowchart TB
A[Browser: OpenHands Web-Interface] -->|HTTP/WebSocket| B[OpenHands App-Server / Agent Canvas]
B <-->|LiteLLM| C((Mistral API<br/>api.mistral.ai))
B <-->|Docker Socket| D[Sandbox-Runtime-Container<br/>eine pro Session]
D -->|Bind Mount| E[WSL: ~/agent]
E <-->|\\wsl$| F[Windows Explorer]
TODOA Im Mermaid-Diagramm “Web-Interface” und “App-Server” bitte fett!
Der App-Server hält den API-Key (in einer Env-Variable) und spricht Mistral direkt an. Der Key gelangt nie in die Sandbox-Container.
Pro Chat/Session startet der App-Server einen isolierten Runtime-Container, in dem der Agent Dateien bearbeitet und Befehle ausführt.
Dein Ordner ~/agent wird in jede Sandbox als /projects gemountet: der Agent arbeitet direkt auf deinen Dateien, du siehst Änderungen live unter \\wsl$\….
Schritt 1: WSL und Docker Desktop installieren
Falls Docker bereits läuft, weiter bei Schritt 2.
Docker Desktop benötigt WSL2. WSL steht für „Windos Subsystem for Linux“. Mit diesem System von Microsoft kann man innerhalb von Windows virtuell als weiteres Betriebssystem Linux laufen lassen. In dieser Anleitung nutzen wir Linux-Variante Ubuntu.
Deshalb installieren und konfigurieren wir zuerst WSL:
WSL2 installieren und aktivieren. In der PowerShell als Administrator:
wsl --install
Windows neu starten.
In der PowerShell Ubuntu in WSL installieren:
wsl --install Ubuntu
Dabei wird auch Benutzername + Passwort für Ubuntu abgefragt, also die Ausgabe des Kommandos beachten. Außerdem muss man wählen, ob man Statistiken über die Nutzungsdaten übermitteln will.
Nach erfolgreicher Installation lander man direkt in der Kommandozeile des installierten Ubuntu. Das sieht dann ungefähr so aus:
Weiter zu Docker Desktop:
Docker Desktop von docker.com herunterladen und zwar die Variante „… for Windows AMD64“.
Installer ausführen. Optionen „All-users installation (Requires password)“ + Häkchen bei “Use WSL 2 instead of Hyper-V” (Standard).
Nach Fertigstellung der Installation wird man zum Neustart von Windows aufgefordert. ```
Danach Docker Desktop starten (Startmenü oder Desktop-Verknüpung). Nutzugsbedingungen akzeptieren; Anmeldung mit Konto kann übersprungen werden (Skip rechts oben).
Geduldig warten. Der erste Start benötigt sehr viel Zeit.
Unter Settings (Zahnrad in der oberen Leiste) → Resources → WSL Integration folgende Einstellungen vornehmen:
“Enable integration with my default WSL distro” aktivieren.
Deine Ubuntu-Distribution explizit einschalten.
Bestätigten mit „Apply & Restart“.
Optional Docker Insallation prüfen:
Dazu die folgenden zwei Kommandos in der PowerShell ausführen:
docker --version
→ Zeigt nur die aktuell installierte Version von Docker an.
docker --versiondocker run --rm hello-world
→ Lädt einen kleinen Docker-Container herunter, der dann gestartet wird und nur einen Ausgabetext produziert. Danach wird er direkt wieder gelöscht.
Docker Desktop startet nicht automatisch
Nach jedem Reboot muss Docker Desktop bewusst gestartet werden (Startmenü → Docker Desktop), bevor OpenHands läuft. Die WSL-Docker-Engine wird erst mit Docker Desktop aktiv. Ggf. prüfen, ob die Engine gestartet ist: Docker-Desktop-Symbol in der Taskleiste (grün/„Engine running”) oder docker version in der WSL-Shell ausführen.
Schritt 2: Arbeitsumgebung vorbereiten (Ordner; API key)
Für die Arbeit mit dem OpenHands-KI-Agenten nutzen wir zwei Ordner:
Der Ordner agent dient dazu mit dem KI-Agenten Dateien auszutauschen.
Der Ordner agent-openhands-state enthält Konfiguration und weiter Informationen zum OpenHands-System. Bekommt für den Zugriff für das OpenHands-System einen anderen Besitzer (uid=10001).
Kommandozeile von WSL/Ubuntu nutzen
Für die meisten der folgenden Kommandos wird die Ubuntu-Kommandozeile genutzt. Um diese Kommandozeile zu bekommen WSL über das Startmenü starten.
WSL/Ubuntu:
# Ordner für Dateiaustausch und Konfigurationen/System-Informationen anlegen:mkdir -p ~/agent ~/agent-openhands-state# Besitzer: agent-openhands-state gehört dem Container-Benutzer (uid 10001),# ~/agent bleibt beim eigenen WSL-Nutzer:sudo chown -R 10001:10001 ~/agent-openhands-state# Gegenseitige Lese-/Schreibrechte per ACL festlegen — einmalig, gilt auch# für alle künftigen Dateien (Default-ACL ersetzt die umask des Agenten):sudo setfacl -R -m u:10001:rwX ~/agentsudo setfacl -R -d -m u:10001:rwX ~/agentsudo setfacl -R -m u:$(id -u):rwX ~/agent-openhands-statesudo setfacl -R -d -m u:$(id -u):rwX ~/agent-openhands-state
Damit der API key nicht bei jedem Start eingegeben werden muss, wird er mit folgendem Kommando sicher in der Datei .profile abgelegt. Diese Datei liegt im Nutzer-Verzeichnis des Ubuntu-Nutzers und natürlich nicht im Agent-Ordner.
Auf die oben angelegten Ordner kann man über den Windows-Datei-Explorer zugreifen. Dazu im Explorer in der linken Spalte auf Linux und dann durch die Ordner Ubuntu > home > Linux-Benutzername klicken.
Hier findet sich übrigens auch die Datei .profile, die man einfach mit dem Text-Editor öffnen kann. In der letzten Zeile findet sich der API key.
Schritt 3: OpenHands/Agent Canvas installieren
OpenHands/Agent Canvas ist die in dieser Anleitung vorgestellt Variante und der empfohlene Einstieg. Mit den folgenden Kommandos wird das offizielle Agent-Canvas-Image heruntergeladen und in Docker gestartet.
Beim ersten Start wird das Image geladen (ca. 1–2 GB) — das kann einige Minuten dauern.
Nach dem Start dauert es etwa eine Minute, bis die UI antwortet (der Root-Pfad / leitet auf /canvas/ weiter)
TODOS Erklärung Wechsel von :sha-3500d9e-amd64 zu latest.
Variante: Wer besonders experimentierfreudig ist oder vorsichtig sein möchte, kann auch erstmal mir folgendem Kommando beginnen. Das --rm räumt den Docker-Container mit Agent Canvas nach dem Stopp automatisch wieder weg. Dadurch gehen aber auch alle
Erläuterungen zu bestimmten Parametern aus der langen Liste (mehrere Zeilen) hinter dem Befehl docker run:
-p 127.0.0.1:8000:8000 bindet das Webinterface nur an den lokalen Rechner (loopback); damit ist das Web-Intreface bzw. der KI-Agent von anderen Rechnern prinzipiell nicht erreichbar. Deshalb können wir auch die Option/Umgebungsvariable AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true setzen, durch die der Agent ohne diesen “session key” aufgerufen werden kann. Variante auf eigene Gefahr: Will man das nicht (und z.B. das Web-Interface im eigenen Heimischen Netzwerk (LAN) verfügbar machen, stellt man diese Option auf false und findet in dieser Datei den Schlüssel für die Anmeldung agent-openhands-state/agent-canvas/api-key.txt (wird beim ersten Start generiert).
-e SANDBOX_USER_ID=1000 lässt die einzelnen Sessions (Sandboxes) als normaler Nutzer (non-root) laufen.
Der Mount ~/agent:/projects ist die Verknüfung des Austauschordners agent mit dem Ordner /projects in den Docker-Containern, die für jede Chat-Session gestartet werden.
Falls die UI beim ersten Start einen generierten API-Key verlangt (lokaler Modus): auslesen mit
docker exec agent-canvas sh -c 'cat "$STATE_DIR/api-key.txt"'
Schritt 4: Erster Aufruf und Konfiguration Modelle (Mistral)
Im Browser das erste das Web-Interface von Agent Canvas aufrufen:
http://localhost:8000Info: hier nur http://, also ausnahmsweise ohne das übliche s.
Abfragedialog “Einen Backend hinzufügen” über den Link “Vorerst überspringen” ganz unten auslassen.
In der Abfrage “Help improve OpenHands” das Häkchen rausnehmen und bestätigen klicken, um die anonyme Übermittlung von Nutzungsdaten abzulehnen.
“Getting Started” zuklappen.
Mistral als Modell-Anbieter hinzufügen: Einstellungen öffnen (Zahnrad links unten) > LLM > Provider Connections > Add connection und wie folgt ausfüllen:
Modelle hinzufügen: … > Available Profiles > Add from provider connections > Provider, Mistral auswählen und dann z.B. folgende drei Modelle (drei verschiedene Größenordnungen) > Add 3 profiles.
ministral-8b-latest
mistral-medium-latest
zai-glm-latest → Achtung: scheint aktuell leider nur bei einem Abo verfügbar.
Schritt 5: Erste Chat-Session und Dateiaustausch testen
Arbeitsverzeichnis (Dateiordner) auswählen: direkt unter dem Chateingabe-Fenster links auf Open Workspace > in der Auswahl + Add new Workspace > in der linken Spalte Ordner /projects auswählen > *Add this directory *
Eine erste Anfrage oder Aufgabe stellen, z.B.:
Schreibe mir ein kurzes Gedicht zum Herbstanfang in Bad Urach auf der Schwäbischen Alb. Lege es in alb-gedicht.txt ab.```
Es wird ein neuer Container für die Chat-Session gestartet. Der Chat bekommt einen neuen Tab/Reiter in der linken Spalte und nach einer kurzen Weile auch automatisch einen Titel.
Nach Lust und Laune weiter mit dem KI-Agenten chatten. Und bei Gelegenheit auch unter Windows im Explorer das Ergebnis im Ordner \\wsl$\Ubuntu\home\<user>\agent prüfen (siehe auch weiter oben).
Dateirechte der Agent-Dateien
Dateien, die der Agent anlegt, gehören dem Container-Benutzer openhands (uid 10001) mit restriktiven Rechten (0600) — der eigene WSL-Benutzer kann sie nicht ohne Weiteres lesen, und der \\wsl$-Zugriff aus dem Windows-Explorer ebenso wenig. Abhilfe: in der WSL-Shell sudo chown $(id -u):$(id -g) ~/agent/outgoing/zusammenfassung.md oder sudo chmod a+r — oder die Datei über die OpenHands-UI (File-Ansicht der Conversation) direkt lesen.
Mehrere Sessions parallel
Man kann nun einfach weitere Konversationen bzw. Chat-Sessions starten. Jede bekommt ihren eigenen Container, verbrauchen damit etwas Systemressourcen (v.a. Arbeitsspeicher). Alle teilen sich aber denselben Arbeitsordner in ~/agent.
Kollisionsgefahr durch gemeinsamen Ordner
Wenn mehrere parallele Sessions an den gleichen Dateien im ~/agent-Ordner arbeiten, können sich Agenten gegenseitig Dateien überschreiben. Deshalb für unterschiedliche Projekte/Aufgaben am besten einen eigenen Unterordner verwenden (z.B. ~/agent/projekt-kekse, ~/agent/geburtstagsplanung). Wenn man mehrere Sessions an einem Projekt = Ordner arbeiten lässt, sollte man die schreibenden Dateizugriffe koordinieren.
Schritt 6: Betrieb, Updates, Persistenz
Anwendung = Docker-Container stoppen: Entweder über die grafische Oberfläche in Docker Desktop oder in WSL/Ubuntu:
# Container stoppen (bei --rm ist er danach weg, Zustand bleibt in den Mounts)docker stop <container>
Port-Binding prüfen: nur 127.0.0.1:8000:8000 verwenden, Browser auf localhost
Sandboxes starten nicht / “docker.sock” Fehler
WSL-Integration von Docker Desktop nicht aktiviert (Schritt 1.2), oder Socket-Mount fehlt
401 von Mistral API
Key falsch/abgelaufen – LLM_API_KEY prüfen, nie mit führendem/trailingem Leerzeichen
UI läuft, aber jede Conversation schlägt sofort fehl (Auth-Fehler)
LLM_API_KEY war beim docker run leer (Variable nicht gesetzt/geexpandiert). Prüfen: docker exec <container> sh -c 'echo -n "$LLM_API_KEY" | wc -c' → muss > 0 sein; sonst Container mit gesetztem Key neu starten
Agent-Dateien lassen sich nicht öffnen („Permission denied”)
Dateien gehören uid 10001 mit 0600 – sudo chown/chmod in der WSL-Shell, s. Schritt 5
Agent sieht Dateien nicht
Sandbox-Mount fehlt (-v ~/agent:/projects), oder falscher Pfad im Prompt (/projects/... statt Windows-Pfad)
Sehr langsames Dateisystem
\\wsl$-Zugriff von Windows ist träge – große Dateien besser direkt in WSL ablegen
Sicherheitsbedenken bei docker.sock-Mount
Bekannter Trade-off: der App-Server darf Container spawnen. Loopback-Binding + keine Port-Weiterleitung nach außen minimiert das Risiko
Ubuntu-Fenster zeigt nur das Logo und fragt nie nach Name/Passwort
First-Run-Assistent (OOBE) hängt. Workaround: PowerShell wsl -d Ubuntu -u root -- useradd -m -s /bin/bash -G sudo BENUTZERNAME, dann Passwort setzen (echo 'BENUTZERNAME:PASSWORT' | wsl -d Ubuntu -u root -- chpasswd), dann /etc/wsl.conf um [user] + default=BENUTZERNAME ergänzen und wsl --shutdown — danach startet wsl direkt als dieser Benutzer. Vorher beachten: wenn wsl-Befehle blockieren oder wsl --shutdown hängt, erst die Ubuntu-Konsole schließen und Windows neu starten
Bei Problemen das Vorliegen des API Keys prüfen
LLM_API_KEY="$MISTRAL_API_KEY" funktioniert im nächsten Schritt nur, wenn die Umgebungsvariable in dieser WSL-Shell wirklich gesetzt ist (siehe Schritt 2 oben). Wird der Container mit leerem Key gestartet, läuft das Webinterface zwar normal, aber jede Conversation schlägt sofort mit einem Authentifizierungsfehler fehl. In WSL daher verifizieren:
docker exec <container-name> sh -c 'echo -n "$LLM_API_KEY" | wc -c' # muss > 0 sein