OpenHands Agent Canvas: Remote-VM-Deployment 2026

Ein Agent-Canvas-Deployment startet laut offizieller Self-Hosting-Anleitung mit einem einzigen Befehl: npx @openhands/agent-canvas --public. Daraus folgt die wichtigste Entscheidung für Ihren Betrieb: Verwenden Sie eine unabhängige, wiederherstellbare Remote-VM statt Ihres persönlichen Entwicklungsrechners, testen Sie zuerst über SSH-Tunnel oder VPN und öffnen Sie den Dienst erst nach API-Key-, TLS-, Sandbox- und Restart-Prüfung öffentlich. Einen Remote-Mac benötigen Sie erst dann, wenn Xcode, iOS-Simulator, Codesignierung oder ein anderer macOS-spezifischer Werkzeugpfad tatsächlich Teil des Auftrags ist. (Offizielle Self-Hosting-Anleitung)

Für wen diese Anleitung gedacht ist:
Für Entwickler, deren lange OpenHands-Aufgaben durch den Ruhezustand des Notebooks abbrechen. Für Plattform- und DevOps-Teams, die einen gemeinsam nutzbaren Agent Server bereitstellen möchten. Und für Entwicklungsverantwortliche, die Linux-Aufgaben von macOS- und Xcode-Builds trennen müssen.

Zuletzt aktualisiert am 14.08.2026; die Angaben wurden anhand des offiziellen OpenHands-Repositorys, der Self-Hosting-Anleitung, der Architektur-Dokumentation und der Agent-Canvas-Releases geprüft.

Warum eine unabhängige Remote-VM der bessere Startpunkt ist

Wenn Ihr Notebook während einer langen Analyse, eines Testlaufs oder einer Automatisierung einschläft, verschwindet nicht nur die Benutzeroberfläche. Je nach Ausführung verlieren Sie auch die Verbindung zum Backend, lokale Terminalprozesse, nicht synchronisierte Dateien und den Kontext für die weitere Arbeit. Ein persönlicher Entwicklungsrechner ist deshalb als dauerhaft laufender Agent-Host problematisch, selbst wenn die Installation zunächst schneller wirkt.

Eine unabhängige VM trennt drei Verantwortungsbereiche:

1. Agent Canvas als Bedienoberfläche: Sie sehen Gespräche, Dateien, Terminal, Einstellungen und Backend-Auswahl.
2. Agent Server und Automatisierung: Dort werden Agent-Aktionen, API-Aufrufe und geplante oder ereignisgesteuerte Aufgaben ausgeführt.
3. Arbeitsverzeichnis und Ausführungsumgebung: Dort liegen Repositorys, Build-Artefakte, Umgebungsvariablen und gegebenenfalls Zugangsdaten.

Die offizielle Architektur beschreibt Agent Canvas als Frontend, das einen oder mehrere Agent Server ansprechen kann. Das Frontend führt die Aktionen nicht selbst aus und stellt auch keine Sandbox bereit. Diese Grenze ist für Ihre Sicherheitsplanung entscheidend: Wenn Sie Agent Canvas auf einer VM starten, läuft der Agent Server dort und kann je nach Betriebsart Dateisystem, Umgebung und Netzwerk des Hosts erreichen.

Drei Risiken werden häufig unterschätzt:

• Schlaf- und Verbindungsrisiko: Ein geschlossenes Notebook beendet oder unterbricht lokale Prozesse, während eine VM unabhängig weiterlaufen kann.
• Berechtigungsrisiko: Ein direkt auf dem Host laufender Agent kann mehr lesen oder verändern, als für ein einzelnes Repository notwendig wäre.
• Geheimnisrisiko: API-Schlüssel, Cloud-Zugangsdaten, SSH-Schlüssel und CI/CD-Variablen können für den Agenten erreichbar sein, wenn Sie Arbeitsverzeichnis und Systemumgebung nicht sauber trennen.

Für gewöhnliche Codeanalyse, Backend-Builds, Webtests und viele Automatisierungsaufgaben ist Linux meist die pragmatischere Wahl. macOS wird erst relevant, wenn die Aufgabe Apple-spezifische Werkzeuge voraussetzt. Ein Remote-Mac ist daher kein allgemeiner Ersatz für die VM, sondern ein zusätzlicher Build- oder Testknoten.

Die drei Betriebsgrenzen vor dem ersten Befehl festlegen

Bevor Sie Pakete installieren, schreiben Sie auf, welche der folgenden Grenzen für Ihre Umgebung gilt:

Nur Kontrollservice auf der VM

In diesem Modell stellt die VM Agent Canvas, Agent Server und gegebenenfalls die Automatisierung bereit. Der eigentliche Code wird in einer separaten Sandbox oder auf einem anderen Backend bearbeitet. Das reduziert den Schaden bei einem Fehlkonfigurationsfall, erhöht aber den Aufwand für Netzwerkfreigaben und Dateitransfer.

Kontrollservice, Build und Repository auf derselben VM

Das ist der einfachste Aufbau für Einzelentwickler und kleine Teams. Das Repository liegt direkt auf der VM, der Agent führt Befehle dort aus und die Ergebnisse bleiben an einem Ort. Diese Variante ist nur dann vertretbar, wenn Sie die VM wie einen Rechner mit produktionsnahen Zugangsdaten behandeln und das Arbeitsverzeichnis begrenzen.

Frontend lokal, Agent Server remote

Sie nutzen die Oberfläche auf Ihrem Rechner, registrieren die VM als zusätzliches Backend und wechseln in Agent Canvas zwischen lokalen und entfernten Umgebungen. Die offizielle Dokumentation beschreibt genau diesen Backend-Wechsel. Er ist praktisch, aber kein Dateisynchronisationsmechanismus: Nicht übertragene lokale Änderungen erscheinen auf der VM nicht automatisch. (Remote-Backend-Konfiguration)

Achtung: Ein Backend-Wechsel verschiebt nicht Ihre uncommitteten Dateien. Verwenden Sie Git, einen kontrollierten Dateitransfer oder ein gemeinsam verwaltetes Arbeitsverzeichnis, bevor Sie auf der VM einen Auftrag starten.

Erste Phase: VM vorbereiten und Agent Canvas privat starten

Die offizielle Anleitung nennt für einen einfachen Linux-Host Ubuntu 24.04 LTS als geeignete Standardwahl und führt Node.js 22.x sowie uv als Laufzeitabhängigkeiten auf. Die konkreten Ressourcenangaben der offiziellen Dokumentation sollten Sie nicht als universelle Untergrenze verstehen: Modell, Repository-Größe, parallele Aufgaben und Docker-Nutzung verändern den tatsächlichen Bedarf. (VM-Self-Hosting bei OpenHands)

Führen Sie die erste Inbetriebnahme in dieser Reihenfolge durch:

1. VM bereitstellen: Wählen Sie eine unabhängige Linux-VM mit stabiler Netzwerkverbindung, eigener Firewall und kontrollierbarem Snapshot- oder Wiederherstellungsprozess.
2. Betriebssystem aktualisieren: Installieren Sie Sicherheitsupdates und legen Sie einen administrativen Zugang mit SSH-Schlüssel statt Passwortanmeldung an.
3. Grundwerkzeuge installieren:

bash sudo apt-get update sudo apt-get install -y curl git

1. Node.js und uv einrichten: Verwenden Sie Node.js 22.12.x oder neuer sowie uv entsprechend der offiziellen Installationsanleitung. Vermeiden Sie es, eine nicht geprüfte Versionsnummer aus einem alten Blogbeitrag zu übernehmen. (OpenHands-README mit Laufzeitvoraussetzungen)
2. Firewall geschlossen halten: Erlauben Sie zunächst nur SSH von Ihrer festen IP-Adresse oder aus Ihrem VPN-Netz. Die offiziellen Beispiele führen den internen Ingress auf 127.0.0.1:8000; Agent Server, Automatisierung und statischer Server sollen nicht direkt aus dem Internet erreichbar sein.
3. Privaten Start vorbereiten:

bash export LOCAL_BACKEND_API_KEY=$(openssl rand -base64 32) npx @openhands/agent-canvas --public

Der Schlüssel wird laut offizieller Anleitung mit einem kryptografisch zufälligen 256-Bit-Wert erzeugt. Speichern Sie ihn in einem geschützten Secret-Store oder einer root-lesbaren Service-Konfiguration, nicht in einem öffentlichen Repository. (API-Key- und Public-Mode-Hinweise)
7. SSH-Tunnel öffnen: Wenn der Ingress lokal auf Port 8000 lauscht, verbinden Sie sich beispielsweise über einen lokalen Tunnel:

bash ssh -N -L 8000:127.0.0.1:8000 user@vm.example

Öffnen Sie anschließend die lokale Adresse im Browser. Der genaue Tunnelbefehl muss zu Ihrem SSH-Benutzer und Ihrer Netzwerktopologie passen.

Der erste Erfolg ist nicht „die Seite lädt“. Prüfen Sie stattdessen vier Belege:

• Die Benutzeroberfläche ist über den Tunnel erreichbar.
• Der Backend-Status zeigt eine aktive Verbindung.
• Das ausgewählte Repository kann gelesen werden.
• Ein Testauftrag liefert fortlaufende Ereignisse zurück und beendet sich nachvollziehbar.

Wenn einer dieser Punkte fehlt, gehen Sie nicht zur öffentlichen Erreichbarkeit über. Prüfen Sie zuerst Logs, Arbeitsverzeichnis, API-Key und Backend-Adresse.

Agent Canvas auf einer Cloud-VM installieren: Grenzen der direkten Ausführung

Ja, Agent Canvas kann auf einem Cloud-Server beziehungsweise einer Remote-VM betrieben werden. Die offizielle Self-Hosting-Anleitung nennt eine Cloud-VM oder dedizierte Hardware als mögliche Hosts und beschreibt den Betrieb von Agent Canvas, Agent Server und Automatisierungsbackend auf einem gemeinsamen Rechner.

Die direkte Ausführung ist allerdings nicht dasselbe wie ein Docker-Sandbox-Betrieb. Beim direkten Start läuft der Agent Server auf dem Host. Er erhält dadurch grundsätzlich Zugriff auf die für den Prozess erreichbaren Dateien, Umgebungsvariablen und Netzwerkressourcen. Die OpenHands-README warnt ausdrücklich vor diesem Modell. (OpenHands-Betriebsarten)

Eine Docker-Sandbox ist sinnvoll, wenn Sie:

• nur ausgewählte Projektverzeichnisse freigeben möchten,
• Host-Dateien und Agent-Arbeitsbereich trennen müssen,
• Entwicklungsabhängigkeiten reproduzierbarer bereitstellen wollen,
• den Agenten nicht mit dem gesamten Home-Verzeichnis verbinden möchten.

Das Docker-Modell ist jedoch nicht automatisch sicher. Ein gemountetes Verzeichnis bleibt für den Container erreichbar, und falsch gesetzte Volumes können den Schutz praktisch aufheben. Legen Sie deshalb ein dediziertes Projektverzeichnis an und mounten Sie nicht pauschal /, Ihr komplettes Home-Verzeichnis oder Verzeichnisse mit Produktionsschlüsseln. Die OpenHands-README zeigt für den Docker-Betrieb ein begrenztes PROJECTS_PATH und ein separates Konfigurationsverzeichnis. (Docker-Sandbox-Beispiel)

Zweite Phase: API-Key, Dateirechte und Sandbox nach dem ersten Lauf härten

Nach dem ersten erfolgreichen Test müssen Sie die Berechtigungsgrenze beweisen, nicht nur behaupten. Der API-Key schützt den Zugriff auf die Agent-Schnittstelle, ersetzt aber weder eine Firewall noch eine saubere Dateistruktur.

Beachten Sie diese Regeln:

• Schreiben Sie LOCAL_BACKEND_API_KEY nicht in ein öffentliches Repository, keine Frontend-Datei und keine Debug-Ausgabe.
• Legen Sie das Repository in einem dedizierten Arbeitsverzeichnis ab.
• Verwenden Sie für den Agent-Prozess ein eigenes Betriebssystemkonto ohne unnötige Administratorrechte.
• Halten Sie SSH-Schlüssel, Cloud-Credentials und CI/CD-Secrets außerhalb des Agent-Arbeitsverzeichnisses.
• Erlauben Sie nur die Umgebungsvariablen, die der Auftrag wirklich benötigt.
• Prüfen Sie, ob Logs versehentlich Tokens, Header oder vollständige Shell-Befehle mit Geheimnissen enthalten.

Führen Sie anschließend drei negative Tests aus:

1. Bitten Sie den Agenten, eine Datei außerhalb des freigegebenen Projektpfads zu lesen.
2. Senden Sie eine Anfrage ohne gültigen API-Key und prüfen Sie, dass sie abgewiesen wird.
3. Testen Sie einen ungefährlichen, aber klar verbotenen Systembefehl und kontrollieren Sie, ob die gewählte Sandbox- oder Benutzergrenze greift.

Dokumentieren Sie jeweils Anfrage, erwartetes Ergebnis und tatsächliches Ergebnis. Ein grüner UI-Status ist kein Sicherheitsnachweis.

Ist ein Agent Server nach dem SSH-Abbruch noch aktiv?

Ein Agent Server läuft nach dem Ende Ihrer SSH-Sitzung nur dann zuverlässig weiter, wenn Sie ihn unter einem Prozessmanager oder als Systemdienst starten. tmux eignet sich für einen schnellen Test. Für einen dauerhaft betriebenen Dienst ist systemd die bessere Grundlage, weil Sie Startverhalten, Neustart und Boot-Aktivierung festlegen können.

Ein minimales Service-Schema aus der offiziellen Anleitung sieht so aus:

[Unit]
Description=Agent Canvas
After=network.target

[Service]
Environment=LOCAL_BACKEND_API_KEY=<Ihr-gespeicherter-Schlüssel>
ExecStart=npx @openhands/agent-canvas --public
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Danach aktivieren Sie den Dienst:

sudo systemctl daemon-reload
sudo systemctl enable --now agent-canvas
sudo systemctl status agent-canvas

Für die Produktion ergänzen Sie eine kontrollierte Arbeitsumgebung, eine feste Node-Laufzeit, ein definiertes Arbeitsverzeichnis und eine nachvollziehbare Update-Strategie. Verlassen Sie sich nicht darauf, dass npx bei jedem Neustart automatisch exakt dieselbe geprüfte Paketversion verwendet. Prüfen Sie vor einem Update die aktuellen Agent-Canvas-Releases und testen Sie die Änderung zunächst auf einer Kopie der VM.

Dritte Phase: TLS, Reverse Proxy und sichere öffentliche Erreichbarkeit

Für die erste Abnahme reicht ein SSH-Tunnel. Für den Teamzugriff oder die mobile Nutzung benötigen Sie anschließend eine Domain, einen Reverse Proxy und HTTPS. Die offizielle VM-Anleitung beschreibt nginx vor dem lokalen Ingress und nennt Let’s Encrypt als möglichen Zertifikatsweg.

In der dokumentierten Topologie übernimmt nginx die externe TLS-Verbindung. Der interne Ingress verteilt anschließend die Anfragen an Frontend, Agent Server und Automatisierungsbackend. Die in der Dokumentation genannten Beispielports sind 443 für HTTPS, 8000 für den lokalen Ingress, 18000 für den Agent Server, 18001 für die Automatisierung und 3001 für den statischen Server. Diese Werte gehören zur beschriebenen aktuellen Starttopologie; behandeln Sie sie nicht als unveränderliche Produktgarantie. (Architektur und Reverse-Proxy-Pfade)

Für die öffentliche Freigabe gilt:

• DNS muss auf die öffentliche Adresse der VM zeigen.
• Port 80 wird im offiziellen Beispiel für die HTTP-01-Zertifikatsprüfung verwendet.
• Port 443 nimmt den verschlüsselten Zugriff entgegen.
• Interne Ports bleiben an 127.0.0.1 gebunden oder werden durch die Netzwerkfirewall blockiert.
• WebSocket- beziehungsweise Long-Lived-Verbindungen müssen durch den Reverse Proxy weitergereicht werden.
• Die API-Key-Prüfung bleibt auch hinter TLS aktiv.

Welche Ports sollte Ihr Remote Agent Server öffnen? Im Normalfall so wenige wie möglich: SSH aus Ihrem Verwaltungsnetz und für eine öffentliche Browser-Anbindung 80 beziehungsweise 443. Den internen Ingress, Agent Server, Automatisierungsdienst und statischen Server sollten Sie nicht direkt ins Internet stellen. Wenn Sie keinen öffentlichen Zugriff benötigen, bleiben Sie beim SSH-Tunnel oder VPN.

Hinweis: HTTPS verschlüsselt die Verbindung, autorisiert aber nicht automatisch jeden Benutzer. Verwenden Sie zusätzlich Netzwerkfilter, einen starken separaten API-Key und möglichst eine IP- oder VPN-Begrenzung für 443.

Agent Canvas lokal mit dem entfernten Backend verbinden

Wenn die VM stabil läuft, können Sie Ihr lokales Frontend weiterverwenden:

1. Öffnen Sie in der lokalen Oberfläche die Backend-Verwaltung.
2. Legen Sie ein neues Backend mit einem verständlichen Namen an.
3. Tragen Sie die HTTPS-Adresse des Reverse Proxys ein; beim privaten Test genügt die Tunnel-Adresse.
4. Hinterlegen Sie den zugehörigen Session API Key.
5. Warten Sie auf den Status „Connected“.
6. Starten Sie einen Testauftrag im eindeutig ausgewählten Backend.
7. Prüfen Sie Repository-Pfad, Agent-Konfiguration, Logs und Aufgabenhistorie.

Die Trennung zwischen lokalem Frontend und Remote Agent Server ist besonders nützlich, wenn Sie mehrere Umgebungen betreiben: ein lokaler Docker-Backend für ungefährliche Experimente, eine Linux-VM für lange Web- und Backend-Aufgaben sowie ein gesonderter macOS-Knoten für Apple-Builds.

Behalten Sie dabei die Datenbewegung im Blick. Ein lokales Repository mit uncommitteten Änderungen wird durch den Backend-Wechsel nicht auf die VM kopiert. Committen Sie Änderungen, übertragen Sie einen kontrollierten Patch oder nutzen Sie einen abgestimmten Dateitransfer.

Wann Sie zusätzlich einen Remote-Mac brauchen

Ein Remote-Mac ist für OpenHands nicht automatisch die bessere Plattform. Für Codeanalyse, Webserver-Tests, viele Backend-Builds und allgemeine Shell-Aufgaben ist eine Linux-VM meist übersichtlicher zu administrieren und leichter zu reproduzieren.

Ein macOS-Knoten wird sinnvoll, wenn mindestens eine dieser Bedingungen erfüllt ist:

• Xcode muss installiert und verwendet werden.
• Ein iOS- oder macOS-Simulator gehört zum Test.
• Codesignierung, Provisioning-Profile oder Apple-spezifische Buildwerkzeuge sind erforderlich.
• Ein Repository enthält native macOS-Abhängigkeiten, die unter Linux nicht gleichwertig verfügbar sind.
• Der finale Build muss unter macOS ausgeführt und signiert werden.

Die offizielle OpenHands-Dokumentation nennt neben Cloud-VMs auch dedizierte Hardware wie einen Mac Mini als möglichen Host. Das bestätigt die technische Möglichkeit, nicht aber die Notwendigkeit für jedes Projekt. (Unterstützte Host-Modelle)

Führen Sie vor dem Dauerbetrieb einen vollständigen Durchlauf mit Ihrem echten Repository aus: Checkout, Agent-Aufgabe, Build, Test, gegebenenfalls Signierung, kontrollierter Neustart und anschließende Wiederaufnahme. Erst wenn dieser Ablauf nachvollziehbar funktioniert, sollten Sie Aufgaben dauerhaft auf den Mac-Knoten routen.

Entscheidungshilfe vor dem produktiven Einsatz

Bewerten Sie Ihre Umgebung mit dieser Checkliste:

• [ ] Die VM kann unabhängig vom persönlichen Notebook neu gestartet und wiederhergestellt werden.
• [ ] Der erste Zugriff wurde ausschließlich über SSH-Tunnel oder VPN getestet.
• [ ] Ein eigener LOCAL_BACKEND_API_KEY ist gespeichert und nicht in Repository, Frontend oder Logdateien enthalten.
• [ ] SSH, Ingress, Agent Server und Automatisierungsbackend sind durch Firewall-Regeln getrennt.
• [ ] Das Agent-Arbeitsverzeichnis enthält nur die vorgesehenen Projekte.
• [ ] Ein Test auf unerlaubtes Lesen außerhalb des Projektpfads wurde dokumentiert.
• [ ] Ein Request ohne gültigen API-Key wird abgewiesen.
• [ ] Der Prozess startet nach SSH-Abbruch und VM-Neustart automatisch wieder.
• [ ] Logs werden begrenzt, geprüft und ohne sensible Zugangsdaten aufbewahrt.
• [ ] TLS, Zertifikatserneuerung und Weiterleitung langer Ereignisverbindungen wurden getestet.
• [ ] Lokale und entfernte Repository-Stände sind durch Git oder einen definierten Dateitransfer nachvollziehbar.
• [ ] Für Xcode-, Simulator- oder Codesignierungsaufgaben existiert ein eigener macOS-Knoten oder eine begründete Alternative.

Linux-VM, Docker-Sandbox und Remote-Mac im direkten Vergleich

Die Bewertung fällt damit klar aus: Remote-VM 4/5 für allgemeine Agent-Aufgaben, Docker-Sandbox 4/5 für getrennte Projekte, lokaler Rechner 2/5 für Dauerbetrieb und Remote-Mac 5/5 für echte macOS-Buildanforderungen, aber nicht für gewöhnliche Linux-Arbeit.

Wenn Ihre aktuelle Lösung der persönliche Rechner, ein ungeschützter Einzelprozess oder eine unkontrollierte Linux-Cloud-Instanz ist, bleiben drei konkrete Nachteile: Aufgaben brechen beim Ruhezustand ab, Host-Dateien und Secrets sind schwerer zu begrenzen, und Neustarts oder Updates lassen sich ohne Service-Definition kaum reproduzierbar durchführen. In diesem Fall ist die sauberste Reihenfolge nicht „sofort öffentlich machen“, sondern zuerst eine isolierte VM, danach API-Key und Prozessschutz, anschließend TLS und erst am Ende die Auswahl eines zusätzlichen macOS-Knotens. Wenn Ihnen dafür ein dauerhaft erreichbarer Apple-Buildplatz fehlt, können Sie bei SSHMac einen passenden Remote-Mac prüfen; sinnvoll ist das vor allem dann, wenn Ihr Repository tatsächlich Xcode, Simulator oder Codesignierung benötigt.

Für die abschließende Prüfung Ihrer Datenschutz- und Zugriffsregeln können Sie außerdem die Datenschutzinformationen von SSHMac heranziehen. Wenn Sie zunächst nur die Infrastrukturfragen klären möchten, finden Sie weitere Hinweise im SSHMac-Hilfezentrum.