Claude Code Sandbox: Bash per settings.json einsperren

Die meisten Setups, die mit permissions.allow und ein paar Deny-Regeln laufen, haben dasselbe Problem: Eine Bash-Regel ist ein Textvergleich. Sie sieht den Befehl, den Claude schicken will, aber nicht, was ein erlaubtes npm test oder ein Python-Skript zur Laufzeit wirklich anfasst. Die Sandbox setzt genau dort an. Sie ist eine Grenze, die das Betriebssystem um die Shell-Befehle zieht, die Claude ausführt, und sie gilt auch für alle Prozesse, die diese Befehle starten. Stand dieses Artikels ist die offizielle Doku im Oktober 2026 und Claude Code v2.1.305.

Was die Sandbox begrenzt und was nicht

Die Sandbox ist standardmäßig aus. Einschalten geht über /sandbox in der Session, das schreibt sandbox.enabled nach .claude/settings.local.json im Projekt. Für alle Projekte setzt du den Schlüssel in ~/.claude/settings.json. Unter der Haube nutzt Claude Code das Open-Source-Paket @anthropic-ai/sandbox-runtime: auf macOS Seatbelt, auf Linux und WSL2 bubblewrap plus socat für die Netzwerk-Weiterleitung. Natives Windows läuft ohne Sandbox, dort hilft nur WSL2.

Die Defaults sind bewusst pragmatisch:

• Schreiben: Working Directory, ein Temp-Verzeichnis pro User und Verzeichnisse aus --add-dir bzw. permissions.additionalDirectories.
• Lesen: fast die ganze Maschine, inklusive ~/.ssh und ~/.aws/credentials.
• Netzwerk: kein direkter Weg nach draußen. Alles geht über einen lokalen Proxy, der Hosts gegen allowedDomains prüft, und diese Liste startet leer.
• Umgebungsvariablen: werden geerbt, Secrets eingeschlossen.

Der wichtigste Punkt steht in der Doku eher beiläufig: Die Sandbox umschließt nur Shell-Befehle. Read, Edit, Write, WebFetch, deine Command-Hooks, lokale MCP-Server, die Statuszeile und apiKeyHelper laufen außerhalb mit deinen vollen Rechten. Ein denyRead stoppt das Read-Tool nicht, und allowedDomains begrenzt WebFetch nicht. Für diese Seite brauchst du weiterhin saubere Permission-Regeln. Wer alles hinter eine Grenze setzen will, muss Claude Code selbst in einem Container oder einer VM starten.

Eine Basis-Konfiguration

Eine Konfiguration für die User-Settings, die die typischen Lücken schließt, sieht so aus:

// ~/.claude/settings.json
{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "excludedCommands": ["docker compose *"],
    "filesystem": {
      "allowWrite": ["~/.kube"],
      "denyRead": ["~/.ssh"]
    },
    "network": {
      "allowedDomains": ["github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }],
      "files": [{ "path": "~/.aws/credentials", "mode": "deny" }]
    }
  }
}

failIfUnavailable ist der unterschätzte Schalter. Ohne ihn führt Claude Code Befehle einfach ungesandboxt aus, wenn die Sandbox nicht starten kann, etwa weil bubblewrap fehlt. Prüfen kannst du das Setup, indem du Claude touch ~/sandbox-probe und curl --noproxy '*' https://example.com ausführen lässt. Beides muss scheitern. Tippst du die Befehle selbst am !-Prompt, testest du nichts, denn die laufen in den meisten Sessions außerhalb.

Bei Credentials gibt es keine eingebaute Deny-Liste. Geschützt ist nur, was du einträgst. deny blendet Dateien aus und entfernt Variablen vor jedem Befehl. mask zeigt dem Befehl stattdessen einen Platzhalter, und der Proxy setzt den echten Wert nur bei Requests an erlaubte Hosts ein. Dafür braucht es network.tlsTerminate, das die Doku als experimentell führt, und es zählt nur aus User-, Managed- oder --settings-Quellen, nie aus der Projekt-settings.json.

Auto-allow, Retry und Strict Mode

Standardmäßig ist autoAllowBashIfSandboxed an: Befehle, die in der Sandbox laufen, brauchen keine Freigabe mehr. Deny-Regeln und inhaltliche Ask-Regeln wie Bash(git push *) greifen weiterhin, ein nacktes Bash-Ask wird für gesandboxte Befehle dagegen übersprungen.

Die eigentliche Lücke ist der Retry. Scheitert ein Befehl in der Sandbox, kann Claude ihn mit dangerouslyDisableSandbox außerhalb wiederholen. Wer dann fragt, hängt vom Permission-Mode ab: In bypassPermissions läuft der Retry ohne Prompt, in dontAsk wird er abgelehnt, und eine passende Allow-Regel wie Bash(curl *) genehmigt ihn stillschweigend mit. Mit allowUnsandboxedCommands: false ignoriert Claude Code den Parameter komplett. Ein false in den User-Settings hält seit v2.1.285 auch gegen ein true aus dem Projekt.

excludedCommands ist laut Doku ausdrücklich keine Sicherheitsgrenze, sondern Komfort. Ein Eintrag greift nur, wenn er jeden Befehl im Aufruf abdeckt: npm ci && docker compose build bleibt gesandboxt. Auch cd, Redirections und Command Substitution halten den ganzen Aufruf in der Sandbox. Braucht ein Tool nur einen weiteren Pfad oder Host, ist allowWrite oder allowedDomains die bessere Wahl.

Protected Paths und der neue Namespace-Schalter

Auch im beschreibbaren Working Directory bleiben bestimmte Dateien gesperrt: die .claude-Settings, .claude/hooks, .claude/agents, .claude/skills, .mcp.json, Shell-Startdateien, .gitconfig sowie hooks und config in .git. Der Grund ist simpel: Ein Befehl, der dort schreiben dürfte, könnte sich selbst Rechte geben oder einen Hook oder MCP-Server eintragen, der dann außerhalb der Sandbox läuft. Eine allowWrite-Regel hebt diesen Schutz nicht auf.

Mit v2.1.305 kam sandbox.allowNestedUserNamespaces dazu. Der Schalter erlaubt gesandboxten Befehlen auf Linux und WSL2, User Namespaces zu erzeugen, was Chromium, Electron oder ein verschachteltes bubblewrap brauchen. Die Release Notes sagen offen, dass das die Dateischutz-Mechanismen der Sandbox aushebeln kann. Die Doku wird deutlicher: Mit dem Schlüssel solltest du dich auf keine Einschränkung der Sandbox mehr verlassen, Protected Paths eingeschlossen. Ein true zählt deshalb nur aus User-, Managed- oder --settings-Quellen. Für rootless Podman verweist die Doku stattdessen auf excludedCommands.

Was das für deinen Workflow bedeutet

Die Sandbox ersetzt deine Permission-Regeln nicht, sie ergänzt sie um die Ebene, die Textregeln nicht leisten können. Für ein einzelnes Repo heißt das konkret:

• Sandbox in den User-Settings einschalten, mit failIfUnavailable und allowUnsandboxedCommands: false, damit sie nicht still ausfällt oder umgangen wird.
• Credentials explizit eintragen, weil Lesezugriff auf ~/.ssh und ~/.aws sonst Default ist.
• excludedCommands kurz halten und lieber Pfade oder Domains freigeben.
• Hooks und MCP-Server getrennt absichern, denn sie laufen außerhalb. Für Datenbank-Server zeigt der Beitrag zu MCP-Server Guardrails die passenden Muster.
• Nach jedem Update auf neue Sandbox-Schlüssel achten, wie bei allowNestedUserNamespaces, und den Probe-Test wiederholen.

Unterm Strich: Mit Sandbox kannst du Claude mehr Befehle ohne Prompt laufen lassen, ohne dass ein erlaubtes Kommando unbemerkt mehr tut als gedacht. Voraussetzung ist, dass du weißt, welche Teile deines Setups außerhalb dieser Grenze bleiben.

Du willst wissen, ob deine settings.json Sandbox, Permissions und Hooks sauber zusammenspielen lässt? Fordere ein Agent-Setup-Review für dein Repo an.