Das --sandbox-Flag startet die CLI mit Isolation auf Betriebssystemebene, setzt die aktiven Berechtigungsbereiche „Read“ und „Write“ auf Betriebssystemebene durch und kann den Netzwerkverkehr optional einschränken.
Wie die Sandbox funktioniert
- Beschreibbare Pfade werden aus den gewährten
Write(...)-Berechtigungsbereichen und dem Workspace-Verzeichnis abgeleitet
- Lesbare Pfade werden aus den gewährten
Read(...)-Bereichen abgeleitet (Plattformstandards wie /usr/bin sind immer lesbar)
- Bereiche, die während einer Sitzung gewährt werden, erweitern die Sandbox dynamisch für nachfolgende Befehle
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.
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.
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.
| Option | Typ | Standard | Beschreibung |
|---|
allowed_domains | string[] | [] | Domain-Muster, die durch den Proxy zugelassen werden. Wenn der Wert nicht leer ist, sind nur übereinstimmende Domains erlaubt (Allowlist-Modus) |
denied_domains | string[] | [] | Domain-Muster, die immer blockiert werden. Sperrregeln haben Vorrang vor Zulassungsregeln |
network_mode | string | "full" | "full" erlaubt alle HTTP-Methoden; "limited" erlaubt nur GET/HEAD/OPTIONS |
| Muster | Entspricht |
|---|
example.com | Nur exakte Übereinstimmungen |
*.example.com | Beliebige Subdomain (nicht die Apex-Domain) |
**.example.com | Apex-Domain und beliebige Subdomains |
{
"sandbox": {
"allowed_domains": [
"github.com",
"**.npmjs.org",
"**.crates.io",
"**.pypi.org"
],
"denied_domains": ["evil.example.com"],
"network_mode": "full"
}
}
Die Domänenfilterung gilt, wenn die Sandbox aktiv ist (--sandbox). Ohne --sandbox wird der Abschnitt zur Sandbox ignoriert.
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:
| Option | Typ | Beschreibung |
|---|
excluded.allow | string[] | Passende Befehle werden automatisch außerhalb der Sandbox ausgeführt |
excluded.ask | string[] | Passende Befehle werden außerhalb der Sandbox ausgeführt, nachdem der Nutzer eine Aufforderung bestätigt hat |
excluded.deny | string[] | Passende Befehle werden nie ausgenommen — sie bleiben immer innerhalb der Sandbox |
{
"sandbox": {
"excluded": {
"allow": ["Exec(git status *)"],
"ask": ["Exec(git push *)"],
"deny": ["Exec(git tag *)"]
}
}
}
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
--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 Lese-/Schreib-Berechtigungsbereiche 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
- 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:
| Szenario | Enterprise-Konfiguration | Nutzerkonfiguration | Effektives Ergebnis |
|---|
| Admin legt Allowlist fest | allowed_domains: ["github.com"] | allowed_domains: ["npmjs.org"] | Nur github.com ist erlaubt (Enterprise ersetzt die Nutzerliste) |
| Admin legt Denylist fest | denied_domains: ["evil.com"] | denied_domains: ["risky.io"] | Sowohl evil.com als auch risky.io sind blockiert (zusammengeführt) |
| Keine Admin-Allowlist | allowed_domains: [] | allowed_domains: ["github.com"] | Die Allowlist des Nutzers wird verwendet |
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
- 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):
{
"excluded": {
"deny": ["Exec(**)"],
"allow": ["Exec(gh *)"]
}
}
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.
