SpyBara
Go Premium

sandboxing.md 2026-10-01 23:59 UTC to 2026-10-02 06:02 UTC

This page contains 587 additions and 288 deletions.

2026
Fri 2 07:00

Configurer l'outil Bash en sandbox

Restreignez les fichiers et les hôtes réseau auxquels les commandes shell de Claude Code peuvent accéder grâce au sandbox intégré. Activez-le, définissez ses limites et corrigez ce qu'il empêche de fonctionner.

Le sandbox Bash est une frontière que le système d'exploitation impose autour des commandes shell que Claude exécute sur votre machine. Vous définissez les fichiers et les domaines réseau auxquels ces commandes peuvent accéder, et les restrictions s'appliquent aux commandes Bash, PowerShell et Monitor ainsi qu'aux processus qu'elles lancent. Comme le système d'exploitation applique ces restrictions pendant l'exécution d'une commande, Claude Code peut exécuter des commandes en sandbox sans vous demander d'approuver chacune d'elles.

Le sandbox couvre uniquement les commandes shell. Les outils de fichiers de Claude, les serveurs MCP et les hooks s'exécutent en dehors de celui-ci.

Le sandbox fonctionne sur macOS, Linux et WSL2. Sous Windows natif, Claude Code exécute les commandes sans sandbox. Pour utiliser le sandbox sur une machine Windows, exécutez Claude Code dans une distribution WSL2.

Ce que le sandbox restreint

Lorsque le sandbox est activé, les commandes shell que Claude exécute démarrent à l'intérieur de ses limites, tout comme les processus qu'elles lancent. Le sandbox est désactivé par défaut. Pour l'activer, exécutez /sandbox dans une session, comme le montre Démarrer, ou définissez sandbox.enabled sur true dans un fichier de paramètres tel que ~/.claude/settings.json.

Le tableau indique ce à quoi une commande exécutée dans le sandbox peut accéder par défaut, ainsi que les paramètres qui modifient chaque valeur par défaut.

Accès Par défaut Modifier avec
Écritures Le répertoire de travail, un répertoire temporaire propre à chaque utilisateur et les répertoires que vous avez ajoutés. Les chemins protégés restent interdits en écriture filesystem.allowWrite, filesystem.denyWrite
Lectures La majeure partie de la machine, y compris les fichiers d'identifiants tels que ~/.ssh et ~/.aws/credentials filesystem.denyRead, credentials
Réseau Aucune route directe vers l'extérieur. Les connexions passent par un proxy sur votre machine qui vérifie chaque hôte par rapport à vos domaines autorisés, dont la liste est vide au départ. Votre mode de permission détermine ce qu'il advient des autres hôtes network.allowedDomains, network.deniedDomains
Variables d'environnement Héritées de Claude Code, y compris les éventuels secrets présents dans son environnement credentials, CLAUDE_CODE_SUBPROCESS_ENV_SCRUB

Claude Code s'appuie, pour le sandbox, sur le package open source @anthropic-ai/sandbox-runtime.

Ce qui s'exécute en dehors du sandbox

Le sandbox encapsule les commandes shell. Les outils et processus suivants s'exécutent en dehors de celui-ci :

  • Outils intégrés de fichiers et web : les outils tels que Read, Edit, Write, WebFetch et WebSearch suivent plutôt les règles de permission. Une entrée denyRead n'empêche pas l'outil Read, et allowedDomains ne limite pas WebFetch
  • Autres processus lancés par Claude Code : les hooks de commande, les serveurs MCP locaux, les moniteurs de plugins, les serveurs LSP et les commandes auxiliaires telles que votre commande de barre de statut et apiKeyHelper s'exécutent avec votre accès complet

Certaines commandes shell s'exécutent également en dehors du sandbox, selon vos paramètres :

Pour placer les outils, processus et commandes de cette section derrière une seule limite, exécutez le processus Claude Code lui-même dans un conteneur, une machine virtuelle ou le runtime du sandbox.

Démarrer

Le sandbox est intégré à Claude Code. Ce que vous installez dépend de votre plateforme :

  • macOS : le sandboxing utilise le framework Seatbelt intégré, vous pouvez donc passer directement aux étapes
  • Linux et WSL2 : le sandbox s'appuie sur bubblewrap et socat, décrits dans Configurer Linux et WSL2. Même si vous ne les avez pas encore installés, vous pouvez commencer avec /sandbox, car son panneau indique s'il manque quelque chose
1

Exécuter /sandbox

Démarrez une session Claude Code et exécutez la commande /sandbox :

/sandbox

Cela ouvre le panneau du sandbox avec trois onglets, plus un onglet Dependencies sous Linux lorsque le filtre seccomp facultatif est absent :

  • Mode : choisissez comment les commandes en sandbox sont approuvées, comme décrit à l'étape suivante
  • Overrides : choisissez si les commandes qui échouent dans le sandbox peuvent se rabattre sur une exécution hors sandbox. Il s'agit du paramètre allowUnsandboxedCommands
  • Config : affichez les paramètres du sandbox résolus

Si le panneau n'affiche qu'un onglet Dependencies, un paquet requis est manquant. Installez-le comme décrit dans Configurer Linux et WSL2, redémarrez Claude Code, puis exécutez à nouveau /sandbox.

2

Choisir un mode

Dans l'onglet Mode, sélectionnez l'approbation automatique ou les permissions standard. L'approbation automatique exécute les commandes en sandbox sans demande, tandis que les permissions standard conservent les demandes de permission habituelles même lorsque les commandes sont en sandbox. Consultez Modes du sandbox pour savoir quelles commandes déclenchent encore une demande en mode d'approbation automatique.

3

Exécuter une commande Bash

Demandez à Claude d'exécuter une commande, comme un build ou une suite de tests. Par défaut, les commandes dans le sandbox peuvent écrire dans le répertoire de travail, dans un répertoire temporaire propre à l'utilisateur et dans tous les répertoires que vous avez ajoutés avec --add-dir, /add-dir ou permissions.additionalDirectories.

La première fois qu'une commande a besoin d'un nouveau domaine réseau, Claude Code vous demande votre approbation ; en mode auto, Claude indique plutôt les hôtes dont une commande a besoin sur la commande elle-même, afin que le classifieur les examine avec elle.

Pour élargir ou restreindre ce que le sandbox autorise, consultez Configurer le sandboxing.

Si des commandes en sandbox échouent avec Operation not permitted dans un conteneur, consultez Bubblewrap ne démarre pas dans un conteneur.

Lorsque vous sélectionnez un mode dans le panneau, Claude Code l'enregistre dans les paramètres locaux de votre projet, dans .claude/settings.local.json, qui s'appliquent au projet en cours. Claude Code ajoute ce fichier à votre gitignore global lorsqu'il y enregistre un paramètre. Pour activer le sandbox dans tous vos projets, définissez sandbox.enabled sur true dans vos paramètres utilisateur, dans ~/.claude/settings.json. Pour imposer le sandboxing à tous les développeurs d'une organisation, utilisez les paramètres gérés.

Pour modifier le sandbox le temps d'une session sans écrire dans un fichier de paramètres, démarrez Claude Code avec --settings. Par exemple, cette commande démarre une session en sandbox dans laquelle Claude ne peut pas réessayer une commande bloquée en dehors du sandbox :

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

Vérifier que les commandes s'exécutent dans le sandbox

Pour vérifier que le sandbox fonctionne, demandez à Claude d'exécuter chaque ligne du tableau. Ce que vous saisissez à l'invite ! s'exécute généralement en dehors du sandbox ; saisir une ligne vous-même ne permet donc pas de le tester.

Commande Résultat dans le sandbox
touch ~/sandbox-probe Échoue avec Operation not permitted sous macOS, ou Read-only file system sous Linux et WSL2
curl --noproxy '*' https://example.com Échoue avec Could not resolve host, car la commande n'a aucun moyen de contourner le proxy du sandbox

Si Claude demande à réessayer une commande ayant échoué en dehors du sandbox, refusez la nouvelle tentative. Si touch réussit et que votre répertoire personnel ne fait pas partie des répertoires dans lesquels le sandbox autorise les commandes à écrire, supprimez ~/sandbox-probe. Exécutez ensuite /sandbox pour vérifier que le sandbox est activé et que ses dépendances sont installées.

Configurer Linux et WSL2

Sous Linux et WSL2, le sandbox s'appuie sur ces paquets :

  • bubblewrap : l'outil de sandboxing non privilégié qui applique l'isolation du système de fichiers
  • socat : le relais utilisé pour acheminer le trafic réseau via le proxy du sandbox

Installez-les avec le gestionnaire de paquets de votre distribution :

sudo apt-get install bubblewrap socat

Lorsqu'une dépendance est manquante, l'onglet Dependencies de /sandbox indique lesquels parmi ripgrep, bubblewrap, socat et le filtre seccomp manquent sur votre plateforme. Si vous ne voyez pas cet onglet après l'installation et le redémarrage de Claude Code, toutes les dépendances sont présentes.

Ripgrep est fourni avec le binaire natif de Claude Code. Le filtre seccomp est facultatif et ajoute le blocage des sockets de domaine Unix. Installez-le avec npm install -g @anthropic-ai/sandbox-runtime s'il est absent.

Lorsqu'une dépendance requise est manquante, l'onglet Dependencies est le seul onglet affiché jusqu'à ce que vous l'installiez. Lorsque seul le filtre seccomp facultatif est absent, l'onglet Dependencies apparaît à côté des autres onglets. La vérification des dépendances s'exécute au démarrage ; redémarrez donc Claude Code après avoir installé des paquets pour que /sandbox les détecte.

Sous Ubuntu 24.04 et versions ultérieures, la politique AppArmor par défaut empêche bubblewrap de créer les espaces de noms utilisateur dont il a besoin pour l'isolation. 
Pour vérifier si votre environnement applique cette restriction, y compris dans WSL2, exécutez `sysctl kernel.apparmor_restrict_unprivileged_userns`. Si la commande renvoie `0`, ignorez cette étape. Si elle affiche une erreur `No such file or directory`, la clé n'existe pas et vous pouvez ignorer cette étape. Si elle renvoie `1`, ajoutez un profil AppArmor qui accorde cette capacité à `bwrap` :

```bash theme={null}
sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
```

Le profil s'applique uniquement à `bwrap` lui-même, et non aux commandes qu'il exécute dans le sandbox. Rechargez AppArmor pour l'appliquer :

```bash theme={null}
sudo systemctl reload apparmor
```
Remarques sur WSL2

Vérifiez votre version de WSL avec wsl -l -v depuis PowerShell. Si vous voyez Sandboxing requires WSL2, votre distribution s'exécute sous WSL1. Passez-la à WSL2 ou exécutez Claude Code sans sandboxing.

Sous WSL2, WSL transmet le lancement d'un binaire Windows tel que cmd.exe, powershell.exe ou tout élément situé sous /mnt/c/ à l'hôte Windows via un socket Unix ; la possibilité pour une commande en sandbox d'en lancer un dépend donc des paramètres de socket Unix du sandbox : le filtre seccomp facultatif doit être installé pour que le socket puisse être bloqué. Pour autoriser ces lancements, définissez allowAllUnixSockets, qui ouvre tous les sockets Unix aux commandes en sandbox.

Modes du sandbox

Claude Code propose deux modes de sandbox. Dans les deux cas, le sandbox applique les mêmes restrictions sur le système de fichiers et le réseau ; la seule différence réside dans le fait que les commandes en sandbox sont approuvées automatiquement ou nécessitent une permission explicite.

Mode d'approbation automatique

Claude Code approuve automatiquement une commande, sans demande, lorsqu'elle s'exécute dans le sandbox. Une commande passe par le flux de permission standard lorsqu'elle s'exécute en dehors du sandbox, parce qu'elle correspond à excludedCommands ou parce que Claude la réessaie hors sandbox.

Une commande en sandbox qui se connecte à un hôte que vous n'avez pas autorisé reste dans le sandbox. Hôtes en dehors de vos domaines autorisés explique qui décide si la connexion aboutit.

Même en mode d'approbation automatique, les éléments suivants s'appliquent toujours :

  • Les règles de refus explicites sont toujours respectées
  • Les commandes rm ou rmdir qui ciblent un chemin critique passent toujours par le flux de permission standard
  • Les règles de demande ciblant un contenu, comme Bash(git push *), imposent toujours une demande, même pour les commandes en sandbox
  • Une règle de demande Bash seule, ou sa forme équivalente Bash(*), est ignorée pour les commandes exécutées en sandbox ; elle s'applique toujours aux commandes qui se rabattent sur le flux de permission standard. En mode plan, la règle n'est pas ignorée : elle déclenche aussi une demande pour les commandes en sandbox, y compris celles en lecture seule

Mode de permissions standard

Toutes les commandes Bash passent par le flux de permission standard, même lorsqu'elles sont en sandbox. Cela offre davantage de contrôle, mais nécessite plus d'approbations.

L'échappatoire de la nouvelle tentative hors sandbox

La nouvelle tentative hors sandbox est une échappatoire pour les commandes qui échouent dans le sandbox, comme les outils incompatibles avec celui-ci. Lorsque le sandbox bloque une connexion réseau, Claude Code indique l'hôte refusé dans le résultat de la commande, afin que Claude voie ce qui a été bloqué. Claude analyse l'échec et peut réessayer la commande avec le paramètre dangerouslyDisableSandbox.

La commande réessayée s'exécute hors sandbox. Dans une session de terminal interactive, la personne ou l'élément qui l'approuve dépend de votre mode de permission :

  • Mode bypassPermissions : la nouvelle tentative s'exécute sans demande
  • Mode Manual et mode acceptEdits : vous recevez une demande intitulée « Bash command (unsandboxed) »
  • Mode auto : un modèle classifieur distinct évalue la commande sous-jacente
  • Mode dontAsk : Claude Code refuse la nouvelle tentative
  • Mode plan : consultez comment Claude Code contrôle les commandes pendant que vous planifiez

Ces règles et paramètres modifient qui approuve la nouvelle tentative :

  • Une règle d'autorisation correspondante : si une règle d'autorisation telle que Bash(curl *) correspond à la commande, elle approuve également la nouvelle tentative ; la commande s'exécute donc en dehors du sandbox sans demande
  • Une règle de demande pour le paramètre : ajoutez une règle de demande pour Bash(dangerouslyDisableSandbox:true) afin de recevoir une demande lors des nouvelles tentatives Bash. Vous recevez la demande en mode auto et en mode bypassPermissions également, et la règle a priorité sur une règle d'autorisation correspondante
  • permissions.blockReadsOutsideWorkingDirectories : Actions qu'aucun mode n'approuve automatiquement décrit les nouvelles tentatives qui déclenchent une demande lorsque ce paramètre est activé

Désactiver la nouvelle tentative avec le mode sandbox strict

Vous pouvez désactiver la nouvelle tentative hors sandbox en définissant "allowUnsandboxedCommands": false dans vos paramètres du sandbox. Lorsque la nouvelle tentative est désactivée, Claude Code ignore le paramètre dangerouslyDisableSandbox. Tant que le sandbox fonctionne, les commandes exécutées par Claude sont alors en sandbox, sauf si elles correspondent à une entrée excludedCommands. Pour empêcher Claude Code d'exécuter des commandes hors sandbox lorsque le sandbox ne peut pas démarrer, définissez également failIfUnavailable. L'onglet Overrides de /sandbox affiche ce paramètre sous le nom Strict sandbox mode.

Une valeur false dans vos paramètres utilisateur, dans --settings ou dans les paramètres gérés s'applique même lorsque les paramètres d'un projet définissent true. Une valeur false dans vos paramètres utilisateur ne rend pas le sandbox imposé par l'administrateur ; les autres paramètres du sandbox d'un projet s'appliquent donc toujours. Avant la v2.1.285, une valeur true d'un projet remplaçait une valeur false de vos paramètres utilisateur.

Si vous ou votre administrateur désactivez la nouvelle tentative dans les paramètres gérés ou avec le flag --settings, le sandbox devient imposé par l'administrateur. Claude Code ignore alors les paramètres des fichiers d'un dépôt qui assouplissent le sandbox, y compris les entrées excludedCommands. Paramètres du dépôt avec un sandbox imposé par l'administrateur les répertorie.

Le mode sandbox strict s'applique aux commandes exécutées par Claude. Les commandes que vous saisissez vous-même à l'invite du mode shell ! s'exécutent en dehors du sandbox, sauf si la session fait partie des cas suivants :

Avant la v2.1.260, le mode sandbox strict plaçait en sandbox les commandes du mode shell dans toutes les sessions.

Répertoires temporaires

Un répertoire temporaire propre à l'utilisateur est accessible en écriture dans le sandbox par défaut, en plus du répertoire de travail. Sauf si vous désactivez l'isolation du système de fichiers, Claude Code définit $TMPDIR sur ce répertoire pour les commandes en sandbox, afin que les outils qui écrivent des fichiers temporaires fonctionnent sans configuration supplémentaire.

Les commandes hors sandbox héritent du $TMPDIR de votre shell lorsqu'il est défini ; ainsi, tant que l'isolation du système de fichiers est activée, les commandes en sandbox et hors sandbox résolvent $TMPDIR vers des répertoires différents. Si votre shell laisse $TMPDIR non défini ou vide, une commande hors sandbox qui fait référence à $TMPDIR reçoit votre valeur de remplacement CLAUDE_CODE_TMPDIR, ou le répertoire temporaire du système d'exploitation si vous n'en avez pas défini ou si la valeur de remplacement est un chemin long, de sorte que la variable ne se développe pas en chaîne vide. Pour échanger des fichiers temporaires entre les deux, écrivez-les plutôt dans le répertoire de travail.

Configurer le sandboxing

Personnalisez le comportement du sandbox via votre fichier settings.json. Consultez Paramètres pour la référence complète de configuration.

Par défaut, les commandes en sandbox peuvent écrire dans le répertoire de travail actuel, dans le répertoire temporaire propre à l'utilisateur et dans tous les répertoires que vous avez ajoutés avec --add-dir, /add-dir ou permissions.additionalDirectories. Si des commandes de sous-processus comme kubectl, terraform ou npm doivent écrire en dehors de ces répertoires, utilisez sandbox.filesystem.allowWrite pour accorder l'accès à des chemins spécifiques :

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

Ces chemins sont appliqués au niveau du système d'exploitation, de sorte que toutes les commandes exécutées dans le sandbox, y compris leurs processus enfants, les respectent. C'est l'approche recommandée lorsqu'un outil a besoin d'un accès en écriture à un emplacement spécifique, plutôt que d'exclure entièrement l'outil du sandbox avec excludedCommands.

Lorsque vous définissez le même tableau de système de fichiers dans plusieurs portées de paramètres, Claude Code les fusionne, en combinant les chemins de chaque portée plutôt qu'en remplaçant le tableau d'une portée par celui d'une autre.

Si vous excluez une source avec --setting-sources dans la CLI ou settingSources dans l'Agent SDK, Claude Code ignore ses entrées sandbox.filesystem, ses règles de permission Edit et ses règles de refus Read lors de la construction de la configuration du sandbox. Nécessite Claude Code v2.1.246 ou une version ultérieure.

Lorsque vous modifiez ces listes de système de fichiers au cours d'une session, Claude Code applique la modification à la session en cours, de sorte que la prochaine commande en sandbox s'exécute avec les nouveaux chemins.

Les chemins de système de fichiers du sandbox suivent les conventions standard : /tmp/build est absolu et ~/.kube est relatif à votre répertoire personnel. Cette syntaxe diffère de celle des règles de permission Read et Edit, qui utilisent //path pour les chemins absolus et /path pour les chemins relatifs au projet. Pour les chemins relatifs, les barres obliques finales et les caractères génériques, consultez Préfixes de chemin du sandbox.

Vous pouvez également refuser l'accès en écriture ou en lecture à l'aide de sandbox.filesystem.denyWrite et sandbox.filesystem.denyRead, et réautoriser des chemins spécifiques au sein d'une zone refusée à l'aide de sandbox.filesystem.allowRead. Lorsque des règles de lecture se chevauchent, c'est la règle au chemin le plus restreint qui s'applique :

Exemples de règles Résultat
"denyRead": ["~/"] avec "allowRead": ["~/projects"] ~/projects est lisible et le reste du répertoire personnel reste bloqué. L'autorisation plus restreinte rouvre cette partie de la zone refusée
"allowRead": ["~/"] avec "denyRead": ["~/.env"] ~/.env reste bloqué et le reste du répertoire personnel est lisible. Le refus tient à l'intérieur d'une autorisation plus large, de sorte qu'une autorisation large ne peut pas réexposer silencieusement un secret
"allowRead": ["~/"] avec "denyRead": ["~/**/.env"] Chaque fichier .env situé sous le répertoire personnel reste bloqué et le reste est lisible. Un refus avec caractère générique tient à l'intérieur d'une autorisation plus large de la même manière qu'un chemin exact

L'exemple ci-dessous bloque la lecture de l'ensemble du répertoire personnel tout en autorisant la lecture du projet actuel. Placez-le dans le fichier .claude/settings.json de votre projet, car le chemin relatif . ne se résout à la racine du projet que lorsque la configuration se trouve dans les paramètres de projet :

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

Si vous placiez la même configuration dans ~/.claude/settings.json, . se résoudrait plutôt en ~/.claude, et les fichiers du projet resteraient bloqués par la règle denyRead.

Pour refuser aux commandes en sandbox l'accès en lecture aux répertoires personnels et aux volumes montés tout en gardant les répertoires de travail lisibles, définissez permissions.blockReadsOutsideWorkingDirectories au lieu d'écrire des règles de chemin.

Exécuter des commandes en dehors du sandbox avec `excludedCommands`

Indiquez un motif de commande dans sandbox.excludedCommands pour exécuter les commandes correspondantes en dehors du sandbox, c'est-à-dire sans restrictions de système de fichiers ni proxy réseau. Utilisez-le pour un outil qui ne peut pas fonctionner dans le sandbox et auquel vous faites confiance avec votre accès complet. Un outil qui a besoin d'un répertoire ou d'un hôte supplémentaire peut fonctionner avec allowWrite ou allowedDomains, qui maintiennent la commande dans le sandbox.

Cet exemple sort les commandes docker compose du sandbox. Enregistrez-le dans ~/.claude/settings.json pour l'appliquer à tous vos projets :

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker compose *"]
  }
}

Claude Code compare vos entrées à chaque appel Bash et Monitor. Un appel correspond à la ligne de commande complète envoyée par Claude, qui peut enchaîner plusieurs commandes. Les règles suivantes déterminent si un appel sort du sandbox :

  • Terminez le motif par * : les entrées utilisent la même syntaxe qu'une règle de permission Bash(...), où un motif sans caractère générique correspond exactement. docker ne correspond qu'à docker sans arguments. docker * correspond à docker avec ou sans arguments
  • Chaque commande de l'appel doit correspondre : npm ci && docker compose build reste dans le sandbox, sauf si une autre entrée couvre npm ci
  • Claude Code compare le texte de l'appel : un script ou une cible make qui appelle docker en interne ne correspond pas, pas plus que /usr/local/bin/docker
  • Certains appels restent dans le sandbox : une redirection vers un fichier, un cd ou une substitution de commande comme $(...) maintient l'appel entier dans le sandbox. L'entrée de référence liste d'autres appels qui restent dans le sandbox
  • L'endroit où vous enregistrez l'entrée peut compter : tant que le sandbox est exigé par l'administrateur, Claude Code ignore les entrées de .claude/settings.json et .claude/settings.local.json

Une commande exclue passe par le flux de permissions habituel :

  • Les commandes en lecture seule et les commandes couvertes par vos règles d'autorisation s'exécutent sans demande de permission
  • En mode auto, le classifieur examine les autres commandes exclues
  • En mode bypassPermissions, une commande exclue s'exécute sans demande de permission, sauf si une règle de demande lui correspond

Pour confirmer qu'une entrée correspond, passez en mode Manual et demandez à Claude d'exécuter une commande correspondante qui modifie quelque chose, comme docker compose up -d. La demande de permission s'intitule « Bash command (unsandboxed) ».

Désactiver l'isolation du système de fichiers

Définissez sandbox.filesystem.disabled sur true pour ignorer l'isolation du système de fichiers tout en conservant l'isolation réseau. L'exemple ci-dessous désactive l'isolation du système de fichiers tout en conservant une liste d'autorisation de domaines réseau :

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Le sandbox comporte deux couches indépendantes : l'isolation du système de fichiers contrôle les chemins que les commandes en sandbox peuvent lire et écrire, et l'isolation réseau contrôle les domaines qu'elles peuvent atteindre. Lorsque la couche système de fichiers est désactivée, les commandes en sandbox obtiennent un accès illimité en lecture et en écriture au système de fichiers de l'hôte, tandis que leur trafic réseau sortant reste limité à vos domaines autorisés. Désactivez cette couche lorsque vous utilisez le sandbox pour contrôler où les commandes se connectent plutôt que ce qu'elles écrivent.

sandbox.filesystem.disabled a false comme valeur par défaut. Nécessite Claude Code v2.1.216 ou une version ultérieure.

Quels paramètres peuvent la désactiver

Comme la désactivation de l'isolation du système de fichiers élargit ce que les commandes en sandbox peuvent faire, Claude Code ne prend en compte filesystem.disabled qu'à partir des sources de paramètres suivantes :

  • Les paramètres utilisateur, les paramètres gérés et le flag CLI --settings peuvent le définir. Les paramètres de projet dans .claude/settings.json et .claude/settings.local.json ne le peuvent pas, de sorte qu'un projet récupéré ne peut pas désactiver l'isolation du système de fichiers.
  • Lorsque les paramètres gérés configurent sandbox.filesystem de quelque manière que ce soit, ou listent une entrée sandbox.credentials.files avec "mode": "deny", seuls les paramètres gérés peuvent définir la clé. Cela maintient en vigueur les restrictions de système de fichiers déployées par l'administrateur ; pour assouplir un tel déploiement, définissez "disabled": true dans les paramètres gérés.
  • Lorsque CLAUDE_CODE_SUBPROCESS_ENV_SCRUB est défini, Claude Code ignore filesystem.disabled quelle que soit la source, y compris les paramètres gérés, et maintient l'isolation du système de fichiers activée.

Une entrée mask valide ne verrouille pas la clé, même lorsque Claude Code la rabat sur deny au démarrage. Indiquez un chemin qui ne peut pas être masqué, comme un répertoire d'identifiants, sous forme d'entrée deny explicite dans les paramètres gérés, ce qui verrouille la clé.

Ce qui change lorsque l'isolation du système de fichiers est désactivée

Définir filesystem.disabled lève les protections que la couche système de fichiers applique elle-même. Les protections appliquées par d'autres couches restent en vigueur :

Protection Avec l'isolation du système de fichiers désactivée
Blocages en lecture filesystem.denyRead et deny de credentials.files Non appliqués. La couche système de fichiers applique les deux
Entrées deny et mask de credentials.envVars Appliquées. Le nettoyage des variables d'environnement est indépendant de la couche système de fichiers
Entrées mask de credentials.files appliquées comme masques Appliquées : le masquage est indépendant de la couche système de fichiers. Une entrée rabattue sur deny n'est pas appliquée, comme toute entrée deny

Deux autres éléments changent :

  • Les commandes en sandbox héritent du $TMPDIR de votre shell au lieu du répertoire temporaire propre à l'utilisateur, car tous les répertoires temporaires sont accessibles en écriture et Claude Code ne redirige plus les commandes vers celui propre à l'utilisateur.

    Sous Linux, cette variable n'est souvent pas définie dans le shell parent. Les consignes de l'outil Bash indiquent à Claude de créer des répertoires de travail temporaires avec mktemp -d plutôt que de s'appuyer sur $TMPDIR.

  • autoAllowBashIfSandboxed a toujours true comme valeur par défaut, de sorte que les commandes en sandbox continuent de s'exécuter sans demande de permission. Définissez-le sur false pour obtenir une demande de permission pour les commandes en sandbox.

Protéger les identifiants

Le paramètre sandbox.credentials déclare les fichiers d'identifiants et les variables d'environnement à protéger des commandes en sandbox. Chaque entrée désigne un chemin de fichier ou une variable d'environnement ainsi qu'un mode. Le bloc dédié credentials regroupe les règles relatives aux identifiants et les maintient séparées des règles générales de système de fichiers.

Pour les entrées avec "mode": "deny", la lecture des chemins de fichiers est refusée dans le sandbox, soit la même restriction que celle appliquée par filesystem.denyRead, et les variables d'environnement sont supprimées avant l'exécution de chaque commande en sandbox. La protection des fichiers fait partie de la couche système de fichiers, elle ne s'applique donc pas si vous désactivez l'isolation du système de fichiers ; la protection des variables d'environnement, elle, continue de s'appliquer.

L'exemple ci-dessous bloque la lecture du fichier d'identifiants AWS et du répertoire SSH, et supprime GITHUB_TOKEN et NPM_TOKEN de l'environnement des commandes en sandbox :

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

Les entrées de variables d'environnement et les entrées de fichiers acceptent également "mode": "mask", décrit dans Masquer les identifiants.

Les chemins de fichiers suivent les mêmes règles de préfixe que les paramètres sandbox.filesystem.*.

Claude Code fusionne les entrées deny de chaque portée de paramètres chargée par la session. Une entrée deny ne fait jamais que restreindre l'accès, donc toute portée peut en ajouter une, mais aucune portée ne peut en supprimer une ajoutée par une autre portée.

Lorsque vous excluez une source de paramètres :

  • Paramètres de projet ou locaux : Claude Code n'applique aucune de leurs entrées credentials. Nécessite Claude Code v2.1.246 ou une version ultérieure.
  • Paramètres utilisateur : Claude Code applique toujours les entrées deny de ~/.claude/settings.json et conserve ses entrées mask de fichiers comme restrictions qui n'autorisent plus le proxy à substituer la valeur réelle, mais abandonne ses entrées mask de variables d'environnement.

Il n'existe aucune liste de refus d'identifiants intégrée : seuls les fichiers et variables que vous listez sont restreints.

sandbox.credentials n'affecte que les commandes Bash en sandbox. Pour retirer les identifiants de tous les sous-processus, qu'ils soient en sandbox ou non, définissez CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.

Masquer les identifiants

Lorsque vous masquez un identifiant, Claude Code présente aux commandes en sandbox une valeur de substitution propre à la session, appelée la sentinelle, et le proxy du sandbox la remplace par la valeur réelle dans les requêtes sortantes vers les hôtes que vous autorisez. Une entrée deny décrite dans Protéger les identifiants bloque plutôt l'identifiant. Pour les fichiers sous macOS, Claude Code bloque plutôt le fichier au lieu de le masquer.

Le masquage des variables d'environnement nécessite Claude Code v2.1.199 ou une version ultérieure. La référence sandbox.credentials liste tous les champs.

Le masquage nécessite les éléments suivants :

  • Terminaison TLS : le proxy substitue la valeur réelle dans le contenu des requêtes, il doit donc pouvoir le voir. Définissez network.tlsTerminate pour que le proxy termine lui-même le TLS. Sans cela, le masquage échoue sans rien exposer : la commande ne voit toujours que la sentinelle, mais celle-ci atteint le serveur sans modification et l'authentification échoue. Claude Code signale cette erreur de configuration au démarrage.
  • Une destination autorisée : chaque entrée mask peut lister des injectHosts, les hôtes que la valeur réelle est autorisée à atteindre. Le proxy n'injecte que sur les connexions admises par la liste d'autorisation de domaines, de sorte que chaque hôte injectHosts doit également être accessible via network.allowedDomains. Pour une entrée mask sans injectHosts, le proxy substitue la valeur réelle dans les requêtes vers tous les hôtes de network.allowedDomains.
  • Une portée de paramètres de confiance : le masquage autorise le proxy à envoyer votre identifiant réel quelque part ; Claude Code ne prend donc en compte les entrées mask, network.tlsTerminate, credentials.allowPlaintextInject, awsPairs et sigv4 qu'à partir des paramètres utilisateur, des paramètres gérés et du flag --settings. Il les ignore dans le fichier .claude/settings.json ou .claude/settings.local.json d'un dépôt. Lorsque votre administrateur fournit des entrées mask, network.tlsTerminate ou credentials.allowPlaintextInject via des paramètres gérés par le serveur, ceux-ci comptent parmi les paramètres nécessitant une approbation.

Masquer les variables d'environnement

Pour masquer une variable d'environnement, définissez "mode": "mask" sur son entrée credentials.envVars. La commande et tout ce qu'elle journalise ne détiennent jamais l'identifiant réel, mais ses requêtes s'authentifient quand même. Lorsque la même variable est listée avec deny dans une portée quelconque, deny est prioritaire.

Cet exemple masque deux jetons. GH_TOKEN n'est substitué que dans les requêtes vers api.github.com, tandis que NPM_TOKEN n'a pas d'injectHosts et est substitué dans les requêtes vers tous les hôtes de network.allowedDomains :

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

Par défaut, le masquage remplace la valeur entière. Pour une valeur structurée, comme une chaîne de connexion DATABASE_URL ou un JWT, utilisez les champs extract, decode, maskClaims et onExtractNoMatch afin que les outils qui analysent la valeur continuent de fonctionner.

Pour une destination IPv6, écrivez l'adresse différemment dans les deux listes :

  • network.allowedDomains : la forme entre crochets, comme "[::1]"
  • injectHosts : l'adresse nue dans sa forme canonique compressée, comme "::1"

Le proxy compare chaque entrée injectHosts à l'adresse de destination nue de la connexion, en ignorant les ports, de sorte qu'une écriture entre crochets, avec identifiant de zone ou compressée différemment ne correspond jamais. claude doctor signale les entrées qui ne peuvent jamais correspondre avec l'avertissement Sandbox credential injectHosts entries can never match their destination. Cette vérification nécessite Claude Code v2.1.229 ou une version ultérieure.

Signer à nouveau les requêtes AWS

Les requêtes AWS portent des signatures SigV4 calculées sur le contenu de la requête ; masquez donc AWS_ACCESS_KEY_ID et AWS_SECRET_ACCESS_KEY ensemble. Le proxy détecte une requête SigV4 grâce à la sentinelle de la clé d'accès et la signe à nouveau avec les valeurs réelles, ce qui nécessite Claude Code v2.1.221 ou une version ultérieure. Si vous masquez uniquement le secret, les requêtes sont signées avec une valeur de substitution que le proxy ne peut pas détecter, de sorte qu'elles échouent côté AWS.

Claude Code associe automatiquement les variables conventionnelles AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY et AWS_SESSION_TOKEN en un seul identifiant lorsque vous masquez leurs valeurs entières. Si vos identifiants AWS se trouvent dans des variables portant d'autres noms, regroupez-les avec credentials.awsPairs, qui nécessite Claude Code v2.1.224 ou une version ultérieure.

Les téléversements en streaming, les URL présignées et les requêtes SigV4A portent des signatures que le proxy ne peut pas recalculer. Lorsqu'une de ces requêtes est signée avec la valeur de substitution d'une paire masquée, le proxy la fait échouer plutôt que de transmettre une signature invalide. Les requêtes signées avec des identifiants non masqués ne sont pas concernées. Utilisez credentials.sigv4, qui nécessite Claude Code v2.1.224 ou une version ultérieure, pour transmettre plutôt l'une de ces formes de requête. AWS rejette toujours la requête, de sorte que l'outil appelant reçoit la réponse de rejet d'AWS elle-même au lieu d'une erreur du proxy.

Masquer les fichiers d'identifiants

Pour masquer un fichier d'identifiants, définissez "mode": "mask" sur son entrée credentials.files. Le masquage des fichiers nécessite Claude Code v2.1.221 ou une version ultérieure. Ce que voit une commande en sandbox dépend de la plateforme :

  • Linux et WSL2 : les commandes en sandbox lisent une copie sentinelle du fichier, et le proxy substitue la valeur réelle dans les requêtes sortantes.
  • macOS : les commandes en sandbox ne peuvent pas du tout lire le fichier. Claude Code ne crée aucune copie sentinelle, de sorte que les outils qui s'authentifient avec le fichier ne fonctionnent pas dans le sandbox, avec le même effet que deny. Le blocage en lecture tient même lorsque vous désactivez l'isolation du système de fichiers.

Cet exemple masque un jeton GitHub stocké dans ~/.config/gh/hosts.yml. Le motif extract indique quelle partie du fichier constitue le secret, de sorte que sous Linux et WSL2, gh analyse toujours le reste de sa configuration :

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com"]
    },
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

Pour confirmer que le masque est actif, demandez à Claude d'exécuter cat ~/.config/gh/hosts.yml dans une commande en sandbox. Sous Linux et WSL2, la sortie affiche une sentinelle à la place du jeton, et sous macOS, la lecture échoue.

Sans extract ni decode, Claude Code remplace l'intégralité du fichier par une seule sentinelle, ce qui convient à un fichier ne contenant qu'un seul secret nu. Utilisez les champs extract, decode, maskClaims, onExtractNoMatch et maskDuplicates pour contrôler le masquage partiel et ce qui se passe lorsque le motif ne correspond à rien.

mask s'applique à un seul fichier ; listez donc chaque fichier d'identifiants individuellement. Claude Code se rabat sur deny pour une entrée mask qu'il ne peut pas masquer en toute sécurité : un chemin de répertoire, un motif glob, un fichier de plus de 8 Mio ou un fichier qui n'est pas du texte UTF-8.

Fonctionnement du sandboxing

Isolation du système de fichiers

L'outil Bash en sandbox restreint l'accès au système de fichiers à des répertoires spécifiques :

  • Comportement d'écriture par défaut : accès en lecture et en écriture au répertoire de travail actuel et à ses sous-répertoires, à tous les répertoires que vous avez ajoutés avec --add-dir, /add-dir ou permissions.additionalDirectories, ainsi qu'au répertoire temporaire propre à l'utilisateur vers lequel pointe $TMPDIR
  • Comportement de lecture par défaut : accès en lecture à l'ensemble de l'ordinateur, à l'exception de certains répertoires refusés. Ce comportement par défaut permet toujours de lire les fichiers d'identifiants ; protégez donc les identifiants que vous ne souhaitez pas voir lus par les commandes.
  • Blocage en lecture : lorsque permissions.blockReadsOutsideWorkingDirectories est activé, les commandes en sandbox perdent également l'accès en lecture à votre répertoire personnel et aux autres répertoires contenant des fichiers utilisateur, à l'exception des chemins répertoriés dans Commandes en sandbox sous le blocage. Cette section indique également quand cette partie du blocage ne s'applique pas.
  • Worktrees Git : lorsque le répertoire de travail est un worktree git lié, le sandbox autorise également les écritures dans le répertoire .git partagé du dépôt principal, afin que des commandes telles que git commit puissent mettre à jour les refs et l'index. Les écritures dans hooks/ et config au sein de ce répertoire restent refusées.

Pour ignorer entièrement l'isolation du système de fichiers tout en conservant l'isolation réseau, définissez sandbox.filesystem.disabled.

Chemins protégés

Dans les répertoires où les commandes en sandbox peuvent écrire, le sandbox refuse toujours les écritures dans les fichiers à partir desquels Claude Code charge sa configuration et son code. Une commande capable de modifier ces fichiers pourrait s'accorder des permissions, ou ajouter un hook ou un serveur MCP que Claude Code exécute en dehors du sandbox. Le système de permissions possède ses propres chemins protégés, qui contrôlent ce que Claude Code approuve avant l'exécution d'un outil ; la liste du sandbox s'applique à une commande déjà en cours d'exécution. Elle couvre quatre groupes de chemins :

  • Dans votre répertoire de travail et les répertoires parents : les fichiers de paramètres .claude, les répertoires .claude/skills, .claude/agents, .claude/commands et .claude/hooks, .mcp.json, ainsi que les fichiers que Claude Code exécute de lui-même, tels que .claude/workflows et .claude/scheduled_tasks.json
  • Dans votre répertoire de travail uniquement : les fichiers de démarrage du shell tels que .bashrc et .zshrc, .gitconfig, les répertoires .vscode et .idea, ainsi que hooks et config dans .git
  • Les fichiers qui transformeraient votre répertoire de travail en dépôt git bare : HEAD, objects et refs au niveau racine, ainsi que les entrées config et hooks existantes à cet endroit lorsqu'un HEAD se trouve à côté. Un fichier nommé config est refusé même en l'absence de HEAD. Sous Linux et WSL2, le sandbox supprime un fichier HEAD ou un répertoire objects ou refs de niveau racine qui apparaît pendant l'exécution d'une commande en sandbox
  • Dans ~/.claude, ou le répertoire vers lequel pointe CLAUDE_CONFIG_DIR : la majeure partie de son contenu, ainsi que ~/.claude.json et le magasin d'identifiants .credentials.json

Si un lien symbolique apparaît au chemin d'un fichier de paramètres protégé pendant la session, le sandbox refuse également les écritures dans le fichier vers lequel il pointe, à partir de la commande suivante.

Il n'existe aucun moyen d'exempter l'un de ces chemins : une entrée allowWrite ou une règle d'autorisation Edit couvrant le chemin ne lève pas la protection. La seule façon de désactiver la protection est filesystem.disabled, qui désactive l'isolation du système de fichiers pour tous les chemins. Pour voir la plupart de ces chemins résolus pour votre machine, exécutez /sandbox et ouvrez l'onglet Config, qui les répertorie sous Denied within allowed, mêlés à vos propres entrées denyWrite.

Si git merge ou git checkout échoue avec unable to unlink old sur l'un de ces chemins, consultez Une commande git échoue avec unable to unlink old.

Isolation réseau

Une commande en sandbox ne dispose d'aucun accès direct au réseau :

  • Linux et WSL2 : la commande s'exécute dans un espace de noms réseau distinct, sans connexion à votre réseau
  • macOS : le framework de sandbox Seatbelt bloque par défaut les connexions autres que celle vers le proxy du sandbox

Claude Code exécute le proxy du sandbox sur votre machine, en dehors du sandbox, et y redirige les commandes via HTTP_PROXY, HTTPS_PROXY, ALL_PROXY et les variables d'environnement associées. Le proxy vérifie le nom d'hôte de chaque connexion par rapport à vos domaines autorisés et refusés.

Ce qu'un outil peut atteindre dépend de son utilisation ou non du proxy :

  • Les outils qui lisent les variables de proxy : curl, npm, git via HTTPS et les outils similaires se connectent dès que leur hôte est autorisé. Une entrée allowedDomains sans port autorise tous les ports de cet hôte
  • Les outils qui ignorent les variables de proxy : ssh seul, la plupart des pilotes de base de données et les outils similaires ne peuvent pas se connecter, même à un hôte autorisé. Consultez Un client de base de données ou un autre outil non HTTP ne parvient pas à atteindre un hôte autorisé
  • Tout ce qui n'est pas TCP : UDP, HTTP/3 sur QUIC et les outils ICMP tels que ping ne peuvent pas sortir du sandbox

Les paramètres et comportements suivants contrôlent les hôtes autorisés par le proxy :

  • Restrictions de domaine : vos domaines autorisés sont initialement vides. Hôtes en dehors de vos domaines autorisés décrit ce qui se passe la première fois qu'une commande a besoin d'un nouveau domaine.
  • Choix d'approbation : si vous choisissez Yes lorsque cela vous est demandé, Claude Code autorise l'hôte pour le reste de la session en cours. Si vous choisissez « Yes, and don't ask again », Claude Code enregistre une règle d'autorisation WebFetch(domain:...) dans vos paramètres locaux, de sorte que l'hôte reste autorisé lors des sessions futures. Lorsque le sandbox est exigé par l'administrateur, Claude Code enregistre la règle dans vos paramètres utilisateur, où elle s'applique à tous les projets.
  • Domaines pré-autorisés : pré-autorisez des domaines avec allowedDomains pour éviter entièrement la demande. Claude Code pré-autorise également les domaines issus des règles d'autorisation WebFetch(domain:...), comme décrit dans Règles de permission.
  • Liste d'autorisation stricte : si vous définissez strictAllowlist sur true dans les paramètres utilisateur, gérés ou --settings de la CLI, Claude Code refuse aux commandes en sandbox l'accès à tout hôte en dehors de la liste d'autorisation au lieu de vous le demander. La liste d'autorisation se compose de allowedDomains et des domaines issus des règles d'autorisation WebFetch(domain:...), ou uniquement des entrées des paramètres gérés lorsque allowManagedDomainsOnly est défini. Verrous qui s'appliquent sans sandbox exigé par l'administrateur traite des entrées d'un dépôt. Claude Code applique cela uniquement aux commandes en sandbox ; les outils intégrés au processus tels que WebFetch suivent toujours leurs règles de permission. Le définir dans le fichier .claude/settings.json ou .claude/settings.local.json d'un dépôt n'a aucun effet. Nécessite Claude Code v2.1.219 ou version ultérieure.
  • Verrouillage géré : si allowManagedDomainsOnly est défini dans les paramètres gérés, les domaines non autorisés sont automatiquement bloqués au lieu de faire l'objet d'une demande, et seules les règles d'autorisation allowedDomains et WebFetch(domain:...) issues des paramètres gérés sont prises en compte.
  • Proxy d'entreprise : lorsque votre réseau exige que le trafic sortant passe par un proxy d'entreprise, définissez HTTPS_PROXY, HTTP_PROXY et NO_PROXY comme décrit dans configuration du proxy, dans le bloc env de vos paramètres afin que les agents en arrière-plan les reçoivent également, ou dans l'environnement à partir duquel vous lancez Claude Code. Claude Code applique la liste d'autorisation des domaines, puis fait transiter les connexions autorisées par ce proxy en amont. Les URL de proxy http:// et https:// fonctionnent, avec une authentification basique dans l'URL si nécessaire.

Dans une règle WebFetch(domain:...), le sandbox prend en charge deux formes de caractères génériques : un *. en préfixe, comme *.example.com, et un * seul. La forme * seule nécessite Claude Code v2.1.186 ou version ultérieure. Un caractère générique à toute autre position, comme WebFetch(domain:example.*), correspond toujours aux récupérations mais n'a aucun effet sur les commandes en sandbox.

Hôtes en dehors de vos domaines autorisés

Lorsqu'une commande en sandbox se connecte à un hôte qui ne figure pas dans vos domaines autorisés, la commande reste dans le sandbox et attend une décision. Dans une session de terminal interactive, la décision dépend de votre mode de permission :

Mode de permission Ce qu'il advient de la connexion
Mode bypassPermissions, et mode plan avec contournement des permissions disponible Autorisée sans demande
Mode manuel, mode acceptEdits et mode plan dans les autres cas Une demande vous est présentée
Mode auto Refusée, sauf si la commande a répertorié l'hôte et que le classifieur a approuvé la liste
Mode dontAsk Refusée

Lorsque strictAllowlist ou allowManagedDomainsOnly est activé, le proxy intégré du sandbox refuse la connexion dans tous les modes de permission. En mode bypassPermissions, les hôtes en dehors de vos domaines autorisés sont autorisés, sauf si l'un de ces paramètres est activé. L'échappatoire de la nouvelle tentative hors sandbox explique quand une commande peut sortir du sandbox dans ce mode. Une connexion à un hôte figurant dans deniedDomains est également refusée dans tous les modes de permission.

Noms d'hôte résolus en adresses locales

Une fois qu'un nom d'hôte a passé la liste d'autorisation, le proxy du sandbox le résout et refuse la connexion lorsque le nom ne se résout qu'en adresses locales. Les adresses locales incluent les adresses de loopback telles que 127.0.0.1, les adresses link-local telles que l'endpoint de métadonnées cloud 169.254.169.254, et les adresses attribuées à votre propre machine. Les noms localhost et *.localhost sont autorisés à se résoudre en loopback.

Un nom d'hôte intranet autorisé qui se résout dans une plage privée telle que 10.0.0.0/8 se connecte. Pour permettre à un nom de se résoudre en une adresse refusée, ajoutez cette adresse IP à allowedDomains, par exemple "127.0.0.1:8080".

La vérification s'applique aux noms d'hôte. Vos domaines autorisés et votre mode de permission déterminent le sort d'une connexion à une adresse IP. Le proxy ignore également la vérification pour les connexions qu'il fait transiter par un proxy d'entreprise en amont, car c'est ce proxy qui résout le nom.

Domaines autorisés par commande en mode auto

En mode auto avec le sandboxing activé, Claude indique sur la commande elle-même les hôtes dont elle a besoin, au lieu de déclencher une approbation réseau pour chaque connexion. Chaque commande Bash, PowerShell ou Monitor exécutée dans le sandbox peut comporter une liste d'hôtes au-delà de la liste d'autorisation du sandbox : un domaine tel que registry.npmjs.org, un caractère générique tel que *.pythonhosted.org ou une adresse IP, chacun avec un :port facultatif. Le classifieur examine les hôtes en même temps que la commande. Nécessite Claude Code v2.1.271 ou version ultérieure.

Une liste approuvée ouvre ces hôtes pour cette seule commande, pendant toute la durée de son exécution. Rien n'est ajouté aux hôtes autorisés de votre session ni à vos paramètres ; la commande suivante indique ses propres hôtes.

Une commande comportant des hôtes est transmise au classifieur au lieu d'être approuvée par une règle de permission ou par le mode d'autorisation automatique du sandbox. Si une règle ask impose une demande pour la commande, la boîte de dialogue de permission de votre terminal affiche les hôtes à côté, et l'approbation à cet endroit couvre les deux.

Une liste par commande élargit uniquement ce que le sandbox refuse par défaut. Les entrées deniedDomains continuent de bloquer. Lorsque strictAllowlist ou allowManagedDomainsOnly verrouille la liste d'autorisation, Claude Code refuse les listes par commande.

Tant que les listes par commande s'appliquent, Claude Code refuse une connexion à un hôte qu'aucune commande approuvée n'a répertorié, sans demande ni vérification par le classifieur. Le refus indique l'hôte dans le résultat de la commande, et Claude réexécute la commande en ajoutant l'hôte.

Adresses IPv6 dans les listes de domaines

Pour faire correspondre une adresse IPv6 dans allowedDomains, deniedDomains ou une règle WebFetch(domain:...), écrivez l'adresse entre crochets : "[::1]" correspond à cette adresse sur tous les ports, et "[::1]:443" uniquement sur le port 443. La forme entre crochets nécessite Claude Code v2.1.229 ou version ultérieure.

Une entrée sans crochets telle que ::1:443 est ambiguë : elle peut désigner une adresse ou une adresse suivie d'un port :

  • Listes de refus : Claude Code refuse chaque interprétation possible de l'entrée, de sorte que l'interprétation que vous vouliez est bloquée quelle qu'elle soit. Pour une entrée sans interprétation analysable, Claude Code ne bloque rien
  • Listes d'autorisation : Claude Code n'autorise jamais plus que ce que vous avez écrit. Il réécrit une entrée ambiguë selon son interprétation hôte-et-port lorsque celle-ci s'analyse correctement, et peut supprimer entièrement l'entrée plutôt que d'élargir la liste d'autorisation

Pour trouver les entrées ambiguës, exécutez claude doctor dans votre terminal et recherchez l'avertissement Sandbox network domain entries have unreliable spellings. Réécrivez chaque entrée ambiguë sous la forme entre crochets.

Application au niveau du système d'exploitation

L'outil Bash en sandbox utilise les primitives de sécurité du système d'exploitation :

  • macOS : utilise Seatbelt pour l'application du sandbox
  • Linux : utilise bubblewrap pour l'isolation
  • WSL2 : utilise bubblewrap, comme Linux

Vous pouvez également exécuter le package @anthropic-ai/sandbox-runtime seul pour encapsuler le processus Claude Code. Consultez Sandbox runtime.

Comment le sandboxing se rapporte aux permissions et aux modes de permission

Le sandboxing, les règles de permission, et les modes de permission sont des couches complémentaires. Les sections ci-dessous couvrent comment le sandbox interagit avec chacun.

Règles de permission

Les règles de permission et le sandboxing contrôlent des choses différentes :

  • Les règles de permission contrôlent quels outils Claude Code peut utiliser et sont évaluées avant l'exécution de tout outil. Elles s'appliquent à chaque outil : Bash, Read, Edit, WebFetch, MCP, et autres, sauf qu'une règle de refus ou de demande ne peut pas bloquer EndConversation tant qu'un autre outil reste.
  • Le sandboxing fournit une application au niveau du système d'exploitation qui restreint ce que les commandes shell peuvent accéder au niveau du système de fichiers et du réseau. Il s'applique uniquement aux commandes Bash, PowerShell, et Monitor et à leurs processus enfants.

Les deux couches diffèrent également dans la façon dont elles sont appliquées. Claude Code évalue les décisions de permission avant l'exécution d'une commande, en fonction de la chaîne de commande et, en mode auto, du jugement d'un classificateur distinct sur la sécurité de la commande. Le système d'exploitation applique la limite du sandbox au processus en cours d'exécution, donc elle tient indépendamment de ce que le modèle a choisi d'exécuter et même si une commande autorisée fait plus que son nom ne le suggère.

Les restrictions du système de fichiers et du réseau sont configurées via les paramètres du sandbox et les règles de permission :

Paramètre ou règle Ce qu'il fait
sandbox.filesystem.allowWrite Accorde l'accès en écriture du sous-processus aux chemins en dehors du répertoire de travail
sandbox.filesystem.denyWrite et sandbox.filesystem.denyRead Bloquent l'accès du sous-processus à des chemins spécifiques
sandbox.filesystem.allowRead Réautorise la lecture de chemins spécifiques dans une région denyRead
sandbox.filesystem.disabled Désactive entièrement la couche du système de fichiers tout en conservant l'isolation du réseau
Règles d'autorisation Edit Accordent l'accès en écriture à des chemins spécifiques, de la même manière que sandbox.filesystem.allowWrite
Règles de refus Read et Edit Bloquent l'accès à des fichiers ou répertoires spécifiques
Règles d'autorisation et de refus WebFetch(domain:...) Contrôlent l'accès au domaine
allowedDomains du sandbox Contrôle les domaines que les commandes Bash peuvent atteindre
deniedDomains du sandbox Bloque les domaines spécifiques même lorsqu'un caractère générique allowedDomains plus large les autoriserait autrement

Les chemins et domaines des paramètres du sandbox et des règles de permission sont fusionnés dans la configuration finale du sandbox.

Le répertoire d'exemples du référentiel claude-code inclut des configurations de paramètres de démarrage pour les scénarios de déploiement courants, y compris des exemples spécifiques au sandbox. Utilisez-les comme points de départ et ajustez-les selon vos besoins.

Modes de permission

/sandbox n'est pas un mode de permission. Les modes de permission décident si un appel d'outil s'exécute et si vous êtes d'abord invité, tandis que le sandbox restreint ce qu'une commande Bash peut accéder une fois qu'elle s'exécute. Ils diffèrent dans ce qu'ils contrôlent et ce qui remplace l'invite par action :

Ce qu'il contrôle Ce qui remplace l'invite
/sandbox Ce qu'une commande Bash peut accéder une fois qu'elle s'exécute La limite du sandbox elle-même, en mode auto-allow
Mode auto Si chaque appel d'outil s'exécute Un classificateur qui examine les actions
--dangerously-skip-permissions Si chaque appel d'outil s'exécute Rien. Les vérifications de chemin protégé sont également ignorées ; les actions qu'aucun mode n'auto-approuve s'appliquent toujours

Le mode auto-allow du sandbox est séparé du mode auto : auto-allow approuve les commandes Bash parce que la limite du sandbox les contient, tandis que le mode auto utilise un classificateur pour examiner les actions. Les deux fonctionnent indépendamment et peuvent être combinés, avec les exceptions énumérées sous Modes du sandbox. Pour choisir une limite d'isolation pour les exécutions sans surveillance, voir Environnements du sandbox. Pour un tableau des appairages courants de mode de permission et de sandbox avec les drapeaux qui démarrent chacun, voir Configurations courantes.

Configurer le sandbox pour votre organisation

Les administrateurs peuvent exiger le sandboxing pour chaque utilisateur, empêcher les développeurs d'élargir la politique et acheminer le trafic sandbox via un proxy d'entreprise.

Appliquer le sandboxing avec les paramètres gérés

Pour exiger le sandbox pour chaque développeur, livrez les clés sandbox via paramètres gérés, soit en tant que fichier géré par votre MDM, soit via paramètres gérés par serveur sur claude.ai.

La configuration de paramètres gérés suivante active le sandbox, refuse de démarrer Claude Code lorsque la plateforme n'est pas prise en charge ou qu'une dépendance est manquante, et empêche le modèle de réessayer les commandes en dehors du sandbox :

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

Les deux clés au-delà de enabled contrôlent ce qui se passe lorsque le sandbox ne peut pas exécuter une commande :

  • failIfUnavailable : une dépendance manquante telle que bubblewrap sur Linux empêche Claude Code de démarrer plutôt que de revenir à une exécution non sandboxée
  • allowUnsandboxedCommands: false : Claude Code ignore la trappe d'échappement dangerouslyDisableSandbox, donc lorsqu'une commande échoue sous le sandbox, Claude ne peut pas la réessayer en dehors du sandbox

Envisagez ces ajouts en complément :

Cette configuration sandboxe les commandes que Claude exécute. Un développeur peut toujours taper une commande à l'invite shell-mode ! et l'exécuter en dehors du sandbox, avec le même accès qu'il a déjà dans n'importe quel terminal en dehors de Claude Code. Consultez le mode sandbox strict pour les sessions où les commandes tapées s'exécutent en sandboxé.

Le sandbox ne s'exécute pas sur Windows natif, donc avec failIfUnavailable défini, Claude Code se ferme au démarrage sur ces machines. Si votre flotte inclut des hôtes Windows, vous pouvez :

  • Livrer la configuration par système d'exploitation : déployez-la via votre MDM ou en tant que fichier de paramètres gérés uniquement sur les machines macOS et Linux. Les paramètres gérés par serveur s'appliquent à tous les utilisateurs de l'organisation
  • Déplacer les utilisateurs Windows vers un environnement pris en charge : demandez-leur d'exécuter Claude Code à l'intérieur de WSL2 ou d'un conteneur

Empêcher les développeurs d'élargir la politique

Lorsque les paramètres gérés définissent une clé booléenne telle que enabled ou failIfUnavailable, Claude Code utilise la valeur gérée et ignore tout ce qu'un développeur définit localement. Pour les clés de tableau telles que allowRead, Claude Code fusionne les entrées des portées que la session charge, un développeur peut donc ajouter des entrées qui élargissent la politique, sauf si un verrou couvre cette clé.

Sauf si les paramètres gérés les définissent, les paramètres utilisateur d'un développeur ou --settings peuvent activer les clés suivantes. Le .claude/settings.json d'un dépôt le peut aussi, sauf si le sandbox est exigé par l'administrateur. Chacune affaiblit le sandbox, définissez-la donc sur false dans les paramètres gérés si vous ne voulez pas qu'elle soit utilisée :

Définissez allowManagedReadPathsOnly sur true dans les paramètres gérés pour que seules les entrées allowRead des paramètres gérés soient honorées. Cela empêche les développeurs d'élargir l'accès en lecture au-delà des chemins approuvés par l'organisation.

Pour verrouiller les domaines réseau aux valeurs gérées de la même manière, définissez allowManagedDomainsOnly. Avec ce verrou activé, seuls les paramètres gérés peuvent définir un port de proxy.

Lorsque les paramètres gérés configurent sandbox.filesystem ou listent une entrée sandbox.credentials.files avec "mode": "deny", seuls les paramètres gérés peuvent définir filesystem.disabled, les développeurs ne peuvent donc pas désactiver les restrictions de filesystem déployées par l'administrateur. Une entrée mask valide ne verrouille pas la clé. Consultez Quels paramètres peuvent le désactiver.

Paramètres de dépôt sous un sandbox exigé par l'administrateur

Le sandbox est exigé par l'administrateur tant que l'un de ces paramètres est en vigueur :

Ces paramètres n'activent pas le sandbox, définissez donc également enabled.

Tant que le sandbox est exigé par l'administrateur, Claude Code ne prend les paramètres qui l'assouplissent que dans les paramètres gérés, le flag --settings et le ~/.claude/settings.json de chaque développeur. Il ignore ces paramètres dans le .claude/settings.json et le .claude/settings.local.json d'un dépôt :

Paramètre de dépôt Ce que Claude Code ignore
excludedCommands, ignoreViolations, network.allowedDomains, network.allowUnixSockets, network.allowMachLookup, network.httpProxyPort, network.socksProxyPort Chaque entrée
filesystem.allowWrite, règles d'autorisation Edit(...), permissions.additionalDirectories L'accès en écriture que chaque entrée donne aux commandes sandboxées. Les outils de fichiers de Claude suivent toujours les règles Edit(...) et les répertoires supplémentaires
Règles d'autorisation WebFetch(domain:...) L'hôte que chaque règle ajoute à la liste d'autorisation du sandbox. L'outil WebFetch suit toujours la règle
enableWeakerNestedSandbox, enableWeakerNetworkIsolation, network.allowAllUnixSockets, network.allowLocalBinding true. Un false s'applique toujours
enabled, failIfUnavailable false, lorsque le ~/.claude/settings.json du développeur définit true
filesystem.allowRead Une entrée au niveau ou en dessous d'un chemin dont les paramètres gérés, --settings ou les paramètres utilisateur refusent la lecture, ou un glob qui pourrait correspondre à un tel chemin

Ces paramètres s'appliquent toujours tant que le sandbox est exigé par l'administrateur :

  • Dans les fichiers d'un dépôt : les entrées de refus et la valeur autoAllowBashIfSandboxed. Définissez la clé dans les paramètres gérés pour empêcher un dépôt de la modifier
  • Dans les propres paramètres d'un développeur : les paramètres du tableau s'appliquent toujours depuis ~/.claude/settings.json ou --settings, sauf si un verrou géré uniquement tel que allowManagedDomainsOnly les couvre. La plupart d'entre eux, comme excludedCommands et filesystem.allowWrite, n'ont pas de verrou géré uniquement

La configuration sous Appliquer le sandboxing avec les paramètres gérés rend le sandbox exigé par l'administrateur. Ajoutez aux paramètres gérés les entrées excludedCommands, allowWrite et de sockets dont vos outils approuvés ont besoin, car un dépôt ne peut pas les fournir.

Nécessite Claude Code v2.1.285 ou ultérieur. De la v2.1.282 à la v2.1.284, les mêmes paramètres faisaient ignorer à Claude Code les entrées excludedCommands d'un dépôt.

Verrous qui s'appliquent sans sandbox exigé par l'administrateur

Certains paramètres font ignorer à Claude Code les clés de dépôt qui remplacent directement une restriction, même lorsque le sandbox n'est pas exigé par l'administrateur. Chacun n'a cet effet que lorsque vous le définissez dans un fichier nommé dans sa ligne, et les autres paramètres de sandbox du dépôt s'appliquent toujours. Nécessite Claude Code v2.1.285 ou ultérieur.

Paramètre Où le définir Ce que Claude Code ignore dans les paramètres d'un dépôt
network.deniedDomains ou une règle de refus WebFetch(domain:...) Paramètres gérés, --settings httpProxyPort et socksProxyPort
network.strictAllowlist Paramètres gérés, --settings, paramètres utilisateur Les ports de proxy, allowedDomains et les règles d'autorisation WebFetch(domain:...)
filesystem.denyRead, une règle de refus Read(...) ou une entrée credentials.files Paramètres gérés, --settings Une entrée allowRead, allowWrite, d'autorisation Edit(...) ou additionalDirectories au niveau ou en dessous d'un chemin dont les paramètres gérés, --settings ou les paramètres utilisateur refusent la lecture, ou un glob qui pourrait correspondre à un tel chemin

Ces verrous modifient ce que les commandes sandboxées peuvent atteindre. L'outil WebFetch et les outils de fichiers de Claude suivent toujours les règles et les répertoires supplémentaires d'un dépôt.

Configuration de proxy personnalisée

Pour inspecter, filtrer ou journaliser le trafic sandbox avec vos propres outils, remplacez le proxy intégré du sandbox par un proxy que vous exécutez sur la même machine.

Pour acheminer le trafic sandbox via un proxy d'entreprise situé ailleurs sur votre réseau, définissez plutôt HTTPS_PROXY, comme le décrit l'entrée Proxy d'entreprise sous Isolation réseau. Ainsi, la liste d'autorisation de Claude Code s'applique toujours.

Pour diriger les commandes sandboxées vers votre proxy, définissez les ports localhost sur lesquels il écoute dans les paramètres de sandbox :

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Si vous définissez un port et définissez également HTTPS_PROXY ou HTTP_PROXY, Claude Code ne transmet pas ce que les commandes sandboxées envoient à votre proxy vers le proxy nommé par ces variables. Pour atteindre un proxy d'entreprise, configurez votre propre proxy pour qu'il y transfère le trafic.

Les fichiers pouvant définir un port dépendent de vos autres paramètres de sandbox :

Claude Code ignore un port défini ailleurs. Avant la v2.1.285, n'importe quel fichier de paramètres pouvait définir un port.

Dépannage

Certaines commandes échouent à l'intérieur du sandbox même si elles fonctionnent en dehors. Trouvez le titre qui correspond à votre symptôme ou à votre message d'erreur.

Si le sandbox de votre organisation est imposé par l'administrateur, Claude Code ignore les paramètres cités par ces correctifs dans les fichiers de paramètres d'un projet. Enregistrez-les donc dans ~/.claude/settings.json, où ils s'appliquent à tous les projets. Si un correctif reste sans effet, il se peut que les paramètres gérés de votre organisation définissent cette clé.

Un correctif qui ajoute un motif excludedCommands retire du sandbox les commandes correspondant à ce motif. Consultez ce qu'une commande exclue peut faire.

Les commandes échouent avec une erreur host-not-allowed

De nombreux outils CLI doivent atteindre des hôtes spécifiques. Approuvez l'hôte lorsque cela vous est demandé, ou ajoutez-le à allowedDomains. Si votre organisation verrouille la liste d'autorisation avec allowManagedDomainsOnly, aucune demande n'apparaît : demandez alors à votre administrateur d'ajouter l'hôte.

`jest` se bloque ou échoue

watchman est incompatible avec le sandbox. Exécutez jest --no-watchman à la place.

Les CLI basés sur Go échouent la vérification TLS sur macOS

Les outils tels que gh, gcloud et terraform peuvent échouer la vérification TLS sous Seatbelt. Pour exécuter ces outils en dehors du sandbox, ajoutez un motif pour chaque outil, tel que gh *, à excludedCommands. L'outil s'exécute alors avec votre accès complet et ses identifiants enregistrés. Si vous utilisez httpProxyPort avec un proxy MITM et une CA personnalisée, définissez enableWeakerNetworkIsolation sur true à la place.

Les commandes `open`, `osascript` ou les flux d'authentification basés sur un navigateur échouent avec l'erreur `-600` sur macOS

Le sandbox bloque les Apple Events par défaut. Définissez allowAppleEvents sur true dans vos paramètres utilisateur, gérés ou CLI pour les autoriser. Claude Code ignore cette clé dans les paramètres du projet.

L'activation de allowAppleEvents supprime l'isolation de l'exécution du code, car les commandes sandboxées peuvent alors lancer d'autres applications non sandboxées sans invite utilisateur et envoyer des commandes AppleScript aux applications en cours d'exécution, sous réserve de l'invite de consentement à l'automatisation macOS (TCC). Vous pouvez également ajouter un motif tel que open * à excludedCommands. Chaque appel à open passe alors par le flux de permission, et open peut lancer n'importe quel fichier ou application, y compris un fichier écrit par Claude.

Les commandes `docker` échouent

docker est incompatible avec le sandbox. Retirez du sandbox les commandes docker dont vous avez besoin avec un motif excludedCommands tel que docker compose *. Exécuter des commandes en dehors du sandbox avec excludedCommands explique ce qu'une commande docker exclue peut atteindre. Un motif plus restreint retire moins de commandes du sandbox.

`pbcopy`, `xclip` ou `wl-copy` ne met pas à jour le presse-papiers

Les utilitaires de presse-papiers pbcopy, xclip et wl-copy peuvent échouer à atteindre le presse-papiers système de l'intérieur du sandbox, auquel cas le texte qui leur est envoyé par pipe n'arrive pas.

Pour mettre la sortie de Claude sur votre presse-papiers, demandez à Claude de l'imprimer dans sa réponse, puis exécutez /copy. /copy écrit dans le presse-papiers à partir du processus Claude Code plutôt qu'à partir d'une commande sandboxée.

Lorsque Claude envoie du texte par pipe à l'un de ces outils, ajouter l'outil à excludedCommands ne retire pas cet appel du sandbox en soi.

git merge, git checkout et les commandes similaires échouent avec unable to unlink old lorsqu'elles doivent remplacer un fichier auquel le sandbox refuse les écritures. Sur Linux et WSL2, l'erreur se termine par Read-only file system. Le fichier peut se trouver à l'un de ces emplacements :

  • Sous un chemin protégé tel que .claude/skills
  • Sous l'une de vos entrées denyWrite
  • En dehors des répertoires dans lesquels le sandbox permet aux commandes d'écrire

Après l'échec, Claude peut proposer de réexécuter la commande en dehors du sandbox. Approuvez cette nouvelle tentative ou exécutez la commande git vous-même dans un autre terminal. Si vous avez défini allowUnsandboxedCommands sur false, Claude ne peut pas proposer la nouvelle tentative, alors exécutez la commande vous-même.

Bubblewrap échoue à démarrer à l'intérieur d'un conteneur

Dans un conteneur sans privilèges, bubblewrap ne peut pas monter un système de fichiers /proc frais, donc les commandes sandboxées échouent avec une erreur bwrap telle que Can't mount proc on /newroot/proc: Operation not permitted. Définissez enableWeakerNestedSandbox sur true pour que le sandbox bind-monte le /proc existant du conteneur à la place. Utilisez ce paramètre uniquement lorsque le conteneur externe fournit déjà la limite d'isolation dont vous avez besoin, car ce paramètre expose aux commandes sandboxées des informations de processus qu'un montage /proc frais cacherait.

Les fichiers en lecture seule de 0 octet apparaissent aux chemins des paramètres `.claude`, et « Oui, et ne pas demander à nouveau » ne sauvegarde pas

Sur Linux et WSL2, le sandbox maintient un refus d'écriture sur un fichier qui n'existe pas encore en créant un espace réservé en lecture seule de 0 octet à cet emplacement pendant qu'une commande sandboxée s'exécute. Le sandbox supprime l'espace réservé ensuite. Si une session est tuée avant que ce nettoyage ne s'exécute, par exemple par SIGKILL, les espaces réservés restent. Les sessions ultérieures lient à nouveau les espaces réservés en lecture seule à chaque démarrage, donc une écriture de paramètres telle que l'enregistrement d'un choix de permission échoue à un chemin où un espace réservé subsiste.

Exécutez claude doctor dans votre terminal pour lister les fichiers d'espace réservé restants. L'avertissement Stale sandbox mask files left by a killed session en nomme certains et compte le reste. Supprimez chaque fichier avec rm tandis qu'aucune autre session Claude Code ne s'exécute dans ce projet. Avant v2.1.257, Claude Code laissait les mêmes espaces réservés derrière sans les signaler.

`git` via SSH échoue lorsque le sandbox est activé

Sur macOS, git fetch, git pull et git push vers un dépôt distant SSH échouent à l'intérieur du sandbox même lorsque l'hôte est autorisé. Sur Linux et WSL2, ils fonctionnent dès que l'hôte est autorisé. Claude Code fait transiter la connexion SSH de git par un tunnel via le proxy du sandbox, et le tunnel macOS ne peut pas s'authentifier auprès de ce proxy.

Sur Linux et WSL2, vérifiez les points suivants si la connexion échoue toujours :

  • L'hôte est autorisé sur le port 22 : une entrée allowedDomains sans port, telle que "git.example.com", le couvre
  • Votre proxy d'entreprise autorise le port 22 : si votre réseau exige un proxy en amont, le tunnel passe également par celui-ci
  • La clé est lisible en tant que fichier : le sandbox peut bloquer le socket ssh-agent, et une entrée denyRead ou credentials pour ~/.ssh masque vos fichiers de clé

Sur macOS, basculez le dépôt distant vers HTTPS, ce qui nécessite des identifiants HTTPS tels qu'un jeton d'accès personnel :

git remote set-url origin https://git.example.com/example-org/example-repo.git

Si vous devez conserver le dépôt distant SSH, retirez les commandes réseau de git du sandbox avec excludedCommands :

{
  "sandbox": {
    "excludedCommands": ["git fetch *", "git pull *", "git push *"]
  }
}

Ces entrées correspondent à git push origin main. Un appel qui ajoute un cd, utilise git -C ou contient une substitution de commande reste sandboxé. Les commandes git exclues peuvent atteindre n'importe quel hôte, et pas seulement ceux figurant dans allowedDomains.

Les commandes ssh, scp et rsync simples via SSH échouent pour la raison indiquée dans l'entrée sur les clients de base de données.

Un client de base de données ou un autre outil non HTTP ne parvient pas à atteindre un hôte autorisé

Un outil qui ignore les variables d'environnement du proxy ne peut pas se connecter depuis l'intérieur du sandbox, même à un hôte figurant dans allowedDomains. Une commande sandboxée n'a aucune route directe vers le réseau, donc un outil qui ouvre sa propre connexion échoue. La plupart des pilotes de base de données, ssh simple et les outils qui utilisent UDP se comportent ainsi.

L'échec se présente comme une erreur réseau ou de résolution de nom :

  • macOS : Operation not permitted, ou une erreur de résolution de nom telle que Could not resolve host
  • Linux et WSL2 : Network is unreachable, ou une erreur de résolution de nom telle que Temporary failure in name resolution

Un outil qui utilise le proxy échoue différemment lorsque son hôte n'est pas autorisé. Vous recevez une demande de permission réseau, ou l'outil reçoit une réponse 403 du proxy.

Pour permettre à l'outil de se connecter, exécutez la commande qui en a besoin en dehors du sandbox avec excludedCommands. Cet exemple exclut un script et ajoute une règle ask afin que vous approuviez chaque exécution :

{
  "sandbox": {
    "excludedCommands": ["python scripts/load_orders.py *"]
  },
  "permissions": {
    "ask": ["Bash(python scripts/load_orders.py *)"]
  }
}

Le script s'exécute avec votre accès complet, et Claude peut modifier un script situé dans votre répertoire de travail : examinez-le donc lorsque la demande apparaît.

Une commande ne parvient pas à atteindre un serveur sur localhost

Par défaut, une commande sandboxée ne peut pas se connecter directement à un serveur qui s'exécute sur votre machine en dehors du sandbox, comme un serveur de développement ou une base de données dans un conteneur. Ce que vous pouvez modifier dépend de votre plateforme :

  • macOS : définissez network.allowLocalBinding sur true. Les commandes sandboxées peuvent alors écouter sur des ports réseau et se connecter à n'importe quel port sur localhost, ce qui inclut tous les autres services qui y écoutent. Un service localhost qui n'exige pas d'authentification, comme un débogueur, peut alors agir pour le compte de la commande en dehors du sandbox, et une commande qui écoute sur une adresse autre que loopback accepte les connexions d'autres machines
  • Linux et WSL2 : le localhost d'une commande sandboxée est privé à cette commande. La commande peut écouter sur un port et atteindre les serveurs qu'elle a elle-même démarrés. Une connexion directe à localhost ou 127.0.0.1 n'atteint pas les serveurs de l'hôte, et allowLocalBinding n'a aucun effet. Exécutez la commande qui a besoin du serveur de l'hôte en dehors du sandbox avec excludedCommands, où elle n'a aucune limite de système de fichiers ni de réseau. Pour les connexions qui passent par le proxy du sandbox, consultez Noms d'hôte qui se résolvent en adresses locales

Cet exemple active le paramètre pour macOS :

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

Une entrée allowedDomains pour localhost s'applique aux connexions qui passent par le proxy, elle ne modifie donc pas une connexion directe. Claude Code définit NO_PROXY pour les commandes sandboxées afin qu'elles se connectent à localhost directement plutôt que via le proxy. L'entrée expose également tous les ports du localhost de votre machine à une commande qui utilise le proxy. Pour un nom d'hôte de développement qui pointe vers 127.0.0.1, consultez Un nom d'hôte autorisé est refusé avec resolved to a loopback address.

Un nom d'hôte autorisé est refusé avec `resolved to a loopback address`

Le proxy du sandbox refuse un nom d'hôte autorisé qui se résout en une adresse locale, ce qui affecte les noms de développement tels que myapp.test qui pointent vers 127.0.0.1. La commande reçoit une réponse 403 dont le corps indique le type d'adresse, par exemple Connection to myapp.test blocked: resolved to a loopback address.

Ajoutez l'adresse IP en laquelle le nom se résout à côté du nom d'hôte dans allowedDomains, chacun avec le port sur lequel votre serveur écoute :

{
  "sandbox": {
    "network": {
      "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]
    }
  }
}

Une entrée d'adresse IP sans port permet aux commandes sandboxées d'atteindre tous les services qui écoutent sur cette adresse.

Avant v2.1.284, le proxy se connectait à l'adresse en laquelle se résolvait un nom d'hôte autorisé, quelle qu'elle soit.

`/sandbox` échoue avec `Sandbox settings are overridden by a higher-priority configuration`

/sandbox affiche Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally. au lieu d'ouvrir son panneau lorsqu'un niveau de paramètres supérieur définit sandbox.enabled, sandbox.autoAllowBashIfSandboxed ou sandbox.allowUnsandboxedCommands. Le panneau enregistre vos choix dans .claude/settings.local.json, et une valeur enregistrée à cet endroit ne peut pas remplacer ces niveaux.

Les paramètres gérés et --settings ont priorité sur les paramètres locaux. Pour voir lesquels ont été chargés dans cette session, exécutez /status et lisez la ligne Setting sources :

  • Command line arguments : si vous avez démarré Claude Code avec --settings, vérifiez si le fichier ou le JSON que vous avez transmis définit l'une de ces clés. Si c'est le cas, modifiez la valeur à cet endroit, ou redémarrez Claude Code sans ces clés.
  • Enterprise managed settings : les paramètres gérés de votre organisation sont chargés. S'ils définissent l'une de ces clés, vous ne pouvez pas modifier cette clé depuis /sandbox ni depuis aucun fichier de paramètres que vous contrôlez : adressez-vous donc à votre administrateur.

Limitations

Le sandboxing réduit le risque mais n'est pas une limite d'isolation complète. Examinez les limitations ci-dessous avant de vous y fier comme contrôle de sécurité dur.

Limitations de sécurité

  • Filtrage réseau : le sandbox restreint les domaines auxquels les processus peuvent se connecter. Par défaut, le proxy intégré ne termine pas ou n'inspecte pas TLS sur le trafic sortant, le contenu des connexions chiffrées n'est donc pas examiné. Le paramètre expérimental network.tlsTerminate termine TLS au proxy pour la substitution d'identifiants mask mais n'ajoute pas de filtrage de contenu. Vous êtes responsable de vous assurer que seuls les domaines de confiance sont autorisés dans votre politique.
  • Escalade de privilèges via les sockets Unix : la configuration allowUnixSockets peut accorder involontairement l'accès à des services système qui pourraient entraîner des contournements du sandbox. Par exemple, autoriser l'accès à /var/run/docker.sock accorde effectivement l'accès au système hôte via le socket Docker. Considérez attentivement tous les sockets Unix que vous autorisez via le sandbox.
  • Escalade de permissions du système de fichiers : les permissions d'écriture du système de fichiers trop larges peuvent permettre des attaques d'escalade de privilèges. Autoriser les écritures dans les répertoires contenant des exécutables dans $PATH, les répertoires de configuration système ou les fichiers de configuration shell utilisateur tels que .bashrc ou .zshrc peut entraîner l'exécution de code dans différents contextes de sécurité lorsque d'autres utilisateurs ou processus système accèdent à ces fichiers.
  • Force du sandbox Linux : l'implémentation Linux fournit une isolation forte du système de fichiers et du réseau mais inclut un mode enableWeakerNestedSandbox qui lui permet de fonctionner à l'intérieur des environnements Docker sans espaces de noms privilégiés. Cette option affaiblit considérablement la sécurité et ne doit être utilisée que lorsqu'une isolation supplémentaire est autrement appliquée.
  • Apple Events sur macOS : le sandbox macOS bloque les Apple Events par défaut. Le paramètre allowAppleEvents lève cette restriction afin que les outils tels que open et osascript fonctionnent, mais il supprime l'isolation de l'exécution du code : les commandes sandboxées peuvent lancer d'autres applications sans sandbox sans invite utilisateur, et peuvent envoyer des commandes AppleScript aux applications en cours d'exécution, sous réserve de l'invite de consentement à l'automatisation macOS par application (TCC). Il n'est honoré que par les paramètres utilisateur, gérés ou CLI. Les paramètres de projet ne peuvent pas l'activer.

Portée

Le sandbox isole les commandes shell et leurs processus enfants. Ce qui s'exécute en dehors du sandbox répertorie les outils et processus auxiliaires qu'il ne couvre pas. L'utilisation de l'ordinateur et les sous-agents se rapportent au sandbox comme suit :

  • Utilisation de l'ordinateur : lorsque Claude ouvre des applications et contrôle votre écran, il s'exécute sur votre bureau réel plutôt que dans un environnement isolé. Les invites de permission par application contrôlent chaque application. Consultez utilisation de l'ordinateur dans la CLI ou utilisation de l'ordinateur dans Desktop.
  • Sous-agents : les sous-agents s'exécutent dans le même processus que la session parent et utilisent la même configuration de sandbox. Les commandes Bash à l'intérieur d'un sous-agent sont sandboxées lorsque le sandboxing est activé dans la session parent.
  • Mods : un mod est un plugin qui exécute son propre code à l'intérieur de Claude Code, et un processus lancé par un mod s'exécute en dehors du sandbox. Consultez Ce qu'un mod peut atteindre.

Voir aussi