Configurer les politiques de bac à sable

Le fait qu’une exécution d’agent soit isolée dans un bac à sable se décide sur le serveur, au démarrage (--sandbox). L’interrupteur Activer le bac à sable et le sélecteur Back-end sous Paramètres → Serveur → Diagnostics et confidentialité sont des préférences stockées sur votre appareil. La détection d’hôte de la carte Bac à sable indique ce que l’hôte du serveur peut encapsuler.

Deux contrôles atteignent une exécution, et ce guide couvre les deux : les règles d’action sous Paramètres → Espace de travail → Autorisations des agents, qui décident de ce qu’un agent peut pousser, ouvrir ou atteindre, et le flag --sandbox du serveur lui-même.

Ce qui limite une exécution d’agent

Six choses retiennent un agent. La première est le bac à sable du système d’exploitation, et c’est la seule qui soit conditionnelle — les cinq autres tiennent sur tout hôte.

Frontière	Ce qu’elle fait
Le bac à sable du système d’exploitation	Seatbelt sous macOS, bubblewrap sous Linux et WSL2. Encapsule la CLI Claude Code, les adaptateurs ACP et l’outil `bash` du harnais. Absent sous Windows et sous Linux sans `bwrap` et `socat`
Son propre arbre de travail	Chaque conversation reçoit une copie de travail en copie sur écriture. La copie de travail d’origine est intégrée à l’exécution comme chemin en refus d’écriture, et c’est le bac à sable qui l’applique
Des identifiants délivrés par le courtier	Le courtier d’identifiants émet un environnement par exécution et le révoque au démontage. Son jeton GitHub peut lire mais pas pousser : un push passe par Control Center, qui interroge d’abord la règle de push
Les garde-fous des actions	Chaque outil de mutation déclare ses classes d’effets et le garde-fou les résout avant l’exécution de l’appel. Un `prompt` sans approbateur connecté est refusé
L’assainissement de l’environnement	ACP et l’outil `bash` du harnais reçoivent un environnement filtré. Claude Code via `NoSandboxAdapter` hérite de l’environnement de l’hôte
La surface d’outils du mode	Un mode en lecture seule retire purement et simplement les outils qui mutent l’arbre de travail et épingle le verbe de sortie propre au mode pour qu’il puisse tout de même livrer

Trois choses restent plus faibles qu’elles n’en ont l’air :

Seul le harnais intégré applique le filtre d’outils, les contrats d’achèvement et les règles structurelles des modes. L’adaptateur Claude Code, non. Claude Code en particulier est lancé avec --dangerously-skip-permissions, parce qu’un claude -p non interactif se bloquerait sinon indéfiniment sur sa propre invite — les appels de lecture, d’écriture et d’édition de Claude ne sont donc ni vus ni filtrés par Control Center, et ses commandes bash ne sont vérifiées que par un hook qui lit la ligne de commande. Là où le bac à sable est actif, c’est la frontière qui les entoure.
Les outils de fichiers in-process du harnais (read, write, edit, apply patch, search, find, search_files) s’exécutent dans le processus du serveur, si bien qu’aucun profil de bac à sable ne les contraint. Seul l’outil bash passe par l’exécuteur de commandes encapsulé. Ces outils sont bornés par leur propre confinement de chemins, plus les garde-fous des actions.
Sur un hôte dépourvu de backend, la première ligne ne s’applique pas du tout. ACP et l’outil bash du harnais retombent sur l’assainissement de l’environnement plus la politique de commandes ; Claude Code hérite de l’environnement de l’hôte via NoSandboxAdapter. Le serveur le signale dans son journal de démarrage. Vérifiez le vôtre ci-dessous.

Décider de ce qu’un agent peut pousser

Il n’existe aucun interrupteur par agent pour git push, GitHub, les tickets ou le réseau. Chacun est une règle d’action :

Règle	Valeur par défaut	Ce qu’elle couvre
Pousser vers un dépôt distant	Demander d’abord	Chaque `git push` vers GitHub, quel que soit l’adaptateur
Ouvrir une pull request	Demander d’abord	`gh pr create` et les outils de pull request
Publier une revue ou fusionner	Demander d’abord	`gh pr merge`, `gh pr review`, `gh pr comment`, `gh pr close`
Écrire dans un outil de suivi externe	Demander d’abord	Les écritures de tickets via les outils de Control Center et `gh issue`
Accéder au réseau	Autoriser	Si le bac à sable dispose d’un réseau, et les outils web du harnais

Ouvrez Paramètres → Espace de travail → Autorisations des agents
Choisissez la portée — Espace de travail, Agent ou Espace — puis, sur la ligne de la règle, choisissez Autoriser, Demander d’abord ou Refuser

Les règles de push limitées à des branches, comme une règle qui refuse les push vers main, s’appliquent aussi : voir Garde-fous.

Point de contrôle : demandez à l’agent de pousser une branche. Avec Demander d’abord, vous recevez une demande d’approbation qui nomme le dépôt et les refs ; avec Refuser, git affiche ! [remote rejected] <ref> (Control Center policy: …).

Comment chaque règle atteint l’exécution :

Le push est appliqué par ce que détient l’exécution. Son jeton GitHub est un jeton d’installation de GitHub App en lecture seule, qui peut lire le contenu et travailler avec les pull requests. Sa configuration git envoie chaque push GitHub à une passerelle en boucle locale sur cc_server, qui interroge la règle et ne transmet le push qu’ensuite, avec un jeton d’écriture que l’agent ne voit jamais. La passerelle ne transmet qu’au dépôt propre à l’arbre de travail ou à un dépôt GitHub lié à l’espace de travail. Cela vaut pour tous les adaptateurs.
Les pull requests et les tickets depuis un shell sont reconnus à leur ligne de commande, dans l’outil bash du harnais et, via un hook, dans l’outil Bash de Claude Code. Un agent qui cache la commande (un script, eval, un appel d’API direct) passe ce contrôle, mais pas la passerelle de push.
Les clés de tickets ne sont jamais placées dans le bac à sable. Les agents écrivent les tickets via les outils MCP de Control Center, qui interrogent la règle.
Le réseau est résolu une seule fois, au démarrage de l’exécution. Refuser désactive le réseau du bac à sable ; Autoriser et Demander d’abord le laissent activé, et avec Demander d’abord les outils web_fetch et web_search du harnais continuent de demander à chaque appel. Tant que le réseau est activé, GitHub figure toujours sur la liste d’autorisation de sortie.

Vérifier si vos exécutions d’agent sont isolées

Deux choses en décident, toutes deux sur le serveur : si l’hôte offre un backend et si --sandbox est activé. Vérifiez-les dans cet ordre.

Ouvrez Paramètres → Serveur → Diagnostics et confidentialité
Lisez la carte Bac à sable. Le fait Hôte est la machine sur laquelle s’exécute cc_server, pas celle que vous avez sous les yeux. Le champ Back-end indique Native sandbox (Seatbelt sous macOS, bubblewrap sous Linux et WSL2) ou No isolation. Le fait En vigueur est la préférence de cet appareil, pas l’encapsulation que le serveur utilise réellement.
Lisez le journal de démarrage du serveur. Il affiche exactement l’une de ces trois lignes :
- agent sandbox ON plus la note du backend — les exécutions sont encapsulées
- no OS-native agent sandbox on this host plus une indication d’installation lorsqu’il y en a une — les exécutions ne sont pas encapsulées
- agent sandbox DISABLED by --sandbox off — une désactivation délibérée

GET /healthz ne signale pas l’état du bac à sable, c’est donc le journal de démarrage qui fait foi.

Pour désactiver délibérément le bac à sable — un hôte où le profil se comporte mal est la raison même de l’existence de cette option —, démarrez le serveur avec --sandbox off, ou définissez CC_SERVER_SANDBOX=off. La valeur par défaut est on, et on signifie « utiliser un backend si l’hôte en a un », jamais « en exiger un ».

Deux situations ne reçoivent jamais d’encapsulation par un bac à sable natif. Sous Windows, la sonde native signale toujours l’indisponibilité et il n’y a rien à installer — la répartition des agents utilise none. Le backend microvm est à part (terminaux interactifs et rigs) et dépend d’une sonde sur son propre runtime. Sous Linux et WSL2, bwrap et socat doivent tous deux être dans le PATH ; sans eux, la sonde signale l’indisponibilité et nomme les paquets manquants.

Sur Linux/WSL2 avec bubblewrap installé, les motifs glob de fichiers de secrets de la politique standard ne peuvent pas être appliqués aux fichiers qu’un agent crée par la suite. Une telle exécution native échoue désormais au lieu d’ignorer silencieusement les règles. Une sonde de démarrage positive ne garantit donc pas qu’une répartition sous Linux puisse démarrer. --sandbox off est une désactivation délibérée sans confinement, pas une frontière de sécurité de substitution.

Savoir ce qu’un mode interdit déjà

Le mode est stocké par espace et alimente le résolveur de garde-fous comme couche de préréglage du mode. Trois des quatre modes sont en lecture seule, et un mode en lecture seule refuse d’emblée onze classes d’effets :

Mode	Arbre de travail	Refusé par le préréglage
Agent (`chat`)	Accessible en écriture	Rien — les valeurs par défaut intégrées s’appliquent
Plan	Lecture seule	Supprimer un fichier, écrire hors de l’arbre de travail, créer un commit, pousser vers un dépôt distant, ouvrir une pull request, publier une revue ou fusionner, écrire dans un outil de suivi externe, installer un paquet, exécuter un processus, modifier la structure de l’espace de travail, piloter une enceinte
Revue	Lecture seule	Les mêmes onze. Non sélectionnable par l’utilisateur — le compositeur ne propose qu’Agent, Plan et Orchestration
Orchestration	Lecture seule	Les mêmes onze

L’accès réseau et l’accès aux secrets ne sont délibérément pas refusés par un mode en lecture seule : la recherche est toute la raison d’être d’un tel mode.

Exiger une approbation avant l’exécution d’une action

L’approbation est une décision de garde-fou, pas un réglage de bac à sable.

Ouvrez Paramètres → Espace de travail → Autorisations des agents
Réglez la classe d’action sur Demander d’abord à la portée de l’espace de travail, de l’agent ou de l’espace

Une décision Demander d’abord interrompt l’exécution et vous interroge. Sans approbateur connecté, elle échoue en mode fermé et l’action est refusée. Voir Configurer les garde-fous pour l’ordre de résolution complet.

Dépannage

Un agent ne peut pas pousser et je ne l’ai jamais refusé

Lisez ce que git a affiché. Control Center policy: … signifie qu’une règle a refusé le push ou qu’un Demander d’abord est resté sans réponse. … is not linked to this workspace signifie que le push vise un dépôt qui n’est ni celui de l’arbre de travail ni lié à l’espace de travail. Control Center has no GitHub credential that can push … signifie que la GitHub App n’est pas installée sur ce dépôt et qu’aucun identifiant de repli n’a pu pousser : installez l’App sur ce dépôt ou connectez GitHub.

La carte Bac à sable ne signale aucun bac à sable natif

Les exécutions d’agent sur cet hôte ne sont alors pas encapsulées par Seatbelt ou bubblewrap, et les frontières restantes sont tout ce que vous avez. Sous Linux et WSL2, installez les deux outils manquants — sudo apt-get install bubblewrap socat — et redémarrez le serveur ; le journal de démarrage devrait alors indiquer que le bac à sable est actif. Sous Windows, il n’y a aucun backend natif à installer : resserrez plutôt les garde-fous, voir Configurer les garde-fous.

Un agent a atteint un fichier hors de son arbre de travail

L’outil qui l’a atteint détermine si c’est normal.

Les outils de fichiers in-process du harnais (read, write, edit, apply patch, search, find, search_files) s’exécutent dans le processus du serveur, si bien qu’aucun profil de bac à sable ne s’y applique — leur borne est leur propre confinement de chemins, plus les garde-fous. Une commande bash ou la CLI Claude Code est encapsulée là où un backend existe, et vos copies de travail enregistrées sont en refus d’écriture à l’intérieur de cette encapsulation dans tous les modes, y compris leurs graphies résolues par lien symbolique (sous macOS, un chemin atteint via /tmp ou /var/folders se résout sous /private et les deux graphies sont désormais refusées). Sur un hôte sans backend, rien de tout cela ne s’applique. Dans un cas comme dans l’autre, les garde-fous peuvent refuser d’emblée Écrire hors de l’arbre de travail.