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). Le commutateur 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 envelopper.

Deux réglages 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éterminent ce qu’un agent peut pousser, ouvrir ou atteindre, et l’indicateur --sandbox du serveur lui-même.

Ce qui limite l’exécution d’un agent

Six éléments encadrent un agent. Le premier est le bac à sable du système d’exploitation, et c’est le seul qui soit conditionnel — les cinq autres tiennent sur tous les hôtes.

Frontière	Ce qu’elle fait
Le bac à sable du système d’exploitation	Seatbelt sous macOS, bubblewrap sous Linux et WSL2. Enveloppe l’interface de ligne de commande Claude Code, les adaptateurs ACP et l’outil bash du harnais. Absent sous Windows et sous Linux sans bwrap ni socat
Son propre arbre de travail	Chaque conversation obtient 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’impose
Identifiants délivrés par courtage	Le courtier d’identifiants forge un environnement propre à chaque exécution et le révoque au démontage. Son jeton GitHub peut lire, mais pas pousser : une poussée passe par Control Center, qui consulte d’abord la règle de poussée
Garde-fous d’actions	Chaque outil modificateur déclare ses classes d’effet, et le garde-fou les résout avant l’exécution de l’appel. Un prompt sans approbateur connecté est refusé
Assainissement de l’environnement	ACP et l’outil bash du harnais reçoivent un environnement filtré. Claude Code par l’intermédiaire de NoSandboxAdapter hérite de l’environnement de l’hôte
La surface d’outils du mode	Un mode en lecture seule retire carrément les outils qui modifient 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 la barrière d’outils, les contrats d’achèvement et les règles structurelles de mode. L’adaptateur Claude Code, lui, ne le fait pas. Claude Code en particulier est lancé avec --dangerously-skip-permissions, parce qu’un claude -p non interactif bloquerait autrement indéfiniment sur sa propre invite — les appels de lecture, d’écriture et de modification de Claude ne sont donc ni vus ni contrôlé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 lui qui constitue la frontière autour d’eux.
• Les outils de fichiers intraprocessus du harnais (read, write, edit, apply patch, search, find, search_files) s’exécutent dans le processus du serveur, de sorte qu’aucun profil de bac à sable ne les contraint. Seul l’outil bash passe par le lanceur de commandes isolé. Ces outils sont bornés par leur propre confinement des chemins, plus les garde-fous d’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 se rabattent sur l’assainissement de l’environnement et la politique de commandes ; Claude Code hérite de l’environnement de l’hôte par l’intermédiaire de 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 commutateur 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

1. Allez dans Paramètres → Espace de travail → Autorisations des agents
2. 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.

Sans GitHub App, la règle de push n’est qu’indicative

Sans GitHub App configurée, l’exécution reçoit le jeton d’accès personnel de repli, qu’il est impossible de restreindre à la lecture seule. git push passe toujours par la passerelle et la règle, mais du code qui utilise directement le jeton peut pousser en la contournant. Configurez la GitHub App pour que la règle soit contraignante.

L’identifiant GitHub de l’exécution est toujours celui du courtier — un jeton d’installation de GitHub App limité au dépôt, ou le PAT de repli — jamais le jeton stocké du membre demandeur. Le PAT du serveur est retenu pour une exécution qui agit pour un membre qui n’est pas propriétaire et n’a pas connecté GitHub.

Vérifier si vos exécutions d’agent passent par le bac à sable

Deux éléments le déterminent, tous deux côté serveur : si l’hôte offre un backend et si --sandbox est activé. Vérifiez-les dans cet ordre.

1. Allez dans Paramètres → Serveur → Diagnostics et confidentialité
2. Lisez la carte Bac à sable. Le fait Hôte désigne la machine sur laquelle cc_server s’exécute, et non celle que vous consultez. Le champ Back-end indique Native sandbox (Seatbelt sous macOS, bubblewrap sous Linux et WSL2) ou No isolation. Le fait En vigueur correspond à la préférence de cet appareil, et non à l’enveloppe que le serveur utilise réellement.
3. Lisez le journal de démarrage du serveur. Il affiche exactement l’une des trois lignes suivantes :
   • agent sandbox ON suivi de la note sur le backend — les exécutions sont enveloppées
   • no OS-native agent sandbox on this host suivi, s’il y en a un, d’un indice d’installation — les exécutions ne sont pas enveloppé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 précisément la raison d’être 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 n’obtiennent jamais d’enveloppe de bac à sable native. Sous Windows, la sonde native signale toujours que le bac à sable est indisponible et il n’y a rien à installer — le lancement d’agents utilise none. Le backend microvm est distinct (terminaux interactifs et rigs) et son activation dépend de la sonde sur son propre moteur d’exécution. Sous Linux et WSL2, bwrap et socat doivent tous deux se trouver dans le PATH ; sans eux, la sonde signale que le bac à sable est indisponible et nomme les paquets manquants.

Sous Linux/WSL2 avec bubblewrap installé, les globs de fichiers 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 les règles en silence. Une sonde de démarrage positive ne garantit donc pas qu’un lancement sous Linux pourra démarrer. --sandbox off est une désactivation délibérée sans confinement, et non une frontière de sécurité de remplacement.

Savoir ce qu’un mode interdit déjà

Le mode est stocké par espace et alimente le résolveur de garde-fous comme couche 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’effet :

Mode	Arbre de travail	Refusé par le préréglage
Agent (chat)	Inscriptible	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, ouvrir une PR, publier ou fusionner, écrire dans un outil de suivi externe, installer un paquet, exécuter un processus, modifier la structure de l’espace de travail, démarrer ou piloter une enceinte
Review	Lecture seule	Les mêmes onze. Non sélectionnable par l’utilisateur — le composeur n’offre que Agent, Plan et Orchestrate
Orchestrate	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 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, et non un réglage du bac à sable.

1. Allez dans Paramètres → Espace de travail → Autorisations des agents
2. 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 demande votre avis. Si aucun approbateur n’est 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 n’ai jamais refusé quoi que ce soit

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

Alors les exécutions d’agent sur cet hôte ne sont pas enveloppées par Seatbelt ou bubblewrap, et les frontières restantes sont tout ce qui vous protège. Sous Linux et WSL2, installez les deux outils manquants, sudo apt-get install bubblewrap socat, puis 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 intraprocessus du harnais (read, write, edit, apply patch, search, find, search_files) s’exécutent dans le processus du serveur, de sorte qu’aucun profil de bac à sable ne s’y applique — leur limite est leur propre confinement des chemins, plus les garde-fous. Une commande bash ou l’interface de ligne de commande Claude Code est enveloppée là où un backend existe, et vos copies de travail enregistrées sont en refus d’écriture à l’intérieur de cette enveloppe dans tous les modes, y compris sous leur forme résolue par lien symbolique (sous macOS, un chemin atteint par /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 catégoriquement Écrire hors de l’arbre de travail.

Guides connexes

• Configurer les garde-fous
• Créer et configurer un agent
• Diagnostiquer un agent
• Backends de bac à sable
• CLI cc_server : l’indicateur --sandbox

Concepts connexes

• Bac à sable et sécurité
• Modes