OpenHands Agent Canvas mit Docker und Ollama selbst betreiben

OpenHands ist ein quelloffener KI-Agent für Softwareentwicklung: Er liest Code, führt Befehle aus, schreibt Tests und ändert Dateien in einem Arbeitsordner. Die Oberfläche dafür heißt inzwischen Agent Canvas. Die aktuelle Dokumentation (V1) führt sie als Einstieg für den eigenen Betrieb, der Quellcode liegt im Hauptrepository OpenHands/OpenHands. Anders als die frühere Web-Oberfläche auf Port 3000 braucht das offizielle Docker-Image keinen Zugriff auf den Docker-Socket des Hosts: Canvas, Agent Server und Automation Server laufen gemeinsam in einem Container, der Agent sieht nur die Ordner, die Sie einbinden. Diese Anleitung betreibt Agent Canvas 1.34.0 per Docker Compose zusammen mit Ollama, sichert den Zugang ab und zeigt, worauf es bei lokalen Modellen ankommt.

Voraussetzungen

Agent Canvas selbst ist genügsam, das Sprachmodell nicht. Planen Sie beide Teile getrennt.

• Agent Canvas: 2 CPU-Kerne und 4 GB RAM für einen Nutzer (Herstellerangabe für VM-Betrieb), x86_64 oder ARM64. Im Test belegte der Container im Leerlauf etwa 840 MB RAM.
• Lokales Modell: Der Hersteller empfiehlt Qwen3.6-35B-A3B und nennt dafür eine aktuelle GPU mit mindestens 24 GB VRAM für quantisierte Varianten oder einen Mac mit Apple Silicon und 64 GB gemeinsamem Speicher. Kleinere Modelle laufen, erledigen Agentenaufgaben laut Doku aber oft nur eingeschränkt.
• GPU-Betrieb in Docker: NVIDIA-Treiber und NVIDIA Container Toolkit auf dem Host.
• Speicher: Die Images belegen entpackt rund 15 GB (Agent Canvas 5,6 GB, Ollama 9,3 GB), dazu die Modelldateien.
• System: Linux mit Docker Engine und Compose-Plugin v2.

Welche Modellgröße zu welcher Grafikkarte passt, erklärt Ollama-Modelle richtig auswählen.

Schritt 1: Arbeitsordner mit den richtigen Rechten anlegen

Der Container speichert Einstellungen, Geheimnisse und Gesprächsverläufe unter /home/openhands/.openhands und arbeitet in Projekten unter /projects. Er läuft als Benutzer openhands mit UID und GID 10001. Legen Sie die Ordner an und übergeben Sie sie dieser UID:

sudo mkdir -p /opt/agent-canvas/{openhands,projects}
sudo chown -R 10001:10001 /opt/agent-canvas/openhands /opt/agent-canvas/projects
cd /opt/agent-canvas

Warum das nötig ist: Die Herstellerdoku startet den Container mit ~/.openhands aus dem Home-Verzeichnis. Auf einem Linux-Host gehört dieser Ordner Ihrer eigenen UID, meist 1000. Im Test brach der Automation Server dann mit sqlite3.OperationalError: unable to open database file und „Application startup failed. Exiting.“ ab, die Oberfläche blieb unerreichbar.

Verifizieren: ls -lan /opt/agent-canvas zeigt für openhands und projects Besitzer und Gruppe 10001.

Schritt 2: Compose-Datei und Geheimnisse

Die Doku beschreibt den Start per docker run. Für den Dauerbetrieb mit Ollama fasst eine Compose-Datei beides zusammen:

services:
  ollama:
    image: ollama/ollama:0.35.0
    environment:
      OLLAMA_CONTEXT_LENGTH: "32768"
      OLLAMA_KEEP_ALIVE: "-1"
    volumes:
      - ollama:/root/.ollama
    restart: unless-stopped
    # NVIDIA-GPU (nur mit NVIDIA Container Toolkit)
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

  canvas:
    image: ghcr.io/openhands/agent-canvas:1.34.0
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      LOCAL_BACKEND_API_KEY: ${LOCAL_BACKEND_API_KEY}
      OH_SESSION_API_KEYS_0: ${LOCAL_BACKEND_API_KEY}
      OH_SECRET_KEY: ${OH_SECRET_KEY}
      AGENT_CANVAS_DISABLE_TELEMETRY: "1"
    volumes:
      - ./openhands:/home/openhands/.openhands
      - ./projects:/projects
    depends_on:
      - ollama
    restart: unless-stopped

volumes:
  ollama:

Ohne GPU entfernen Sie den deploy-Block, Ollama rechnet dann auf der CPU. Erzeugen Sie die .env mit zwei zufälligen Werten:

printf 'LOCAL_BACKEND_API_KEY=%s\nOH_SECRET_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
chmod 600 .env

Einstellung	Wert	Zweck
Image	ghcr.io/openhands/agent-canvas:1.34.0	Canvas, Agent Server 1.58.1, Automation Server
Port	8000, Oberfläche unter /canvas	gemeinsamer Eingang für UI und API
Volume	/home/openhands/.openhands	Einstellungen, Geheimnisse, Verläufe
Volume	/projects	Arbeitsordner des Agenten
OH_SESSION_API_KEYS_0	Schlüssel	schützt die API (siehe Schritt 4)
OH_SECRET_KEY	Schlüssel	verschlüsselt gespeicherte Einstellungen und Geheimnisse

Verifizieren: docker compose config -q gibt nichts aus, docker compose config | grep -A2 ports zeigt host_ip: 127.0.0.1.

Schritt 3: Stack starten

docker compose pull
docker compose up -d
docker compose logs canvas | grep agent-canvas

Im Test war der Dienst etwa zehn Sekunden nach dem Start erreichbar. Das Log meldet dann:

[agent-canvas] Automation Server is ready on port 18001
[agent-canvas] Starting frontend + proxy on port 8000...
[agent-canvas] All services started. Unified entry point: http://0.0.0.0:8000/

Verifizieren: curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/canvas/ liefert 200, ebenso /health. Der Aufruf von / antwortet mit 308, einer Weiterleitung auf /canvas/.

Schritt 4: API-Schutz prüfen

Der Agent Server führt beliebige Shell-Befehle im Container aus und liest Dateien. Wer die API erreicht, kontrolliert also den Agenten. Die Doku nennt LOCAL_BACKEND_API_KEY als Schutz. Im Test mit Agent Canvas 1.26.0 reichte diese Variable allein jedoch nicht: Mit gesetztem LOCAL_BACKEND_API_KEY beantwortete /api/settings Anfragen ohne Schlüssel und mit falschem Schlüssel mit 200. Das Startskript des Images übergibt den Schlüssel nur dann an den Agent Server (OH_SESSION_API_KEYS_0), wenn es ihn selbst erzeugt. Deshalb setzt die Compose-Datei aus Schritt 2 beide Variablen auf denselben Wert. Prüfen Sie das Ergebnis:

K=$(grep ^LOCAL_BACKEND_API_KEY .env | cut -d= -f2)
curl -s -o /dev/null -w 'ohne Schlüssel: %{http_code}\n' http://127.0.0.1:8000/api/settings
curl -s -o /dev/null -w 'mit Schlüssel:  %{http_code}\n' -H "X-Session-API-Key: $K" http://127.0.0.1:8000/api/settings

Eine zweite Eigenheit betrifft den Zugang von außen: Die Seite /canvas/ liefert den Schlüssel im HTML an den Browser aus, damit die Oberfläche ohne Anmeldung funktioniert. Wer die Oberfläche öffnen kann, hat damit auch den Schlüssel. Veröffentlichen Sie Port 8000 deshalb nicht über einen Reverse Proxy, sondern nutzen Sie den von der Doku beschriebenen SSH-Tunnel:

ssh -L 8000:127.0.0.1:8000 benutzer@server

Verifizieren: Die erste Abfrage liefert 401, die zweite 200. Im Browser öffnet http://localhost:8000/canvas über den Tunnel die Oberfläche, und das Backend erscheint als verbunden.

Schritt 5: Modell in Ollama laden

OpenHands schickt einen langen Systemprompt samt Werkzeugbeschreibungen. Mit dem Ollama-Standard von 4096 Token passt laut Doku nicht einmal dieser, der Agent arbeitet dann fehlerhaft. Die Compose-Datei setzt deshalb OLLAMA_CONTEXT_LENGTH=32768; das Minimum laut Hersteller sind 22 000. Laden Sie das empfohlene Modell:

docker compose exec ollama ollama pull qwen3.6:35b-a3b
docker compose exec canvas curl -s http://ollama:11434/v1/models

Der zweite Befehl prüft die Verbindung aus Sicht des Agent Servers. Das ist entscheidend, denn die Modelladresse muss vom Backend aus erreichbar sein, nicht vom Browser. Im selben Compose-Projekt heißt der Rechner ollama. Läuft Ollama direkt auf dem Host, zeigt 127.0.0.1 im Container auf den Container selbst; dann brauchen Sie host.docker.internal mit dem Eintrag extra_hosts: ["host.docker.internal:host-gateway"] und ein Ollama, das nicht nur auf 127.0.0.1 lauscht.

Verifizieren: docker compose exec canvas curl -s http://ollama:11434/api/version liefert {"version":"0.35.0"}. Nach dem Download listet /v1/models den Eintrag qwen3.6:35b-a3b.

Schritt 6: Modell in Agent Canvas eintragen

Öffnen Sie Settings > LLM und wechseln Sie auf Advanced. Für lokale Server mit OpenAI-kompatibler Schnittstelle gilt laut Doku:

• Model: openai/qwen3.6:35b-a3b (Präfix openai/ plus exakter Name aus /v1/models)
• Base URL: http://ollama:11434/v1
• API Key: ein beliebiger Platzhalter wie local-llm

Wer dieselben Zugangsdaten für mehrere Modelle nutzt, legt sie einmal als Provider Connection an und verknüpft die Profile damit. Wählen Sie vor dem ersten Gespräch mit Open Workspace einen Ordner unter /projects, sonst arbeitet der Agent an einem Ort, den Sie nicht erwarten.

Verifizieren: Ein neues Gespräch mit einer kurzen Aufgabe, etwa „Liste die Dateien im Arbeitsordner auf“, liefert eine Antwort des Modells und zeigt den ausgeführten Befehl. Die Fehlermeldung LLM Provider NOT provided weist auf ein fehlendes Präfix oder falsches Anbieterfeld hin.

Schritt 7: Grenzen der Isolation kennen

Der Container ist die Sicherheitsgrenze. Im Test fand der Agent Server keinen Docker-Socket (failed to connect to the docker API at unix:///var/run/docker.sock) und konnte damit keine anderen Container steuern. Der Agent sieht nur die eingebundenen Ordner. Soll er selbst Container bauen und starten, verlangt die Doku --privileged und warnt, dass dies die Trennung zum Host erheblich schwächt; einen sichereren Mittelweg gibt es laut Hersteller nicht. Binden Sie außerdem keine breiten Pfade wie das ganze Home-Verzeichnis ein, und legen Sie Zugangsdaten für Git-Dienste nur mit den Rechten an, die der Agent wirklich braucht.

Verifizieren: docker compose exec canvas ls /var/run/docker.sock meldet „No such file or directory“, docker inspect auf den Canvas-Container zeigt unter Mounts nur die beiden Ordner aus Schritt 1.

Update auf Agent Canvas 1.29.0: Sichern Sie die Ordner openhands und projects sowie die .env. Erhalten Sie OH_SECRET_KEY, beide API-Schlüsselvariablen und die localhost-Bindung. Ändern Sie den Canvas-Image-Tag und erstellen Sie den Container neu. Version 1.28 lässt den Agenten laut Release Notes Geheimnisse direkt im Chat anfordern, blendet auf selbst betriebenen Instanzen Automationsvorlagen aus, die sich mit eingebauten Integrationen überschneiden, und bringt zahlreiche Korrekturen an Oberfläche und Automationen; 1.28.1 hebt den Agent Server auf 1.56.0. Prüfen Sie nach dem Update Oberfläche, API-Anmeldeschutz und vorhandene Einstellungen. Im Test von 1.27.1 auf 1.28.1 mit der Compose-Datei aus Schritt 2 (ohne Ollama) antwortete /api/settings ohne und mit falschem Schlüssel weiter mit 401, mit Schlüssel mit 200, die gespeicherten Einstellungen und eine Datei im Projektordner blieben erhalten, der Container lief weiter als UID 10001, /canvas/ und /health lieferten 200, und im Container war kein Docker-Socket vorhanden.

Version 1.29.0 bringt laut Release Notes vor allem Agentenprofile, in denen Sie Skills, Condenser, Verifikation und Model Router je Profil festlegen; der Agent Server bleibt bei 1.56.0. Neue Pflichtvariablen oder geänderte Mounts gibt es nicht. Der Test von 1.28.1 auf 1.29.0 am 21.10.2026 lieferte dasselbe Bild: /api/settings ohne und mit falschem Schlüssel 401, mit Schlüssel 200, Einstellungen und Projektdatei erhalten, Container als UID 10001, /canvas/ und /health mit 200.

Version 1.30.0 bringt laut Release Notes vor allem Korrekturen: Arbeitsbereich-Gruppierungen werden serverseitig als Tags der Konversation gespeichert, Automationsvorlagen zeigen den Verbindungsstatus eingebauter Integrationen, dazu Fehlerbehebungen an Seitenleiste und Agentenprofilen. Der Agent Server bleibt bei 1.56.0, neue Pflichtvariablen oder geänderte Mounts gibt es nicht. Auch der Test von 1.29.0 auf 1.30.0 am 22.10.2026 mit der Compose-Datei aus Schritt 2 (ohne Ollama) lieferte /api/settings ohne und mit falschem Schlüssel 401, mit Schlüssel 200; Einstellungen und Projektdatei blieben erhalten, der Container lief als UID 10001, /canvas/ und /health antworteten mit 200.

Version 1.30.1 hebt laut Release Notes den Agent Server auf 1.57.0, Version 1.31.0 blendet auf selbst gehosteten Instanzen das Feld für das GitHub-Token in Automationen aus, sobald GitHub verbunden ist, und korrigiert die Installation von MCP-Einträgen, die nur OAuth nutzen, sowie das Bearbeiten von Automationen mit Repositorys. Neue Pflichtvariablen oder geänderte Mounts gibt es nicht. Im Test von 1.30.0 auf 1.31.0 am 23.10.2026 mit der Compose-Datei aus Schritt 2 (ohne Ollama) antwortete /api/settings ohne und mit falschem Schlüssel mit 401, mit Schlüssel mit 200; Einstellungen und Projektdatei blieben erhalten, im Container meldete das Paket openhands-agent-server Version 1.57.0, der Prozess lief als UID 10001, und /canvas/ sowie /health antworteten mit 200.

Version 1.32.0 hebt laut Release Notes den Agent Server auf 1.58.1 und den Automation Server auf 1.25.1, speichert angeheftete Automationen in den Einstellungen des Agent Servers und schreibt die Protokolle des Backends standardmäßig knapper. Version 1.33.0 maskiert Geheimwerte in Anfragen und Einstellungsformularen und bringt Korrekturen an Automationen. Neue Pflichtvariablen oder geänderte Mounts gibt es auch hier nicht. Im Test von 1.31.0 auf 1.33.0 am 24.10.2026 mit der Compose-Datei aus Schritt 2 (ohne Ollama) antwortete /api/settings ohne und mit falschem Schlüssel mit 401, mit Schlüssel mit 200; das eingestellte Modell und die Projektdatei blieben erhalten, im Container meldete openhands-agent-server Version 1.58.1, der Prozess lief als UID 10001, und /canvas/ sowie /health antworteten mit 200. Version 1.34.0 bringt laut Release Notes eine eigene Docker-Laufzeit je Gespräch mit der neuen Einstellungsseite Settings → Runtime, übergibt den Sitzungsschlüssel an den statischen Server per Umgebungsvariable statt als Programmargument und verhindert, dass nicht vertrauenswürdiges Markdown Links mit rel="opener" setzt. Die Docker-Laufzeit setzt einen Zugriff auf Docker voraus, den diese Anleitung bewusst nicht einbindet (Schritt 7). Neue Pflichtvariablen oder geänderte Mounts nennen die Release Notes nicht. Im Test von 1.33.0 auf 1.34.0 am 28.10.2026 mit der Compose-Datei aus Schritt 2 (ohne Ollama) antwortete /api/settings ohne und mit falschem Schlüssel mit 401, mit Schlüssel mit 200; die Projektdatei blieb erhalten, openhands-agent-server meldete weiter Version 1.58.1, der Prozess lief als UID 10001, und /canvas/ sowie /health antworteten mit 200.

Grundlagen zum Betrieb finden Sie in Docker Compose unter Linux: Grundlage für Selfhosting, Docker Compose absichern: Secrets, Healthchecks, Non-Root, Linux-Server absichern mit UFW und Fail2ban und Docker-Container automatisch aktualisieren: Diun, WUD und Renovate im Vergleich.

Typische Fehler

• unable to open database file, danach „Application startup failed“: Der eingebundene Ordner gehört nicht UID 10001. Container stoppen, chown -R 10001:10001 auf beide Ordner, neu starten.
• API antwortet ohne Schlüssel mit 200: Nur LOCAL_BACKEND_API_KEY gesetzt. OH_SESSION_API_KEYS_0 mit demselben Wert ergänzen und den Container neu erstellen.
• Modell nicht erreichbar: Base URL zeigt auf 127.0.0.1 oder localhost. Aus dem Container heraus mit curl testen und den Dienstnamen oder host.docker.internal verwenden.
• Agent verhält sich wie ein Chatbot oder ignoriert Werkzeuge: Kontextfenster zu klein oder Modell zu schwach. OLLAMA_CONTEXT_LENGTH prüfen, größeres Modell wählen.
• Port 8000 belegt: Linke Seite der Portzuordnung ändern, etwa 127.0.0.1:8010:8000.

Häufige Fragen

Was ist aus dem alten OpenHands-Container auf Port 3000 geworden?

Die aktuelle Dokumentation beschreibt Agent Canvas als Weg für den eigenen Betrieb. Das eigenständige Repository OpenHands/agent-canvas verweist inzwischen auf das Hauptrepository. Der frühere Aufbau, bei dem der Web-Container über den Docker-Socket eigene Sandbox-Container startete, entfällt im Docker-Image von Agent Canvas.

Geht es ganz ohne GPU?

Ja, Ollama rechnet dann auf der CPU. Für Agentenaufgaben mit großem Kontext ist das langsam, und die kleinen Modelle, die auf CPU erträglich laufen, scheitern laut Doku häufiger an Werkzeugaufrufen. Alternativ binden Sie einen Cloud-Anbieter per API-Schlüssel an; dann verlassen Code und Prompts allerdings Ihr Netz.

Kann ich Agent Canvas ohne Docker betreiben?

Ja, per npm install -g @openhands/agent-canvas mit Node.js 24 und uv. Der Agent arbeitet dann direkt mit den Rechten Ihres Benutzerkontos auf dem Host. Die Doku empfiehlt Docker ausdrücklich, wenn Sie eine klarere Dateigrenze wollen.

Wie aktualisiere ich?

Release Notes lesen, das Tag in der Compose-Datei anheben, docker compose pull und docker compose up -d. Einstellungen und Verläufe bleiben im Ordner openhands erhalten. Sichern Sie diesen Ordner vorher, er enthält auch die mit OH_SECRET_KEY verschlüsselten Geheimnisse; ohne den Schlüssel aus der .env sind sie wertlos.

Fazit

Agent Canvas macht den Betrieb von OpenHands einfacher und sicherer als der frühere Aufbau: ein Container, keine Socket-Freigabe, klare Arbeitsordner. Zwei Details entscheiden über einen sauberen Start. Die Ordner müssen UID 10001 gehören, und der API-Schlüssel wirkt im Test erst mit OH_SESSION_API_KEYS_0. Weil die Oberfläche den Schlüssel an jeden Browser ausliefert, gehört Port 8000 an 127.0.0.1 und der Zugriff durch einen SSH-Tunnel. Beim Modell entscheidet die Hardware: Für brauchbare Agentenarbeit mit Ollama braucht es eine GPU mit 24 GB VRAM und ein großes Kontextfenster.

Weiterführende Anleitungen und Quellen

• Ollama-Modelle richtig auswählen: VRAM und Quantisierung
• Ollama und Open WebUI mit Docker
• Continue.dev mit Ollama in VS Code
• Lokale KI: DSGVO-Checkliste
• OpenHands: Use Docker with Agent Canvas
• OpenHands: Install Agent Canvas
• OpenHands: VM / Self-Hosted Installation
• OpenHands: Run Local LLMs
• OpenHands: Configure a Model
• GitHub: OpenHands Releases