Ihr erster OpenHands-Agent startet nicht, weil Node.js, Berechtigungen oder ein erreichbares Backend fehlen.

Schnellste Lösung: Für einen persönlichen Ersttest wählen Sie die Desktop-Vorschau oder npx; für klar begrenzten lokalen Dateizugriff Docker; für Dauerbetrieb, Teamzugriff oder stärkere Ressourcen ein Remote-Backend. OpenHands Agent Canvas installieren bedeutet dabei nicht nur, eine Oberfläche zu öffnen: Sie müssen getrennt prüfen, wo der Client läuft, wo der Agent-Prozess läuft und welche Umgebung tatsächlich Dateien und Befehle ausführt.

Zielgruppe und Entscheidung in 30 Sekunden

Dieser Artikel richtet sich an Entwickler, die OpenHands erstmals ausprobieren möchten, ohne sich sofort in Node.js- und uv-Abhängigkeiten einzuarbeiten. Er hilft ebenso Plattformingenieuren, die Dateizugriffe begrenzen, einen dauerhaft erreichbaren Dienst betreiben oder eine Umgebung für mehrere Personen bereitstellen müssen.

Ihr konkretes Ziel Empfohlener Einstieg Wo läuft der Agent? Was bleibt nach dem Stoppen?
Persönlicher Ersttest ohne Infrastruktur Desktop-Vorschau oder npx In der lokal verwendeten Backend-Umgebung Laufender Prozess und nicht persistierte Sitzungsdaten enden
Agent soll ein lokales Projekt bearbeiten Docker mit gezieltem Mount Im Container oder in der von Ihnen gewählten Backend-Umgebung Nur Daten in gemounteten oder persistierten Speicherorten bleiben
Wiederholbare Entwicklungsumgebung Docker mit Volume und fester Konfiguration Im Container Volume-Inhalte bleiben, Containerprozesse enden
Aufgaben sollen bei geschlossenem Rechner weiterlaufen Remote-Backend auf VM oder Remote-Host Auf dem unabhängigen Host Backend und persistierte Daten können weiterlaufen
Gemeinsame Teamumgebung Remote-Backend mit kontrolliertem Zugang In der zentral verwalteten Ausführungsumgebung Abhängig von Persistenz, Aufgabenverwaltung und Wiederherstellungslogik

Die offizielle Architektur beschreibt Agent Canvas nicht als ein einziges Programm mit einer einzigen Sicherheitsgrenze. Sie müssen vielmehr Canvas-Client, aktives Backend und tatsächliche Ausführungsumgebung auseinanderhalten Architecture von Agent Canvas. Diese Trennung ist der wichtigste Schutz gegen eine falsche Installationsentscheidung.

Installationswege und ihre tatsächlichen Grenzen

Die Desktop-App ist für den ersten Kontakt attraktiv, weil sie die Zahl der manuellen Schritte reduziert. Nach dem Öffnen sehen Sie schneller eine Canvas-Oberfläche und müssen nicht zwingend zuerst eine lokale JavaScript-Umgebung aufbauen. Der Status bleibt jedoch entscheidend: Die offiziellen Hinweise führen die Desktop-Anwendungen für macOS, Windows und Linux weiterhin als frühe Vorschau. Das ist ein Argument für einen einfachen Test, nicht für die Annahme, dass die App bereits die stabilste Produktionsgrundlage bildet.

Bei npx wird der Start stärker an die lokale Node.js-Umgebung gebunden. Das ist für Entwickler praktisch, die ohnehin mit JavaScript-Werkzeugen arbeiten, weil der Aufruf und die Aktualisierung näher an den üblichen Paketabläufen liegen. Prüfen Sie die von der Dokumentation erwartete Node.js-Version und Installationsart in der offiziellen Node.js-Anleitung, bevor Sie einen Befehl aus einer fremden Anleitung übernehmen. Eine globale npm-Installation ist nicht automatisch besser: Sie kann Updates und reproduzierbare Rollbacks erschweren.

Der npm-Weg ist dann sinnvoll, wenn Sie den Start in ein eigenes Skript, eine Entwicklungsumgebung oder eine standardisierte lokale Einrichtung aufnehmen möchten. Für einen einmaligen Test erzeugt er dagegen mehr Pflegeentscheidungen als nötig. Die aktuelle Installationsseite ist die maßgebliche Quelle für Befehle, unterstützte Systeme und die jeweils erwarteten Voraussetzungen offizielle Agent-Canvas-Setup-Seite.

Docker verschiebt den Schwerpunkt von „möglichst schnell öffnen“ zu „kontrolliert wiederholen“. Sie definieren, welche Projektpfade gemountet werden, wo Konfiguration und Sitzungsdaten liegen und wie der Start reproduziert wird. Das ist vor allem dann wertvoll, wenn ein Agent Schreibzugriff erhalten soll, Sie aber nicht das gesamte Benutzerverzeichnis freigeben möchten. Die Docker-Anleitung für das Agent-Canvas-Backend beschreibt diesen Bereitstellungsweg in der offiziellen Backend-Dokumentation.

Installationsweg Vorbedingungen Stärkster Vorteil Hauptproblem
Desktop-Vorschau Herunterladen, öffnen, Backend-Verbindung prüfen Niedrige Einstiegshürde Keine automatische Sandbox für Agent-Aktionen
npx Node.js und funktionierender Paketaufruf Schneller, lokaler Test ohne dauerhafte globale Installation Abhängigkeit von lokaler Umgebung und Terminal
npm Node.js, Paketverwaltung und Updatepflege In Skripte und Entwickler-Setups integrierbar Versions- und Pfadpflege liegt bei Ihnen
Docker Docker Engine oder Desktop, Mount- und Speicherplanung Wiederholbarer Start und begrenzte Dateifläche Containerbetrieb ist zusätzliche Infrastruktur
Remote-Backend VM oder separater Host, Netzwerk- und Zugriffskonfiguration Dauerbetrieb, Teamzugriff und unabhängige Ressourcen Authentifizierung, TLS, Wartung und Kosten

Die Versionslage ist für diese Auswahl relevant: Die offizielle Dokumentation enthält unter anderem die Release-Informationen für Agent Canvas 1.16.0 in den Release Notes. Da sich Vorschau-Status, Befehle und unterstützte Architekturen ändern können, sollten Sie vor jedem produktiven Rollout die Setup-Seite und die zugehörigen Release Notes gemeinsam prüfen.

Szenario Ersttest

Für die erste erfolgreiche Aufgabe sollten Sie nicht sofort ein wichtiges Repository öffnen. Erstellen Sie ein kleines Testprojekt mit einer einzelnen Textdatei und einer Aufgabe, die eine klar erkennbare Änderung erzeugt, etwa das Anlegen einer kurzen Dokumentationsdatei. So können Sie nachweisen, dass der Agent nicht nur sichtbar ist, sondern tatsächlich eine Aufgabe annimmt, Dateien lesen darf und Änderungen am erwarteten Ort schreibt.

Gehen Sie in dieser Reihenfolge vor:

  1. Öffnen Sie die aktuelle offizielle Setup-Anleitung und wählen Sie dort den für Ihr Betriebssystem vorgesehenen Desktop-, npx- oder npm-Weg.
  2. Starten Sie Canvas und identifizieren Sie das aktive Backend, bevor Sie ein Arbeitsverzeichnis auswählen.
  3. Legen Sie ein isoliertes Testverzeichnis an, das keine Zugangsschlüssel, privaten SSH-Dateien oder produktiven Quellcodes enthält.
  4. Erteilen Sie nur die für diesen Test erforderlichen Dateirechte und starten Sie eine minimale Schreibaufgabe.
  5. Prüfen Sie die erzeugte Datei außerhalb der Oberfläche und kontrollieren Sie, ob sie wirklich im erwarteten Verzeichnis liegt.
  6. Stoppen Sie den Prozess, öffnen Sie die Sitzung erneut und dokumentieren Sie, welche Konfiguration und welche Aufgabenhistorie erhalten geblieben sind.
  7. Erst wenn diese Prüfung erfolgreich ist, verbinden Sie ein echtes Projekt oder wechseln zu Docker beziehungsweise einem Remote-Backend.

Die Belege für einen gelungenen Ersttest sind damit konkret: Der Agent läuft im erwarteten Backend, die Änderung erscheint im vorgesehenen Arbeitsverzeichnis, kein nicht freigegebener Ordner wurde verändert und Sie wissen, was nach dem Beenden des Clients verloren geht. Die Desktop-Vorschau verkürzt diesen Weg, ersetzt aber keine dieser Prüfungen.

Szenario Lokales Projekt und Dateigrenzen

Eine lokale Installation ist besonders bequem, wenn der Agent direkt neben Ihrem Projekt arbeitet. Genau diese Nähe ist jedoch die zentrale Risikofläche. Je nach Startart, Benutzerkonto und Backend können Prozesse dieselben Rechte erben wie Ihr lokaler Benutzer. Ein Agent, der ein Projektverzeichnis ändern darf, kann dadurch unter Umständen auch auf weitere Ressourcen zugreifen, wenn Sie die Umgebung nicht bewusst einschränken.

Für ein nicht vertrauliches Projekt mit sauberem Versionskontrollstand kann der direkte lokale Weg angemessen sein. Das gilt vor allem, wenn Sie jede Änderung prüfen und schnell zurücksetzen können. Für Quellcode mit Zugangsdaten, Kundendaten, privaten Schlüsseln oder weitreichenden Build-Skripten sollten Sie dagegen ein getrenntes Arbeitsverzeichnis und möglichst Docker verwenden.

Die entscheidende Frage lautet nicht „Sieht die Oberfläche lokal aus?“, sondern „Welche Verzeichnisse sieht der ausführende Prozess?“. Öffnen Sie nicht pauschal Ihr Home-Verzeichnis. Mounten Sie bei Docker nur das Projekt, das der Agent bearbeiten muss, und legen Sie Konfigurationsdateien getrennt von den Quelldateien ab. Docker-Volumes sind für persistente Daten gedacht und werden in der offiziellen Dokumentation zur Volume-Speicherung beschrieben.

Szenario Reproduzierbare Isolation mit Docker

Docker ist die ausgewogene Wahl, wenn Sie lokale Ausführung wünschen, aber die Dateigrenze explizit machen müssen. Der Agent läuft dann im Container; sichtbar sind zunächst nur das Container-Dateisystem und die von Ihnen eingebundenen Verzeichnisse. Nach dem Entfernen des Containers verschwinden nicht automatisch die Daten, die in einem persistenten Volume oder einem bewusst gemounteten Host-Verzeichnis liegen. Genau diese Unterscheidung müssen Sie vor dem ersten echten Auftrag dokumentieren.

Prüfen Sie eine Docker-Einrichtung in fünf technischen Punkten:

  1. Arbeitsverzeichnis: Mounten Sie nur den Projektpfad, nicht pauschal den gesamten Benutzerordner.
  2. Schreibrechte: Testen Sie getrennt, ob der Agent lesen, eine neue Datei anlegen und eine bestehende Datei verändern kann.
  3. Konfigurationsspeicher: Bestimmen Sie, ob Einstellungen im Container, in einem Volume oder auf dem Host liegen.
  4. Stoppszenario: Beenden Sie den Container und starten Sie ihn erneut; vergleichen Sie Konfiguration, Aufgabenstatus und Projektdateien.
  5. Netzwerk: Prüfen Sie, welche ausgehenden Verbindungen erforderlich sind und ob unnötiger Netzwerkzugriff blockiert werden kann.
Prüfpunkt Direkter lokaler Start Docker Remote-Backend
Sichtbare Dateien Abhängig von Benutzerrechten und Prozessstart Durch Mounts und Containerpfade begrenzbar Auf dem Remote-Host festlegbar
Wiederholbarer Start Eher skriptabhängig Image, Volumes und Konfiguration dokumentierbar VM- oder Host-Konfiguration dokumentierbar
Verhalten bei Terminalende Kann den Agent-Prozess beenden Abhängig vom Containerbetrieb Unabhängig vom lokalen Terminal möglich
Wiederherstellung Lokale Sitzungs- und Projektprüfung nötig Volume- und Aufgabenstatus prüfen Backend-, Speicher- und Aufgabenstatus prüfen
Sicherheitsgrenze Benutzer- und Prozessrechte Zusätzliche Containergrenze, aber keine Vollisolation Durch Host, Netzwerk und Zugangskontrollen bestimmbar

Die Containergrenze ist nicht dasselbe wie vollständige Mandantentrennung. Die Docker-Sicherheitsdokumentation weist auf Konfigurations- und Betriebsaspekte hin, die Sie vor einem Team- oder Produktionsbetrieb berücksichtigen müssen Docker-Sicherheitsdokumentation. Besonders kritisch sind privilegierte Container, unnötige Socket-Freigaben, weit gefasste Mounts und gemeinsam genutzte Geheimnisse.

Szenario Dauerbetrieb und Remote-Zugriff

Sobald Ihr Rechner schlafen geht, das Terminal geschlossen wird oder die lokale Netzwerkverbindung wechselt, wird ein lokaler Start zur Betriebsentscheidung. Ein kurzer Agent-Auftrag darf dann scheitern oder manuell neu gestartet werden. Ein längerer Build, eine Migration oder eine Aufgabe mit mehreren Zwischenschritten sollte dagegen auf einem unabhängigen Host laufen.

Ein Remote-Backend ist passend, wenn Canvas nur noch als lokale Oberfläche dienen soll, während der Agent-Prozess und die Ausführungsumgebung auf einer VM oder einem separaten Server liegen. Die offizielle Anleitung beschreibt diesen VM-Weg als eigene Backend-Option in der Dokumentation zur VM-Bereitstellung. Entscheidend ist die Reihenfolge der Absicherung:

  1. Backend zunächst nur im privaten Netzwerk erreichbar machen.
  2. Verbindung vom lokalen Canvas-Client mit einem ungefährlichen Testprojekt prüfen.
  3. Authentifizierung und Rechte für Benutzer beziehungsweise Teams einrichten.
  4. Erst danach einen externen Zugriff planen.
  5. Für externe Verbindungen TLS, Netzwerkfilter und Protokollierung aktivieren.
  6. Einen kontrollierten Test für Abbruch, Neustart und Aufgabenwiederaufnahme durchführen.
  7. Festlegen, wer Images, Abhängigkeiten, Geheimnisse und Logs aktualisiert.

Ein offener Port ohne Authentifizierung ist kein Teamdienst. Ebenso ersetzt HTTPS keine Zugriffskontrolle. Wenn Sie sensible Quellcodes verarbeiten, sollten Sie zusätzlich klären, wo Logs, Arbeitskopien und Zugangsdaten gespeichert werden. Für Anforderungen an Datenschutz und DSGVO gehört diese Prüfung in die Architekturentscheidung; die Datenschutzerklärung von SSHMac zeigt, wo Sie ergänzende Informationen zur Verarbeitung im Zusammenhang mit dem Dienst nachlesen können.

Szenario Teams und unterschiedliche Werkzeugketten

„Gemeinsam nutzen“ kann drei verschiedene Dinge bedeuten: eine gemeinsame Canvas-Oberfläche, ein gemeinsames Backend oder eine gemeinsame Ausführungsumgebung. Diese Ebenen sollten Sie nicht in einem einzigen Benutzerkonto zusammenfassen. Ein Team kann dieselbe Oberfläche verwenden, aber getrennte Backends benötigen. Umgekehrt kann ein zentraler Dienst mehrere Nutzer bedienen, ohne dass alle Aufgaben dieselben Dateipfade, Geheimnisse oder Betriebssystemwerkzeuge sehen.

Für Linux-nahe Aufgaben ist ein standardisierter Container oder eine VM häufig leichter reproduzierbar. Aufgaben, die macOS-spezifische Werkzeuge, Apple-SDKs oder lokale Signaturumgebungen benötigen, sollten in eine getrennte Ausführungsgruppe gehören. Ein Linux-Container kann keinen Mac-Arbeitsplatz ersetzen, nur weil Canvas von mehreren Geräten erreichbar ist. Wenn Sie Apple-spezifische Aufgaben remote ausführen möchten, prüfen Sie daher zuerst die Bedingungen der macOS-Entwicklungsumgebung von SSHMac, statt die Plattformwahl allein nach der Installationsdauer zu treffen.

Teamanforderung Geeignete Struktur Vor dem Rollout zu belegen
Einzelner Entwickler, ungefährlicher Test Desktop oder npx Start, Dateizugriff und Stop-Verhalten
Mehrere Entwickler, gemeinsames Standardprojekt Zentrales Backend mit getrennten Zugriffsrechten Identität, Projektgrenzen und Aufgabenwiederaufnahme
Unterschiedliche Linux-Projekte Getrennte Container oder klar definierte Arbeitsbereiche Image-Version, Mounts und persistente Speicher
Apple-spezifische Aufgaben Eigene macOS-Ausführungsumgebung Verfügbarkeit der erforderlichen Werkzeuge und Zugriffsrechte
Lang laufende Aufgaben Remote-Backend auf unabhängiger Infrastruktur Neustart, Logs, Persistenz und Wiederaufnahme

Eine gemeinsame Infrastruktur ist also nicht automatisch effizienter. Wenn jede Aufgabe eigene Abhängigkeiten benötigt, kann ein getrenntes Backend mehr Betriebsaufwand verursachen, aber gleichzeitig Fehler durch konkurrierende Versionen und falsche Dateirechte verhindern.

Entscheidungsregeln für die Auswahl

Verwenden Sie diese Bedingungen, bevor Sie sich auf einen Installationsweg festlegen:

  • Wenn Sie nur eine kleine, ungefährliche Aufgabe testen und keine dauerhafte Infrastruktur benötigen, wählen Sie die Desktop-Vorschau oder npx; andernfalls wechseln Sie zu Docker.
  • Wenn der Agent ausschließlich ein klar bestimmtes lokales Projekt sehen und verändern darf, wählen Sie Docker mit einem engen Mount; andernfalls prüfen Sie zuerst, ob der direkte lokale Start zu viele Benutzerrechte übernimmt.
  • Wenn der Prozess auch bei geschlossenem Laptop oder Terminal weiterlaufen muss, wählen Sie ein Remote-Backend; andernfalls genügt eine lokale Ausführung.
  • Wenn mehrere Personen dieselbe Umgebung nutzen, wählen Sie ein Backend mit getrennten Identitäten, Logs und Arbeitsbereichen; andernfalls bleibt eine lokale Installation für Einzeltests einfacher.
  • Wenn die Aufgabe macOS- oder Apple-spezifische Werkzeuge verlangt, wählen Sie eine passende Mac-Ausführungsumgebung; andernfalls kann eine Linux-basierte Container- oder VM-Umgebung ausreichen.
  • Wenn Sie nicht sicher sagen können, welche Dateien nach dem Stoppen erhalten bleiben, starten Sie noch keinen echten Auftrag; dokumentieren Sie zuerst Mounts, Volumes und Aufgabenpersistenz.

Aktualität und Prüfgrenzen

Zuletzt aktualisiert am 06.09.2026; geprüft anhand der offiziellen Installations-, Architektur-, Docker-, VM- und Release-Dokumentation.

Für diesen Artikel werden keine eigenen Startzeiten, Leistungswerte oder Anbieterbenchmarks behauptet. Die belastbaren Aussagen beziehen sich auf die dokumentierten Installationswege, die Trennung von Client und Backend, die weiterhin frühe Desktop-Vorschau sowie die veröffentlichte Agent-Canvas-Version 1.16.0. Wenn die offizielle Dokumentation die Installationsbefehle, unterstützten Architekturen oder den Vorschau-Status ändert, muss die Auswahl erneut getestet werden.

Wenn Sie lediglich den persönlichen Ersttest abschließen möchten, beginnen Sie mit der offiziellen Anleitung und einem ungefährlichen Testverzeichnis. Sobald jedoch lokale Geheimnisse, unbegrenzte Benutzerrechte oder lange Laufzeiten ins Spiel kommen, ist die bequemste Oberfläche nicht mehr automatisch die passende Lösung.

Häufige Fragen

Die folgenden Antworten trennen den sichtbaren Canvas-Client von dem Backend, das den Agent tatsächlich ausführt. Dadurch vermeiden Sie die häufige Fehlannahme, eine Desktop-Oberfläche sei bereits eine vollständige Sandbox oder ein Teamserver.

Nächster Schritt nach der Entscheidung

Für einen kurzen persönlichen Test ist die lokale Desktop- oder npx-Variante meist der schnellste Weg, solange Sie ein unkritisches Projekt verwenden und die tatsächlichen Dateirechte prüfen. Docker ist die bessere Zwischenstufe, wenn Sie ein lokales Projekt mit kontrollierter Dateifläche bearbeiten lassen möchten. Für dauerhaft laufende Aufgaben, Teamzugriff und wechselnde Geräte gehört das Backend auf eine unabhängige VM oder einen Remote-Host.

Ein eigener Rechner hat dabei drei typische Nachteile: Er ist an Schlafmodus und Terminallebensdauer gebunden, seine Benutzerrechte können für Agent-Aufgaben zu weit reichen, und reproduzierbare Teamumgebungen müssen manuell gepflegt werden. Ein gemieteter Mac von SSHMac ist deshalb vor allem dann die passendere Ergänzung, wenn Ihre Aufgaben macOS- oder Apple-Werkzeuge benötigen und Sie nicht dauerhaft eigene Hardware dafür bereitstellen möchten. Für einen stabilen, langfristigen Hochlastbetrieb oder zwingend benötigte physische Schnittstellen bleibt eigene Infrastruktur die ehrlichere Wahl. Für temporäre Tests, Remote-Entwicklung und klar begrenzte macOS-Aufgaben kann die ausgelagerte Umgebung dagegen den Betriebsaufwand deutlich besser kontrollierbar machen.