Tutoriel sandbox Claude Code : guide de configuration de /sandbox
Lancez /sandbox, choisissez auto-allow et enfermez chaque commande bash dans une frontière imposée par l'OS — avec les vraies clés settings, pas des légendes. 12 étapes vérifiées contre la doc officielle.
L'essentiel
- La commande /sandbox ouvre un panneau aux onglets Mode, Overrides et Config. Le mode auto-allow exécute les commandes bash sandboxées sans prompt de permission ; regular permissions conserve chaque prompt.
- La frontière est imposée par le noyau, pas par des prompts : Seatbelt sur macOS, bubblewrap sur Linux et WSL2. Windows natif et WSL1 ne sont pas pris en charge.
- Les commandes sandboxées n'écrivent que dans votre répertoire de travail, un répertoire temporaire par utilisateur et les chemins --add-dir. Le trafic réseau passe par un proxy qui ne pré-autorise aucun domaine.
- Les lectures ne sont pas bloquées par défaut — ~/.ssh et ~/.aws restent lisibles jusqu'à l'ajout de règles sandbox.credentials. La boîte de dialogue Sandbox de VS Code est arrivée en v2.1.280.
Claude Code Sandbox Explained
Vidéo:The Art of Vibe Coding4:29
How auto mode works with Claude Code
Vidéo:Claude5:42
Configure the sandboxed Bash tool (official docs)
Docs:code.claude.com
La première vidéo est un explainer en motion design — ses images sur cette page sont des illustrations stylisées, pas des captures d'écran, et certaines affirmations sont corrigées dans les étapes ci-dessous (les identifiants sont lisibles par défaut ; ses exemples de clés settings ne correspondent pas aux vraies). La seconde vidéo est l'enregistrement officiel d'Anthropic ; seuls son vrai terminal et sa vraie interface de réglages sont utilisés.
Faits vérifiés contre code.claude.com/docs/en/sandboxing et le CHANGELOG d'anthropics/claude-code (v2.1.280–2.1.283). Les images citent de brefs extraits des enregistrements à des fins de commentaire.
Configurer la sandbox Claude Code en 12 étapes
Comprendre la frontière
- 1
Reconnaissez le problème de la fatigue d'approbation
Sans sandbox, chaque commande suggérée s'arrête pour un y/n : npm install, git status, puis la suivante. Anthropic a mesuré que 97 % des demandes de permission de Claude Code sont approuvées — c'est précisément pourquoi la sandbox déplace le contrôle hors de chaque commande, vers une frontière que vous configurez une fois.
Une recréation de la boucle y/n par commande que la sandbox remplace — au 47e Entrée, on ne lit plus.Voir à 0:22 - 2
Démarrez Claude Code sur une plateforme prise en charge
Ouvrez une session dans votre projet. Le sandboxing est intégré sur macOS, où Seatbelt fait partie de l'OS et rien n'est à installer. Sur Linux et WSL2, installez d'abord bubblewrap et socat avec votre gestionnaire de paquets. Windows natif et WSL1 ne sont pas pris en charge — les utilisateurs de Windows font tourner Claude Code dans une distribution WSL2.
Une session dans ~/Documents/code/acme — ce répertoire de travail est ce que la sandbox traitera comme inscriptible.Voir à 0:35 - 3
Lancez /sandbox et lisez le panneau
Tapez /sandbox dans la session. Le panneau compte trois onglets : Mode (comment les commandes sandboxées sont approuvées), Overrides (si les commandes en échec peuvent retenter hors sandbox — le réglage allowUnsandboxedCommands) et Config (les réglages de sandbox entièrement résolus). Linux ajoute un onglet Dependencies listant ce qui manque, comme bubblewrap, socat ou le filtre seccomp optionnel. Depuis la v2.1.281, on change d'onglet aux flèches, et VS Code a reçu en v2.1.280 une boîte de dialogue Sandbox pour les mêmes réglages.
L'activer
- 4
Choisissez auto-allow ou regular permissions
Dans l'onglet Mode, auto-allow exécute les commandes sandboxées sans demander, tandis que regular permissions conserve les prompts même pour les commandes sandboxées. Le choix est enregistré dans le .claude/settings.local.json du projet, que Claude Code gitignore pour vous. Pour couvrir tous les projets, mettez "sandbox": undefined dans ~/.claude/settings.json ; pour une seule session, passez-le plutôt avec --settings.
Le démarrage rapide en deux temps : /sandbox choisit le mode, settings.json garde tout ce qui doit durer.Voir à 4:00 - 5
Sachez ce qu'auto-allow demande encore
Auto-allow n'est pas un bouton muet. Les règles deny explicites gagnent toujours, rm ou rmdir visant des chemins critiques demande toujours, et les règles ask à portée de contenu comme Bash(git push *) forcent toujours une confirmation. Les commandes qui ne peuvent pas tourner sandboxées retombent dans le flux normal avec un prompt intitulé "Bash command (unsandboxed)". Auto-allow fonctionne aussi indépendamment de votre mode de permission — le bash sandboxé tourne sans prompts même en mode Manual.
shift+tab fait défiler les modes de permission — une commande distincte de l'auto-allow de la sandbox.Voir à 0:28 - 6
Voyez comment l'OS trace la frontière
Les restrictions sont imposées par le noyau, pas de polies suggestions : macOS utilise Seatbelt, Linux et WSL2 bubblewrap. Une commande injectée par prompt qui tenterait de lire ~/.ssh ou de signaler à l'extérieur heurte le même mur, car les règles lient le processus en cours et chaque enfant qu'il engendre — le modèle ne peut pas parler son chemin à travers le noyau.
Les contrôles de permission au niveau applicatif peuvent être contournés ; la couche noyau, non.Voir à 2:07
Système de fichiers, identifiants et réseau
- 7
Comprenez les défauts du système de fichiers — et le bémol de lecture
Les commandes sandboxées peuvent écrire dans le répertoire de travail et ses sous-répertoires, un répertoire temporaire par utilisateur, et les dossiers ajoutés avec --add-dir ou permissions.additionalDirectories. Les lectures sont ouvertes par défaut : tout le disque est lisible, ~/.aws/credentials et ~/.ssh compris, tant que vous ne l'interdisez pas. Les vidéos explicatives disent souvent que les identifiants deviennent « invisibles » — la doc dit crûment que les protéger est votre affaire, avec sandbox.credentials ou des règles denyRead.
Les écritures s'arrêtent au mur de la sandbox ; les lectures restent ouvertes jusqu'à ce que vous les fermiez à l'étape suivante.Voir à 1:30 - 8
Protégez les identifiants avant de passer en autonome
Ajoutez un bloc sandbox.credentials : listez des fichiers comme ~/.ssh ou ~/.aws/credentials avec "mode": "deny", et des variables d'environnement secrètes comme GITHUB_TOKEN pour qu'elles soient unset dans chaque commande sandboxée. Le mode mask va plus loin — la commande voit une valeur sentinelle et le proxy de la sandbox ne substitue la vraie que sur les hôtes que vous autorisez. Les règles Read de permissions.deny couvrent en plus les outils de fichiers.
Des règles deny pour curl et la lecture de .env — le même fichier settings porte votre bloc sandbox.Voir à 4:35 - 9
Autorisez les domaines réseau dont votre stack a besoin
Tout le trafic sandboxé passe par un proxy, et aucun domaine n'est pré-autorisé. La première fois qu'une commande a besoin d'un hôte, Claude Code demande ; répondez "Yes, and don't ask again" et il enregistre une règle allow WebFetch(domain:...) pour les sessions à venir. Pré-autorisez les registries avec sandbox.network.allowedDomains, bloquez des hôtes précis avec deniedDomains, et activez strictAllowlist pour transformer la liste en plafond dur plutôt qu'en liste de prompts.
Les requêtes vers la registry passent le proxy ; un script postinstall qui téléphone à evil.com, non.Voir à 1:51 - 10
Calez la config : projet, utilisateur ou géré
Les settings de projet dans .claude/settings.json peuvent ajouter des chemins inscriptibles et des domaines, mais ils ne peuvent pas désactiver l'isolation du système de fichiers ni activer Apple Events — ces clés ne sont honorées que depuis les settings utilisateur, gérés ou le drapeau --settings, si bien qu'un dépôt cloné ne peut pas affaiblir votre sandbox. Les équipes imposent la sandbox via les settings gérés avec enabled, failIfUnavailable et allowUnsandboxedCommands à true/false/false.
Un fichier de settings gérés décrit l'environnement de confiance de l'organisation — les admins le posent, les développeurs l'héritent.Voir à 4:10
Vérifier et corriger
- 11
Vérifiez avec une vraie tâche
Demandez un build ou un lancement de tests. Les commandes sandboxées s'exécutent sans prompts, et quand quelque chose est bloqué, la violation nomme le chemin ou l'hôte dans le résultat de la commande, ce qui permet à Claude de s'adapter. Ouvrez l'onglet Config de /sandbox pour lire chaque règle résolue, y compris les chemins protégés qu'aucun réglage ne peut passer outre. Pour un essai strict ponctuel, lancez avec : claude --settings 'undefined}'.
Une tâche tapée, aucun prompt par commande — la frontière tient sans vous.Voir à 0:32 - 12
Dépannez les pannes habituelles
jest se pend — watchman est incompatible, lancez jest --no-watchman. docker échoue — il ne peut pas tourner sandboxé, ajoutez "docker *" à excludedCommands. open ou osascript échoue avec l'erreur -600 sur macOS — Apple Events est bloqué tant que allowAppleEvents n'est pas true. git merge ou checkout échoue avec "unable to unlink old" — un chemin protégé ou une règle denyWrite barre la route ; approuvez la nouvelle tentative hors sandbox ou lancez la commande vous-même. bwrap rapporte Operation not permitted dans un conteneur — activez enableWeakerNestedSandbox. Les pipes vers le presse-papiers passent à côté — utilisez /copy plutôt que pbcopy.
Les réglages sandbox qui comptent
Le panneau /sandbox écrit les bases, mais le vrai levier est dans settings.json. Voici les clés documentées par la référence officielle du sandboxing — toutes vivent sous un bloc "sandbox" (la dernière sous "permissions").
- 1sandbox.enabled — éteint jusqu'à ce que vous basculiez. true dans ~/.claude/settings.json couvre tous vos projets ; le panneau /sandbox écrit la copie locale au projet dans .claude/settings.local.json.
- 2sandbox.autoAllowBashIfSandboxed — l'interrupteur auto-allow, true par défaut. Passez-le à false pour conserver les prompts de permission même pour les commandes tournant dans la sandbox.
- 3sandbox.allowUnsandboxedCommands et sandbox.failIfUnavailable — false sur la première clé tue la nouvelle tentative dangerouslyDisableSandbox (présentée comme Strict sandbox mode dans l'onglet Overrides) ; true sur la seconde transforme les dépendances manquantes en échec de démarrage dur plutôt qu'en avertissement.
- 4sandbox.filesystem — allowWrite pour les chemins hors projet dont les outils ont besoin ("~/.kube", "/tmp/build"), denyRead plus allowRead pour les lieux secrets, et disabled (v2.1.216+) pour retirer la couche système de fichiers tout en gardant l'isolation réseau.
- 5sandbox.network — allowedDomains et deniedDomains, strictAllowlist (v2.1.219+) pour interdire tout ce qui n'est pas listé, allowLocalBinding pour que les serveurs de dev puissent binder leurs ports, et tlsTerminate pour le masquage d'identifiants au proxy.
- 6sandbox.credentials — des entrées fichiers et envVars aux modes deny ou mask ; les masques exigent tlsTerminate et ne sont honorés que depuis des sources user, managed ou --settings. À associer à permissions.blockReadsOutsideWorkingDirectories pour couper toute lecture hors de vos répertoires de travail.
Seatbelt vs bubblewrap : les différences de plateforme
macOS utilise Seatbelt, intégré à l'OS — rien à installer. Les aspérités sont concrètes : les CLIs en Go comme gh, gcloud et terraform peuvent échouer à la vérification TLS sous Seatbelt ; listez-les dans excludedCommands. open, osascript et les flux d'authentification navigateur échouent avec l'erreur -600 tant que allowAppleEvents n'est pas activé — ce qui affaiblit l'isolation et est ignoré dans les settings de projet.
Linux et WSL2 utilisent bubblewrap plus socat, installés via votre gestionnaire de paquets. Le filtre seccomp optionnel (npm install -g @anthropic-ai/sandbox-runtime) ajoute le blocage des sockets de domaine Unix et c'est ce qui permet à WSL2 de tenir les binaires Windows à distance. Ubuntu 24.04 et plus récent embarquent une politique AppArmor qui empêche bubblewrap de créer des espaces de noms utilisateur — ajoutez le profil bwrap de la doc et rechargez AppArmor. Dans un conteneur non privilégié, activez enableWeakerNestedSandbox pour que bubblewrap bind-mount le /proc existant.
WSL1 n'est pas pris en charge du tout — bubblewrap a besoin de fonctionnalités du noyau que seul WSL2 possède. Le surcoût de performance est minime, même si certaines opérations du système de fichiers tournent un peu plus lentement. Les sous-agents tournent dans le même processus que la session parent et héritent de sa configuration de sandbox, donc le bash d'arrière-plan dans un agent est sandboxé aussi.
La gestion de la sandbox bouge encore entre versions : la v2.1.280 a ajouté la boîte de dialogue Sandbox de VS Code, la v2.1.281 a amélioré la navigation d'onglets de /sandbox et l'indice allowLocalBinding pour les serveurs de dev, et les v2.1.282–2.1.283 ont corrigé le matching d'excludedCommands, les écritures TMPDIR et le parsing des settings gérés. Parcourez le CHANGELOG avant de compter sur un comportement de cas limite.