Claude-Code-Sandbox-Tutorial: /sandbox richtig einrichten
Starten Sie /sandbox, wählen Sie Auto-Allow und legen Sie jeden Bash-Befehl in eine vom OS erzwungene Grenze — mit den echten Settings-Keys statt Folklore. 12 Schritte, gegen die offizielle Doku geprüft.
Kurz zusammengefasst
- Der /sandbox-Befehl öffnet ein Panel mit den Tabs Mode, Overrides und Config. Der Auto-Allow-Modus führt sandboxed Bash-Befehle ohne Berechtigungs-Prompt aus; Regular Permissions behält jeden Prompt.
- Die Grenze setzt der Kernel durch, nicht Prompts: Seatbelt unter macOS, bubblewrap unter Linux und WSL2. Natives Windows und WSL1 werden nicht unterstützt.
- Sandboxed Befehle dürfen nur in Ihr Arbeitsverzeichnis, ein benutzerbezogenes Temp-Verzeichnis und --add-dir-Pfade schreiben. Netzwerkverkehr läuft über einen Proxy, der keine Domains vorab erlaubt.
- Lesezugriffe sind standardmäßig nicht blockiert — ~/.ssh und ~/.aws bleiben lesbar, bis Sie sandbox.credentials-Regeln ergänzen. Der VS-Code-Sandbox-Dialog kam mit v2.1.280.
Claude Code Sandbox Explained
Video:The Art of Vibe Coding4:29
How auto mode works with Claude Code
Video:Claude5:42
Configure the sandboxed Bash tool (official docs)
Docs:code.claude.com
Das erste Video ist ein Motion-Graphics-Erklärstück — seine Frames auf dieser Seite sind stilisierte Illustrationen, keine Screenshots, und einige Behauptungen werden in den Schritten unten korrigiert (Credentials sind standardmäßig lesbar; die gezeigten Settings-Keys entsprechen nicht den echten). Das zweite Video ist Anthropics offizielle Aufnahme; nur deren echtes Terminal und Settings-UI wird verwendet.
Fakten geprüft gegen code.claude.com/docs/en/sandboxing und das anthropics/claude-code-CHANGELOG (v2.1.280–2.1.283). Standbilder zitieren kurze Ausschnitte aus den Aufnahmen zum Zwecke der Kommentierung.
Die Claude-Code-Sandbox in 12 Schritten einrichten
Die Grenze verstehen
- 1
Das Problem der Genehmigungs-Ermüdung erkennen
Ohne Sandbox stoppt jeder vorgeschlagene Befehl für ein y/n: npm install, git status, dann der nächste. Anthropic hat gemessen, dass 97 % der Claude-Code-Berechtigungsanfragen genehmigt werden — genau deshalb verlagert die Sandbox die Prüfung aus jedem einzelnen Befehl in eine Grenze, die Sie einmal konfigurieren.
Eine Nachstellung der y/n-Schleife pro Befehl, die die Sandbox ersetzt — nach 47 Enter-Tasten liest niemand mehr mit.Ansehen bei 0:22 - 2
Claude Code auf einer unterstützten Plattform starten
Öffnen Sie eine Session in Ihrem Projekt. Sandboxen ist unter macOS eingebaut — Seatbelt kommt mit dem OS, nichts muss installiert werden. Unter Linux und WSL2 installieren Sie zuerst bubblewrap und socat über Ihren Paketmanager. Natives Windows und WSL1 werden nicht unterstützt — Windows-Nutzer betreiben Claude Code in einer WSL2-Distribution.
Eine Session in ~/Documents/code/acme — genau dieses Arbeitsverzeichnis behandelt die Sandbox als beschreibbar.Ansehen bei 0:35 - 3
/sandbox ausführen und das Panel lesen
Tippen Sie /sandbox in der Session. Das Panel hat drei Tabs: Mode (wie sandboxed Befehle genehmigt werden), Overrides (ob scheiternde Befehle unsandboxed wiederholen dürfen — die Einstellung allowUnsandboxedCommands) und Config (die vollständig aufgelösten Sandbox-Settings). Linux ergänzt einen Dependencies-Tab, der alles Fehlende auflistet, etwa bubblewrap, socat oder den optionalen seccomp-Filter. Seit v2.1.281 wechseln Sie mit den Pfeiltasten die Tabs, und VS Code erhielt in v2.1.280 einen Sandbox-Dialog für dieselben Einstellungen.
Einschalten
- 4
Auto-Allow oder Regular Permissions wählen
Im Mode-Tab führt Auto-Allow sandboxed Befehle ohne Rückfrage aus, während Regular Permissions die Prompts auch für sandboxed Befehle behält. Die Wahl wird in die .claude/settings.local.json des Projekts geschrieben, die Claude Code für Sie gitignored. Um alle Projekte abzudecken, setzen Sie "sandbox": undefined in ~/.claude/settings.json; für eine einzelne Session übergeben Sie es stattdessen mit --settings.
Der Zwei-Schritt-Schnellstart: /sandbox wählt den Modus, settings.json hält alles Dauerhafte.Ansehen bei 4:00 - 5
Wissen, was Auto-Allow trotzdem nachfragt
Auto-Allow ist kein Stummschalter. Explizite Deny-Regeln gewinnen immer; rm oder rmdir gegen kritische Pfade fragt weiterhin; inhaltlich gefasste Ask-Regeln wie Bash(git push *) erzwingen weiter eine Bestätigung. Befehle, die nicht sandboxed laufen können, fallen in den normalen Fluss mit einem Prompt namens "Bash command (unsandboxed)" zurück. Auto-Allow arbeitet zudem unabhängig von Ihrem Berechtigungsmodus — sandboxed Bash läuft auch im Manual-Modus ohne Prompts.
shift+tab rotiert durch die Berechtigungsmodi — eine eigene Steuerung, unabhängig vom Auto-Allow der Sandbox.Ansehen bei 0:28 - 6
Sehen, wie das OS die Grenze zieht
Die Beschränkungen setzt der Kernel durch, keine höflichen Empfehlungen: macOS nutzt Seatbelt, Linux und WSL2 bubblewrap. Ein per Prompt-Injection eingeschleuster Befehl, der ~/.ssh lesen oder nach Hause telefonieren will, stößt an dieselbe Wand, denn die Regeln binden den laufenden Prozess und jedes Kind, das er erzeugt — das Modell kann sich am Kernel nicht vorbeireden.
Berechtigungsprüfungen auf Applikationsebene lassen sich umgehen; die Kernel-Ebene nicht.Ansehen bei 2:07
Dateisystem, Credentials und Netzwerk
- 7
Dateisystem-Defaults verstehen — und den Lese-Haken
Sandboxed Befehle dürfen in das Arbeitsverzeichnis samt Unterordnern, ein benutzerbezogenes Temp-Verzeichnis und mit --add-dir oder permissions.additionalDirectories hinzugefügte Ordner schreiben. Lesen ist standardmäßig offen: Die ganze Platte ist lesbar, inklusive ~/.aws/credentials und ~/.ssh, bis Sie es blockieren. Erklärvideos behaupten gern, Credentials würden „unsichtbar“ — die Doku sagt ungeschönt, dass sie zu schützen Ihre Aufgabe ist, mit sandbox.credentials oder denyRead-Regeln.
Schreibvorgänge stoppen an der Sandbox-Wand; Lesezugriffe bleiben offen, bis Sie sie im nächsten Schritt schließen.Ansehen bei 1:30 - 8
Credentials schützen, bevor es autonom wird
Ergänzen Sie einen sandbox.credentials-Block: Listen Sie Dateien wie ~/.ssh oder ~/.aws/credentials mit "mode": "deny" auf, dazu geheime Umgebungsvariablen wie GITHUB_TOKEN, damit sie in jedem sandboxed Befehl unset sind. Der Mask-Modus geht weiter — der Befehl sieht einen Sentinel-Wert, und der Sandbox-Proxy setzt den echten nur auf Hosts ein, die Sie erlauben. permissions.deny-Read-Regeln kommen obendrein für die Datei-Tools dazu.
Deny-Regeln für curl und .env-Lesezugriffe — dieselbe Settings-Datei trägt auch Ihren Sandbox-Block.Ansehen bei 4:35 - 9
Die Netzwerk-Domains Ihres Stacks erlauben
Gesamter sandboxed Verkehr läuft über einen Proxy, und keine Domain ist vorab erlaubt. Braucht ein Befehl erstmals einen Host, fragt Claude Code nach; antworten Sie "Yes, and don't ask again", speichert es eine WebFetch(domain:...)-Allow-Regel für künftige Sessions. Erlauben Sie Registries vorab mit sandbox.network.allowedDomains, blockieren Sie einzelne Hosts mit deniedDomains, und setzen Sie strictAllowlist, um aus der Liste eine harte Obergrenze statt einer Prompt-Liste zu machen.
Registry-Fetches passieren den Proxy; ein postinstall-Skript, das zu evil.com telefoniert, nicht.Ansehen bei 1:51 - 10
Den Scope setzen: Projekt, User oder Managed
Projekt-Settings in .claude/settings.json dürfen beschreibbare Pfade und Domains ergänzen, aber sie können die Dateisystem-Isolation nicht abschalten oder Apple Events aktivieren — diese Keys werden nur aus User-Settings, Managed-Settings oder dem --settings-Flag geehrt, sodass ein ausgechecktes Repo Ihre Sandbox nicht schwächen kann. Teams erzwingen die Sandbox über Managed-Settings mit enabled, failIfUnavailable und allowUnsandboxedCommands auf true/false/false.
Eine Managed-Settings-Datei beschreibt die vertrauenswürdige Umgebung der Organisation — Admins setzen sie, Developer erben sie.Ansehen bei 4:10
Verifizieren und korrigieren
- 11
Mit einer echten Aufgabe verifizieren
Bitten Sie um einen Build oder einen Testlauf. Sandboxed Befehle laufen ohne Rückfragen, und wenn etwas blockiert wird, nennt die Verletzung Pfad oder Host im Ergebnis des Befehls, sodass Claude sich anpassen kann. Öffnen Sie den Config-Tab von /sandbox, um jede aufgelöste Regel zu lesen, inklusive der geschützten Pfade, die keine Einstellung überschreiben kann. Für einen einmaligen Strict-Test starten Sie mit: claude --settings 'undefined}'.
Eine getippte Aufgabe, keine Prompts pro Befehl — die Grenze hält auch ohne Sie.Ansehen bei 0:32 - 12
Die üblichen Fehler troubleshooten
jest hängt — watchman ist inkompatibel, starten Sie jest --no-watchman. docker scheitert — es kann nicht sandboxed laufen, nehmen Sie "docker *" in excludedCommands auf. open oder osascript schlägt unter macOS mit Fehler -600 fehl — Apple Events sind blockiert, solange allowAppleEvents nicht true ist. git merge oder checkout scheitert mit "unable to unlink old" — ein geschützter Pfad oder eine denyWrite-Regel ist im Weg; genehmigen Sie den unsandboxed Retry oder führen Sie den Befehl selbst aus. bwrap meldet Operation not permitted im Container — setzen Sie enableWeakerNestedSandbox. Clipboard-Pipes kommen leer an — nutzen Sie /copy statt pbcopy.
Die Sandbox-Settings, die zählen
Das /sandbox-Panel schreibt die Basics, aber der echte Hebel liegt in settings.json. Das sind die Keys, die die offizielle Sandboxing-Referenz dokumentiert — alle leben unter einem "sandbox"-Block (der letzte unter "permissions").
- 1sandbox.enabled — aus, bis Sie umschalten. true in ~/.claude/settings.json deckt alle Ihre Projekte ab; das /sandbox-Panel schreibt die projektlokale Kopie in .claude/settings.local.json.
- 2sandbox.autoAllowBashIfSandboxed — der Auto-Allow-Schalter, standardmäßig true. Auf false bleiben Berechtigungs-Prompts auch für Befehle innerhalb der Sandbox.
- 3sandbox.allowUnsandboxedCommands und sandbox.failIfUnavailable — false am ersten Key killt den dangerouslyDisableSandbox-Retry (im Overrides-Tab als Strict sandbox mode gezeigt); true am zweiten macht fehlende Abhängigkeiten zu einem harten Startfehler statt einer Warnung.
- 4sandbox.filesystem — allowWrite für Pfade außerhalb des Projekts, die Tools brauchen ("~/.kube", "/tmp/build"), denyRead plus allowRead für geheime Orte, und disabled (v2.1.216+), um die Dateisystem-Schicht abzugeben und die Netzwerk-Isolation zu behalten.
- 5sandbox.network — allowedDomains und deniedDomains, strictAllowlist (v2.1.219+), um alles Ungelist zu verbieten, allowLocalBinding, damit Dev-Server Ports binden können, und tlsTerminate für Credential-Masking am Proxy.
- 6sandbox.credentials — Datei- und envVars-Einträge mit deny oder mask; Masks verlangen tlsTerminate und werden nur aus User-, Managed- oder --settings-Quellen geehrt. Kombinieren Sie es mit permissions.blockReadsOutsideWorkingDirectories, um alle Lesezugriffe außerhalb Ihrer Arbeitsverzeichnisse zu kappen.
Seatbelt vs. bubblewrap: Plattform-Unterschiede
macOS nutzt Seatbelt, das im OS steckt — nichts zu installieren. Die rauen Kanten sind konkret: Go-basierte CLIs wie gh, gcloud und terraform scheitern unter Seatbelt bisweilen an der TLS-Verifizierung; führen Sie sie in excludedCommands. open, osascript und Browser-Auth-Flows scheitern mit Fehler -600, bis Sie allowAppleEvents setzen — was die Isolation schwächt und in Projekt-Settings ignoriert wird.
Linux und WSL2 nutzen bubblewrap plus socat, installiert über den Paketmanager. Der optionale seccomp-Filter (npm install -g @anthropic-ai/sandbox-runtime) ergänzt das Blockieren von Unix-Domain-Sockets und lässt WSL2 Windows-Binaries draußen halten. Ubuntu 24.04 und neuer bringen eine AppArmor-Policy mit, die bubblewrap an User-Namespaces hindert — ergänzen Sie das bwrap-Profil aus der Doku und laden Sie AppArmor neu. In einem unprivilegierten Container setzen Sie enableWeakerNestedSandbox, damit bubblewrap das vorhandene /proc bind-mountet.
WSL1 wird gar nicht unterstützt — bubblewrap braucht Kernel-Features, die nur WSL2 hat. Der Performance-Overhead ist minimal, wenn auch manche Dateisystem-Operationen etwas langsamer laufen. Subagenten laufen im selben Prozess wie die Parent-Session und erben deren Sandbox-Konfiguration — Hintergrund-Bash innerhalb eines Agenten ist also auch sandboxed.
Das Sandbox-Handling bewegt sich weiterhin zwischen Releases: v2.1.280 brachte den VS-Code-Sandbox-Dialog, v2.1.281 verbesserte die /sandbox-Tab-Navigation und den allowLocalBinding-Hinweis für Dev-Server, und v2.1.282–2.1.283 fixten excludedCommands-Matching, TMPDIR-Schreibvorgänge und das Parsen von Managed-Settings. Werfen Sie einen Blick ins CHANGELOG, bevor Sie sich auf Randfall-Verhalten verlassen.