KI-Agent

Wie lässt sich die OpenHands-Sandbox 2026 bereitstellen, um KI-Codieraufgaben vom macOS-Host zu isolieren?

Entscheidung vor dem Start

Docker-Bind-Mounts sind standardmäßig beschreibbar: Ein Prozess im Container kann damit Dateien im eingebundenen Host-Verzeichnis verändern. Das dokumentiert die Docker-Anleitung zu Bind-Mounts. Für die OpenHands-Sandbox bedeutet das: Verwenden Sie bevorzugt den offiziell dokumentierten Container-Ausführungsweg, geben Sie nur den für den Auftrag nötigen Projektordner frei und behandeln Sie diesen Ordner trotz Containerbetrieb als veränderbar. Ein Container ist keine absolute Sicherheitsgrenze; Docker-Socket und Host-Zugangsdaten gehören nicht standardmäßig in die Umgebung.

Diese Anleitung ist für Entwickler gedacht, die OpenHands erstmals auf einem Mac ausführen und dafür Arbeitsverzeichnis, Zugänge und Netzwerkschnittstelle begrenzen möchten.
Engineering-Teams erhalten eine Vorgehensweise, um mehrere Projekte und ihre Zugangsdaten getrennt zu halten.
Verantwortliche für macOS-Anwendungen können damit entscheiden, wo der Agent endet und wo ein separater nativer Build beginnt.

Den Ausführungsweg passend zum Auftrag wählen

OpenHands kann lokal auf dem Rechner betrieben werden oder Agent-Aufgaben in einer Sandbox ausführen. Diese Wege unterscheiden sich darin, welche Teile der Umgebung erreichbar sind und wo die Arbeit tatsächlich stattfindet. Prüfen Sie deshalb vor der Installation die offizielle Übersicht zu OpenHands-Sandbox-Modi und legen Sie fest, welcher Ausführungsweg für den konkreten Auftrag vorgesehen ist.

Für Aufgaben wie Codeänderungen, Tests und das Ausführen von Skripten aus einem nicht vertrauenswürdigen Repository ist ein Container-Sandbox-Ansatz die zweckmäßige Ausgangswahl. Das ist keine Garantie, dass der Mac geschützt ist: Entscheidend bleiben die eingebundenen Pfade, freigegebenen Dienste, Zugangsdaten und Netzwerkeinstellungen. Die OpenHands-Dokumentation beschreibt den vorgesehenen Docker-Ausführungsweg in der Anleitung zur Docker-Sandbox.

Die Dokumentation enthält außerdem einen als V0 gekennzeichneten Docker-Runtime-Pfad. Behandeln Sie diesen nicht ohne Prüfung als aktuelle allgemeine Installationsanleitung. Vergleichen Sie den Abschnitt ausdrücklich mit der aktuellen lokalen Installationsanleitung, bevor Sie Befehle, Umgebungsvariablen oder Image-Angaben übernehmen. Verwenden Sie für eine konkrete Installation die dort dokumentierten Anweisungen und Werte, statt vermeintlich universelle Befehle aus älteren Beiträgen zu kopieren.

Die lokalen Begriffe sollten dabei getrennt bleiben: OpenHands ist die Agent-Anwendung; die Agent-Sandbox ist die Laufumgebung für die Aufgabe; der Docker-Daemon verwaltet Container; der macOS-Host ist der Rechner mit seinen Dateien und Diensten. Ein macOS-nativer Build ist wiederum eine eigene Anforderung. Ein Linux-Container wird nicht dadurch zu einer macOS-Build-Umgebung, dass er auf einem Mac gestartet wird.

Vor der Installation Arbeitsbereich und Vertrauensgrenze festlegen

Erstellen Sie einen eigenen Projektordner für den Auftrag, statt OpenHands direkt auf Ihr Benutzerverzeichnis oder einen übergeordneten Entwicklungsordner anzusetzen. Der freigegebene Pfad sollte nur Dateien enthalten, die der Agent für die konkrete Arbeit benötigt. Lassen Sie persönliche Dokumente, SSH-Schlüssel, Konfigurationsordner, andere Repositories und Daten aus dem Arbeitsalltag außerhalb der Freigabe.

Auf welche Mac-Dateien kann OpenHands zugreifen?
Auf Dateien in Ordnern, die der Laufzeit zur Verfügung gestellt wurden, sowie auf Ressourcen, die über weitere explizite Freigaben oder Dienste erreichbar sind. Containerbetrieb allein gewährt nicht automatisch Zugriff auf das gesamte Dateisystem. Umgekehrt schützt er Dateien innerhalb eines schreibbaren Mounts nicht vor Änderungen durch den Agenten. Prüfen Sie die Freigaben anhand der Docker-Regeln für Bind-Mounts und schreibgeschützte Mounts.

Trennen Sie außerdem Eingabematerial von bearbeitbarem Projektcode. Dokumentationen, Beispielarchive oder Referenzdateien, die der Agent nur lesen muss, können – sofern die verwendete OpenHands-Konfiguration das unterstützt – schreibgeschützt bereitgestellt werden. Für den Code, den der Agent ändern soll, kann ein eigener schreibbarer Projektordner dienen. Ein schreibgeschützter Mount begrenzt die Schreibmöglichkeit in diesem Pfad, hebt aber andere Zugriffswege und Risiken nicht auf.

Hinweis: Prüfen Sie nicht nur, ob der gewünschte Projektordner vorhanden ist. Prüfen Sie auch, ob Elternverzeichnisse, allgemeine Benutzerordner oder zusätzliche Arbeitsbereiche unbeabsichtigt mit freigegeben wurden.

Wie lässt sich OpenHands auf das aktuelle Projekt beschränken?
Wählen Sie bei der Konfiguration ausschließlich den benötigten Projektpfad als Arbeitsbereich und fügen Sie keine pauschale Freigabe des Benutzerverzeichnisses hinzu. Falls weitere Ordner erforderlich sind, begründen und dokumentieren Sie jede Freigabe einzeln. Bei unklarer Pfadauflösung oder einer Konfiguration, die sich nicht eindeutig auf das Projekt begrenzen lässt, brechen Sie den Start ab und klären Sie anhand der aktuellen OpenHands-Dokumentation, welche Mount-Option tatsächlich verwendet wird.

Anforderung Geeignete Konfiguration Vor dem Start prüfen
Agent soll vorhandenen Projektcode ändern Nur den benötigten Projektordner schreibbar bereitstellen Enthält der Ordner ausschließlich für den Auftrag vorgesehene Dateien?
Agent soll Referenzmaterial verwenden, aber nicht ändern Referenzpfad, sofern unterstützt, schreibgeschützt bereitstellen Ist der Mount tatsächlich schreibgeschützt und nicht zusätzlich an anderer Stelle beschreibbar?
Auftrag nutzt ein nicht vertrauenswürdiges Repository Eigenen Arbeitsordner mit klar begrenztem Inhalt verwenden Sind persönliche Dateien, andere Repositories und Zugangsdaten außerhalb des Mounts?
Auftrag benötigt keine Host-Docker-Verwaltung Docker-Socket nicht bereitstellen Gibt es eine nachvollziehbare Anforderung für den Socket-Zugriff?

Container-Zugang und Dienstoberfläche einschränken

Richten Sie die OpenHands-Ausführung nach der aktuell dokumentierten Installations- und Docker-Konfiguration ein. Die offizielle Docker-Sandbox-Anleitung ist die maßgebliche Referenz für die dort beschriebenen Optionen. Image-Bezeichnungen, Parameter und Startanweisungen können sich ändern; übernehmen Sie daher keine unverifizierte Image-Version oder einen älteren Startbefehl allein deshalb, weil er in einem früheren Tutorial funktioniert hat.

Beschränken Sie die Verwaltungsoberfläche auf die Netzwerkschnittstelle, über die sie tatsächlich benötigt wird. Eine lokale Entwicklungsoberfläche sollte nicht ohne begründeten Bedarf öffentlich erreichbar sein. Docker erläutert, dass eine veröffentlichte Container-Schnittstelle an eine Host-Adresse gebunden werden kann; die konkreten Folgen hängen von der gewählten Bindung ab. Prüfen Sie dazu die Dokumentation zur Veröffentlichung von Docker-Ports. Aktivieren Sie keine öffentliche Erreichbarkeit, nur um einen lokalen Verbindungsfehler zu umgehen.

Docker-Socket: Verwaltungsschnittstelle statt Projektfreigabe

Der Docker-Socket ist nicht einfach ein weiterer Zugriff auf den Projektordner. Er verbindet einen Client mit dem Docker-Daemon, der Container verwalten kann. Wer diese Schnittstelle nutzen darf, erhält damit eine andere Art von Kontrolle als ein Agent, der lediglich Dateien in einem begrenzten Arbeitsbereich bearbeitet. Docker weist auf die Schutzbedürftigkeit des Zugangs zum Daemon in seiner Dokumentation zur Absicherung des Docker-Zugriffs hin.

Warum könnte ein OpenHands-Container den Docker-Socket benötigen, und sollte er freigegeben werden?
Ein Zugriff kann für Aufgaben erforderlich sein, bei denen der Agent selbst Docker-Ressourcen verwalten oder Container starten soll. Für gewöhnliche Änderungen an Projektdateien und Tests ist diese Fähigkeit nicht automatisch vorauszusetzen. Gewähren Sie den Zugriff nur, wenn die Aufgabenanforderung ihn ausdrücklich benötigt, die Folgen verstanden sind und eine dafür vorgesehene Konfiguration eingesetzt wird. Ist der Bedarf unklar, bleibt der Socket geschlossen.

Die Trennung hilft auch bei der Fehleranalyse: Wenn eine Aufgabe scheitert, weil ein Container keine weiteren Container starten kann, ist das zunächst eine fehlende Berechtigung – kein Beleg dafür, dass die Berechtigung pauschal erteilt werden sollte. Prüfen Sie, ob sich das Ziel ohne Docker-Daemon-Zugriff erreichen lässt. Wenn nicht, planen Sie diesen Zugriff bewusst als erhöhte Berechtigung und nicht als Standardbestandteil der OpenHands-Sandbox.

Zugangsdaten vor dem ersten Auftrag minimieren

Behandeln Sie Modellzugang, Repository-Zugriff und Dateiberechtigung als getrennte Freigaben. Ein Modellschlüssel erlaubt nicht automatisch den Zugriff auf ein Git-Repository; ein Repository-Token muss dem Agenten nicht Zugriff auf weitere Projekte geben; ein schreibbarer Arbeitsordner ist kein Grund, zusätzlich vertrauliche Dateien einzubinden.

Für private Repositories oder externe Schnittstellen sollten Sie möglichst aufgabenspezifische Zugangsdaten mit den tatsächlich benötigten Berechtigungen verwenden. Legen Sie keine persönlichen, breit berechtigten Schlüssel in Dateien ab, die im Arbeitsbereich liegen oder vom Agenten gelesen werden können. Die Hinweise von GitHub zur sicheren Aufbewahrung von API-Zugangsdaten erläutern die Grundsätze für den Umgang mit solchen Zugangsdaten. Wenn ein GitHub-Token für einen befristeten Auftrag verwendet wird, planen Sie Ablauf und Entzug nach den Hinweisen zu Token-Ablauf und Widerruf.

Auch eine technisch begrenzte Container-Sandbox verhindert nicht, dass ein Agent erreichbare Zugangsdaten verwendet oder über erlaubte Netzwerkverbindungen externe Dienste anspricht. Die Zugangsdaten sollten deshalb in der dafür vorgesehenen Konfiguration der gewählten Installation verwaltet werden, nicht beiläufig in den Projektdateien. Prüfen Sie, ob Protokolle, Ausgaben oder erzeugte Dateien Geheimnisse enthalten könnten, bevor Sie Ergebnisse teilen.

Bei Anforderungen aus Datenschutz und Compliance genügt es nicht, nur den Mount zu dokumentieren. Halten Sie auch fest, welche Daten das Modell, die Anwendung und gegebenenfalls angebundene Dienste erhalten. KuzCloud stellt Informationen zum Umgang mit Daten in der Datenschutzerklärung bereit; die konkrete Prüfung für ein Projekt hängt dennoch von dessen Datenarten, Verträgen und internen Vorgaben ab.

Erster Durchlauf: Verbindungen und Berechtigungen gezielt prüfen

Verwenden Sie für die Inbetriebnahme zunächst ein kleines Projekt ohne vertrauliche Inhalte. Ziel dieses Tests ist nicht die Bewertung der Codequalität, sondern die Überprüfung der Verbindungskette und der Berechtigungsgrenzen. Die folgenden Schritte beziehen sich auf den Ablauf; konkrete Schalter und Befehle müssen Sie aus der aktuellen OpenHands-Dokumentation übernehmen.

  1. Arbeitsordner vorbereiten. Legen Sie ein separates Testprojekt an, das keine vertraulichen Daten und keine nicht benötigten Unterordner enthält. Notieren Sie den Pfad, der als Arbeitsbereich dienen soll.

  2. Ausführungsmodus bestätigen. Öffnen Sie die OpenHands-Dokumentation zum gewählten lokalen oder Docker-basierten Betrieb. Vergewissern Sie sich, dass die Anleitung nicht ausdrücklich als V0- oder Altpfad gekennzeichnet ist, bevor Sie ihre Schritte einsetzen.

  3. Freigaben vor dem Start prüfen. Vergleichen Sie die geplanten Mounts mit dem tatsächlichen Projektbedarf. Entfernen Sie Freigaben für Benutzerverzeichnis, Schlüsselordner, benachbarte Repositories oder andere Host-Daten, wenn der Auftrag sie nicht benötigt.

  4. Dienstoberfläche begrenzen. Kontrollieren Sie, an welche Host-Schnittstelle die Anwendung gebunden wird und welche Verbindungen aus Ihrem Netzwerk erreichbar sind. Stimmen Sie die Einstellung mit der Docker-Dokumentation zur Port-Veröffentlichung ab, statt eine breite Erreichbarkeit als Standard anzunehmen.

  5. Socket und Zugangsdaten kontrollieren. Bestätigen Sie vor dem ersten Start, dass der Docker-Socket nicht ohne begründete Anforderung eingebunden ist. Verwenden Sie für notwendige Modell- oder Repository-Zugänge ausschließlich die für den Test erforderlichen Zugangsdaten.

  6. Einen einfachen Auftrag ausführen. Lassen Sie OpenHands eine kleine, nachvollziehbare Änderung im Testprojekt vorschlagen oder durchführen. Prüfen Sie anschließend, ob die Änderung am erwarteten Ort liegt und keine weiteren, ungeplanten Dateien betroffen sind.

  7. Laufzeit und Restzustand prüfen. Stellen Sie fest, welche Container oder Prozesse nach dem Auftrag weiterlaufen und welche Projektänderungen bestehen bleiben. Vergleichen Sie den Zustand des Testordners mit dem Ausgangszustand und untersuchen Sie Ausgaben auf unbeabsichtigt offengelegte Zugangsdaten.

Prüffrage nach dem Test Erwarteter Befund Bei Abweichung
Ist OpenHands über die vorgesehene Schnittstelle erreichbar? Zugriff entspricht der geplanten lokalen oder internen Nutzung Dienst stoppen und Bindung sowie Port-Konfiguration prüfen
Liegen Änderungen nur im vorgesehenen Arbeitsbereich? Betroffene Dateien sind dem Auftrag zuzuordnen Mounts und weitere Zugriffswege untersuchen
Kann der Agent Docker-Ressourcen verwalten? Nur dann, wenn der Auftrag dies ausdrücklich erfordert Socket-Freigabe entfernen oder Berechtigung gezielt neu bewerten
Sind unerwartete Host-Verzeichnisse erreichbar? Keine nicht benötigten Verzeichnisse sind freigegeben Konfiguration korrigieren und Test mit sauberem Arbeitsbereich wiederholen
Sind Zugangsdaten nach dem Test noch erforderlich? Temporäre Schlüssel werden nicht dauerhaft für weitere Aufträge übernommen Zugangsdaten widerrufen oder rotieren

Erfahrung für Teams: Ein erfolgreicher Start beweist nur, dass die Anwendung erreichbar ist. Erst die Kontrolle der Dateipfade, des Socket-Zugriffs und der nach dem Auftrag verbliebenen Ressourcen zeigt, ob die vorgesehene Grenze tatsächlich umgesetzt wurde.

Nach dem Auftrag aufräumen und Builds getrennt planen

Beenden Sie die Laufzeit nach einem einmaligen Auftrag, wenn sie nicht weiter benötigt wird, und entfernen Sie temporäre Ressourcen nach den für die verwendete OpenHands- und Docker-Konfiguration vorgesehenen Schritten. Bewahren Sie nur die benötigten Codeänderungen auf. Übernehmen Sie diese nach einer Prüfung in den regulären Entwicklungsprozess, statt den gesamten Testzustand ungeprüft als dauerhaft vertrauenswürdig zu behandeln.

Widerrufen oder rotieren Sie temporäre Zugangsdaten, wenn ihr Zweck erfüllt ist. Bei Token und API-Schlüsseln richten Sie sich nach den Regeln des jeweiligen Anbieters. Prüfen Sie außerdem, ob Zugangsdaten in Protokollen, Shell-Verläufen, Projektdateien oder Ergebnissen gelandet sind. Das bloße Entfernen eines Containers ersetzt diese Prüfung nicht.

Für einen macOS-nativen Build ist eine getrennte Ausführungsplanung erforderlich. Wenn OpenHands Xcode oder andere native macOS-Werkzeuge benötigt, darf nicht unterstellt werden, dass der Linux-Container diese Werkzeuge oder eine macOS-Build-Umgebung bereitstellt. Trennen Sie die Bearbeitung des Quellcodes durch den Agenten von der nativen Ausführung und legen Sie fest, welche geprüften Änderungen in die macOS-Build-Umgebung gelangen.

Apples Beschreibung der macOS App Sandbox bezieht sich auf eine Anwendungssicherheitsfunktion mit Berechtigungen und Zugriff auf bestimmte Ressourcen. Sie ist nicht mit einer Docker-Sandbox gleichzusetzen und belegt auch nicht, dass ein Agent-Container dieselben Grenzen hat. Ebenso ist eBPF keine macOS-native Isolationsfunktion, die hier stillschweigend als zusätzliche Container-Schutzschicht angenommen werden könnte.

Entscheidungskriterien für den produktiven Einsatz

Wählen Sie den folgenden Pfad abhängig davon, was der Auftrag tatsächlich benötigt:

  • Wenn OpenHands Code ändern, Tests ausführen oder ein nicht vertrauenswürdiges Repository bearbeiten soll, dann verwenden Sie den offiziell dokumentierten Containerpfad mit einem eigens abgegrenzten Arbeitsordner.
  • Wenn der Agent Referenzdateien nur lesen muss, dann stellen Sie diese – sofern von der gewählten Konfiguration unterstützt – schreibgeschützt und getrennt vom bearbeitbaren Projekt bereit.
  • Wenn ein Auftrag keinen Docker-Container aus einem Container heraus verwalten muss, dann bleibt der Docker-Socket geschlossen.
  • Wenn ein Auftrag Repository- oder API-Zugriff benötigt, dann geben Sie nur aufgabenspezifische Zugangsdaten frei und planen Sie deren Widerruf.
  • Wenn Xcode oder ein anderes natives macOS-Werkzeug nötig ist, dann trennen Sie die Agent-Ausführung von der nativen Build-Umgebung, statt dem Container eine nicht vorhandene macOS-Fähigkeit zuzuschreiben.
  • Wenn Sie die Dateizugriffe, Netzwerkfreigaben oder den Docker-Socket nicht nachvollziehen können, dann geben Sie die Umgebung nicht für vertrauliche oder produktive Daten frei, bis die Konfiguration geklärt ist.

OpenHands ist damit für begrenzte Codeaufgaben einsetzbar, sofern der Arbeitsbereich klein bleibt, Zugänge auf den Auftrag zugeschnitten sind und die Container-Grenze nicht mit vollständigem Host-Schutz verwechselt wird. Bei Bedarf an nativer macOS-Ausführung ist die sachgerechte Ergänzung eine eigens geplante macOS-Umgebung – keine Behauptung, der Docker-Agent könne diese Umgebung ersetzen.

Ein dauerhaft genutzter Entwickler-Mac bringt bei isolierten Agent-Aufträgen wiederkehrende Risiken mit sich: persönliche und projektfremde Dateien liegen möglicherweise in Reichweite, temporäre Zugänge bleiben leicht zurück und eine öffentlich erreichbare Verwaltungsoberfläche kann zur zusätzlichen Angriffsfläche werden. Für einzelne Builds oder getrennte Tests kann eine temporäre Mac-Umgebung diese Vermischung verringern, ohne die Zugriffskontrollen innerhalb der OpenHands-Sandbox zu ersetzen. Wenn ein solcher Einsatz zum Ablauf passt, können Sie die KuzCloud-Umgebung für macOS prüfen; für dauerhaft laufende, stark ausgelastete Arbeitsplätze oder Aufgaben mit erforderlichen physischen Schnittstellen ist eine eigene, kontinuierlich verwaltete Umgebung möglicherweise die passendere Wahl.

KI-Codieraufgaben auf einem dedizierten Mac ausführen

Mit KuzCloud erhalten Sie einen exklusiven Mac mini M4 in der Cloud – getrennt von Ihrem lokalen macOS-Host.

Verbinden Sie sich per SSH oder VNC und richten Sie Ihre Entwicklungsumgebung mit vollem Root-Zugang selbst ein.