Skip to main content
Das --sandbox-Flag startet die CLI mit Isolation auf Betriebssystemebene, setzt beschreibbare Pfade und Sperrregeln auf Betriebssystemebene durch und kann den Netzwerkverkehr optional einschränken.

​
Wie die Sandbox funktioniert

Wenn die Sandbox aktiv ist:
  • Beschreibbare Pfade werden aus den gewährten Write(...)-Berechtigungsbereichen und dem Workspace-Verzeichnis abgeleitet; alles andere ist schreibgeschützt
  • Lesbare Pfade umfassen alle Pfade außer denen, die von Read(...)-Regeln in der deny-Liste abgedeckt werden; diese sind für Befehle in der Sandbox vollständig ausgeblendet
  • Während einer Sitzung gewährte Write(...)-Bereiche erweitern die Sandbox dynamisch für nachfolgende Befehle. Während einer Sitzung erteilte Read(...)-Genehmigungen betreffen nur die eigenen Tools des Agenten – sie können keinen Pfad sichtbar machen, der durch eine Read(...)-deny-Regel ausgeblendet ist, denn dieser bleibt während der gesamten Sitzung ausgeblendet
Wenn die Sandbox nicht ermittelt werden kann (z. B. weil die Sandboxing-Tools auf der Plattform des Nutzers nicht verfügbar sind), startet die CLI nicht, statt ohne Sandbox zu laufen. Dieses Fail-Closed-Verhalten gilt unabhängig davon, ob die Sandbox über eine Teameinstellung oder dadurch aktiviert wurde, dass der Nutzer --sandbox direkt übergibt. So wird sichergestellt, dass die beabsichtigte Sicherheitswirkung nie stillschweigend umgangen wird.Häufige Ursachen dafür, dass die Sandbox nicht ermittelt werden kann:
  • Windows: Sandboxing auf Betriebssystemebene wird unter Windows derzeit nicht unterstützt. Sitzungen unter Windows brechen mit einem harten Fehler ab, wenn --sandbox übergeben wird oder wenn die Sandbox-Erzwingung Required ist, auch dann, wenn die CLI als ACP-Server in einer IDE läuft (z. B. Devin Desktop).
  • Linux: Für Sandboxing müssen bubblewrap (bwrap) und socat installiert sein. Fehlen sie, brechen Sitzungen mit Installationshinweisen ab.
  • Fehler in Berechtigungsbereichen: Ungültige Pfade in Berechtigungsbereichen, die nicht aufgelöst werden können.

​
Netzwerkfilterung

Die Netzwerkfilterung der Sandbox ist derzeit instabil. Wenn Sie diese Funktion benötigen, wenden Sie sich bitte an Ihre zuständige Ansprechperson, um zu erfahren, wann mit einer stabilen Version zu rechnen ist.
Konfigurieren Sie die Netzwerkfilterung auf Domainebene für die Sandbox im sandbox-Abschnitt Ihrer Konfigurationsdatei (nur in der Nutzerkonfiguration). Wenn --sandbox aktiv ist und eine Domänenfilterung konfiguriert wurde, wird auf der Loopback-Schnittstelle ein verwalteter Netzwerk-Proxy gestartet, und die Sandbox erzwingt, dass der gesamte Datenverkehr untergeordneter Prozesse über ihn geleitet wird. Syntax für Domain-Muster: Beispiel:
Die Domänenfilterung gilt, wenn die Sandbox aktiv ist (--sandbox). Ohne --sandbox wird der Abschnitt zur Sandbox ignoriert.

​
Ausgeschlossene Befehle

Manchmal muss ein bestimmter Befehl außerhalb der Sandbox ausgeführt werden — zum Beispiel git-Befehle, die auf Anmeldedaten zugreifen müssen, oder Hooks, die die Sandbox blockiert. Im Konfigurationsabschnitt sandbox.excluded können Sie passende Befehle mithilfe derselben Exec(...)-Regelsyntax wie bei Berechtigungen von der Sandbox-Isolierung ausnehmen: Beispiel:
Regelauflösung: Für jeden Befehl hat innerhalb einer Quelle die spezifischste passende Regel Vorrang (z. B. hat Exec(git push *) Vorrang vor Exec(git *)), und wenn sowohl die Nutzerkonfiguration als auch die Team Settings zutreffen, gilt die restriktivere Entscheidung (deny > ask > allow). Befehle ohne passende Regel — auch wenn sandbox.excluded überhaupt nicht konfiguriert ist — werden immer in der Sandbox ausgeführt.
  • In sandbox.excluded werden nur Exec(...)-Regeln unterstützt; jeder andere Regeltyp (z. B. Read(...), Write(...)) wird mit einer Warnung ignoriert.
  • Ausschlüsse folgen dem Fail-Closed-Prinzip: Wenn ein Befehl nicht sicher ermittelt werden kann (z. B. weil er nicht geparst werden kann), bleibt er in der Sandbox.
  • Ausschlüsse gelten für den Standard-Ausführungspfad pro Befehl. Befehle, die über eine persistente PTY-Shell ausgeführt werden (interaktive Sitzungen oder wenn pty_for_noninteractive_exec aktiviert ist), bleiben immer in der Sandbox.

​
Durchsetzung auf Enterprise-Ebene

Enterprise-Admins können das Sandbox-Verhalten für ihre gesamte Organisation über Team Settings steuern.

​
Sandbox-Erzwingungsmodus

Legen Sie den Erzwingungsgrad für das Flag --sandbox in Ihrer Organisation fest:
  • Optional (Standard) — Nutzer wählen, ob sie --sandbox übergeben. Keine Erzwingung.
  • Required — Das Flag --sandbox wird für alle Nutzer erzwungen, auch wenn sie es nicht in der Befehlszeile angeben. Alle CLI-Sitzungen werden mit einer Dateisystem-Sandbox auf Betriebssystemebene ausgeführt, die beschreibbare Pfade und Read(...)-Sperrregeln erzwingt.
Ein zukünftiger Modus Strict könnte die Sandbox-Konfiguration vollständig sperren und verhindern, dass Nutzer die Sandbox-Einstellungen ändern.
Stellen Sie sicher, dass alle Zielmaschinen bereitgestellt sind, bevor Sie den Sandbox-Erzwingungsmodus in Ihrer Organisation auf Required setzen. Wenn Nutzer Windows verwenden, können sie die CLI erst ausführen, wenn Sandboxing auf Betriebssystemebene unter Windows unterstützt wird oder die Richtlinie auf Optional gelockert wird.

​
Enterprise-Domänenfilterung

Admins können außerdem organisationsweite Allowlists und Denylists für Domains konfigurieren:
  • Domain-Allowlist — Wenn sie festgelegt ist, sind nur die Domains in dieser Liste über den Netzwerk-Proxy der Sandbox erreichbar. Diese Liste ist verbindlich: Sie ersetzt alle vom Nutzer konfigurierten allowed_domains vollständig. Nutzer können keine zusätzlichen Domains hinzufügen, um Admin-Einschränkungen zu umgehen.
  • Domain-Denylist — Domains, die immer blockiert werden. Auf Enterprise-Ebene ausgeschlossene Domains sind additiv: Sie werden mit den lokalen denied_domains des Nutzers zusammengeführt, sodass die kombinierte Liste restriktiver ist.
So wirken Enterprise- und Nutzer-Domainlisten zusammen:
Da die lokalen denied_domains des Nutzers erhalten bleiben und additiv zusammengeführt werden, kann ein Nutzer eine Domain blockieren, die in der Enterprise-Allowlist enthalten ist. Das ist beabsichtigt: Die Gesamtwirkung ist immer restriktiver, nie weniger restriktiv. Falls das zu Zugriffsproblemen führt, sollte der Nutzer den widersprüchlichen Eintrag aus seiner lokalen Konfiguration entfernen.

​
Auf Enterprise-Ebene ausgeschlossene Befehle

Admins können auch organisationsweite Regeln für ausgeschlossene Befehle in den Team Settings festlegen:
  • Ausgeschlossenes allow / ask — Exec(...)-Regeln für Befehle, die organisationsweit außerhalb der Sandbox ausgeführt werden dürfen – automatisch oder nach einer Rückfrage.
  • Ausgeschlossenes deny — Exec(...)-Regeln für Befehle, die niemals außerhalb der Sandbox ausgeführt werden dürfen. Ein Team-deny hat bei übereinstimmenden Befehlen Vorrang vor jedem allow oder ask auf Nutzerebene, sodass Nutzer keine Befehle ausschließen können, die ihre Admins gesperrt haben.
Team- und Nutzerregeln werden gemeinsam ausgewertet: Innerhalb jeder Quelle gewinnt die spezifischste übereinstimmende Regel, und quellenübergreifend gilt die restriktivere Entscheidung (deny > ask > allow). Beispiel: Alle Ausschlüsse außer gh sperren. Ein allgemeines deny mit einer allow-Ausnahme sorgt dafür, dass jeder Befehl außer gh in der Sandbox bleibt – unabhängig davon, was Nutzer lokal konfigurieren. Diese Werte gehören in die excluded-commands-Konfiguration der Team Settings (nicht in die Nutzer-Konfigurationsdatei, daher gibt es keinen umschließenden sandbox-Schlüssel):
Da die spezifischere Regel Exec(gh *) Vorrang vor dem Platzhalter Exec(**) hat, werden gh-Befehle außerhalb der Sandbox ausgeführt, während alles andere innerhalb der Sandbox bleibt — und der Platzhalter deny auf Teamebene überschreibt für andere Befehle alle allow- oder ask-Regeln auf Nutzerebene.

​
Weiterführende Informationen