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.
  • Mistral-API-Key, siehe separate Anleitung Mistral-Account und API-Key.

Architektur

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:

  1. WSL2 installieren und aktivieren. In der PowerShell als Administrator:
    wsl --install
  2. Windows neu starten.
  3. In der PowerShell Ubuntu in WSL installieren:
    wsl --install Ubuntu
    
  4. 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:

  1. Docker Desktop von docker.com herunterladen und zwar die Variante „… for Windows AMD64“.
  2. Installer ausführen. Optionen „All-users installation (Requires password)“ + Häkchen bei “Use WSL 2 instead of Hyper-V” (Standard).
  3. Nach Fertigstellung der Installation wird man zum Neustart von Windows aufgefordert. ```
  4. Danach Docker Desktop starten (Startmenü oder Desktop-Verknüpung). Nutzugsbedingungen akzeptieren; Anmeldung mit Konto kann übersprungen werden (Skip rechts oben).
  5. Geduldig warten. Der erste Start benötigt sehr viel Zeit.
  6. 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 --version
docker 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 ~/agent
sudo setfacl -R -d -m u:10001:rwX ~/agent
sudo setfacl -R -m u:$(id -u):rwX ~/agent-openhands-state
sudo 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.

WSL/Ubuntu:

echo 'export MISTRAL_API_KEY="dein-key"' >> ~/.profile

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.

WSL/Ubuntu:

docker run -d --name agent-canvas --restart unless-stopped \
  -p 127.0.0.1:8000:8000 \
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
  -e SANDBOX_USER_ID=1000 \
  -e LLM_API_KEY="$MISTRAL_API_KEY" \
  -e LLM_MODEL="mistral/mistral-medium-3-5" \
  -e LLM_BASE_URL="https://api.mistral.ai/v1" \
  -v ~/agent-openhands-state:/home/openhands/.openhands \
  -v ~/agent:/projects \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/openhands/agent-canvas:sha-3500d9e-amd64

Die Anwendung läuft dann als Service im Hintergrund. Sie kann über Docker Desktop oder die folgenden Kommandos gestartet und gestoppt werden.

WSL/Ubuntu:

# OpenHands/Agent Canvas starten…
docker start agent-canvas
 
# … und stoppen.
docker stop agent-canvas

Erster Start und Neustart

  • 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

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
  -e SANDBOX_USER_ID=1000 \
  -e LLM_API_KEY="$MISTRAL_API_KEY" \
  -e LLM_MODEL="mistral/mistral-medium-3-5" \
  -e LLM_BASE_URL="https://api.mistral.ai/v1" \
  -v ~/agent-openhands-state:/home/openhands/.openhands \
  -v ~/agent:/projects \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/openhands/agent-canvas:sha-3500d9e-amd64

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)

  1. Im Browser das erste das Web-Interface von Agent Canvas aufrufen: http://localhost:8000 Info: hier nur http://, also ausnahmsweise ohne das übliche s.
  2. Abfragedialog “Einen Backend hinzufügen” über den Link “Vorerst überspringen” ganz unten auslassen.
  3. In der Abfrage “Help improve OpenHands” das Häkchen rausnehmen und bestätigen klicken, um die anonyme Übermittlung von Nutzungsdaten abzulehnen.
  4. “Getting Started” zuklappen.
  5. Mistral als Modell-Anbieter hinzufügen: Einstellungen öffnen (Zahnrad links unten) > LLM > Provider Connections > Add connection und wie folgt ausfüllen: 427
  6. 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. 461

Schritt 5: Erste Chat-Session und Dateiaustausch testen

  1. Im Webinterface http://localhost:8000 linke Spalte, oben auf + New Chat.
  2. 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 *522
  3. 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.```
  4. 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.
  5. 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>

Updaten der Anwendung

# Updaten = neues Docker-Container-Image herunterladen
docker pull ghcr.io/openhands/agent-canvas:latest

Persistenz

  • = Fortbestand über Neustarten von Anwenung oder Laptop hinweg.
  • Dafür liegt der Chatverlauf und Session-Zustand in ~/agent-openhands-state, die gemeinsam bearbeiteten Dateien in ~/agent-

Approval-Policy

  • Im Webinterface unter TODOA Klickpfad hier einfügen.

Weiterführendes

Typische Fehler und Lösungen

ProblemUrsache / Lösung
Web-UI nicht erreichbarPort-Binding prüfen: nur 127.0.0.1:8000:8000 verwenden, Browser auf localhost
Sandboxes starten nicht / “docker.sock” FehlerWSL-Integration von Docker Desktop nicht aktiviert (Schritt 1.2), oder Socket-Mount fehlt
401 von Mistral APIKey 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 nichtSandbox-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-MountBekannter 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/PasswortFirst-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