Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

Mode bac à sable

Statut : actif Portée : état actuel Dernière revue : 2026-08-23 Responsable : runtime AX Code

AX Code inclut un bac à sable d’exécution intégré, qui peut restreindre ce que l’agent fait sur votre système. Par défaut, AX Code démarre en accès complet, bac à sable désactivé, donc les écritures de fichiers et l’accès au réseau ne sont pas limités. Activez workspace-write ou read-only avant de travailler avec des dépôts non fiables ou de lancer des tâches sans surveillance.

Avertissement de sécurité : full-access n’est pas une frontière de sécurité. L’agent peut modifier des fichiers hors de l’espace de travail, écrire .git/ et .ax-code/, lancer des commandes shell sans restriction et accéder au réseau.

Démarrage rapide

Basculez le bac à sable depuis le TUI :

• Saisissez /sandbox dans l’invite, ou
• Appuyez sur Ctrl+P et cherchez « bac à sable »

La barre de statut montre l’état courant :

• bac à sable activé (vert) — agent confiné à l’espace de travail
• bac à sable désactivé (rouge) — aucune restriction

Le réglage persiste d’une session à l’autre dans ax-code.json.

Ce qui change

Configuration

Source de vérité

Cette page résume le comportement visible par l’utilisateur. Lorsque le comportement change, vérifiez la documentation contre :

• packages/ax-code/src/isolation/index.ts pour la résolution du mode, les chemins protégés, les contrôles réseau, les contrôles d’écriture, les contrôles bash et IsolationDeniedError.
• packages/ax-code/src/config/schema.ts pour la forme de la configuration, les défauts et les descriptions.
• packages/ax-code/src/server/routes/isolation.ts pour le comportement de bascule du runtime et la persistance.
• packages/ax-code/test/isolation/isolation.test.ts et packages/ax-code/test/tool/bash.test.ts pour le comportement d’application attendu.

Gardez brèves les affirmations dupliquées dans le README racine, et renvoyez ici pour le détail.

Basculer depuis le TUI

Utilisez /sandbox ou la palette de commandes (Ctrl+P → « Activer ou désactiver le bac à sable »). Le changement prend effet immédiatement et est enregistré dans le ax-code.json de votre projet.

Indicateur CLI

ax-code --sandbox workspace-write   # sandbox on
ax-code --sandbox full-access       # sandbox off
ax-code --sandbox read-only         # strictest: blocks all mutations

Variable d'environnement

AX_CODE_ISOLATION_MODE=workspace-write ax-code

Fichier de configuration

Dans ax-code.json :

{
  "isolation": {
    "mode": "workspace-write",
    "network": false
  }
}

Priorité

Indicateur CLI > variable d’environnement > fichier de configuration > défaut (full-access)

Lorsqu’une surcharge CLI ou d’environnement est active, le TUI rapporte ce mode effectif. Une bascule /sandbox peut enregistrer la préférence du projet, mais la surcharge de priorité plus haute reste active jusqu’à son retrait (en général au redémarrage).

Modes d'isolation

Chemins protégés

En mode workspace-write, ces chemins sont toujours protégés en écriture :

• .git/ — empêche une corruption accidentelle de l’état git
• .ax-code/ — empêche l’altération de la configuration ou des plugins

Ajoutez des chemins protégés personnalisés dans la configuration :

{
  "isolation": {
    "mode": "workspace-write",
    "protected": ["secrets", "credentials"]
  }
}

Accès au réseau

Le réseau est désactivé par défaut dans les modes workspace-write et read-only. Outils concernés :

• webfetch — bloqué
• websearch — bloqué
• codesearch — bloqué
• bash — les clients seulement réseau (curl, wget, nc/ncat/netcat, telnet, ftp, tftp, scp, sftp, dig, nslookup, host) sont bloqués

Limite : le blocage réseau dans bash est de couche applicative et couvre les clients réseau dédiés ci-dessus. Il n’intercepte pas les outils à double usage qui fonctionnent aussi hors ligne (git, npm/pnpm/yarn, pip, go, les interpréteurs de langage tels que python/node), parce que leurs invocations hors ligne ne peuvent pas être distinguées de façon statique et les bloquer casserait des flux courants. Une isolation réseau vraie et exhaustive exige des contrôles au niveau du système, que ce bac à sable ne fournit pas. Lorsqu’un client refusé est atteint, l’agent demande une escalade unique.

Pour autoriser le réseau tout en gardant les restrictions d’écriture :

{
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

Backend d'isolation (application ou système)

macOS : profils Seatbelt via sandbox-exec (écriture limitée à l’espace de travail ou au worktree, réseau refusé lorsque network: false).
Linux : bubblewrap (bwrap) lorsqu’il est installé (--unshare-net lorsque le réseau est désactivé, espace de travail monté en liaison et en lecture-écriture).
Windows : couche applicative seulement, aujourd’hui.

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

Voir SECURITY.md pour le modèle de menace.

Permissions et crochets contrôlés par le dépôt

Les fichiers de projet ne sont pas fiables par défaut. Les règles de permission dans ax-code.json, .ax-code/policy.json et les définitions d’agent ou de mode du projet peuvent resserrer l’accès avec deny, mais les octrois allow/ask contrôlés par le dépôt sont ignorés. Les commandes de projet ne peuvent pas activer l’expansion shell. .ax-code/hooks.json, .ax-code/plugin/ et les plugins configurés par le projet ne sont pas exécutés.

Une configuration de projet non fiable ne peut pas non plus choisir un shell personnalisé, un LSP ou un formateur exécutable, un paquet de fournisseur ou un point de terminaison d’API, des variables d’environnement d’authentifiants de fournisseur, une source de skill externe, ou un chemin d’instructions hors du worktree. Les chemins d’instructions relatifs sûrs et les remplacements intégrés non exécutables restent disponibles. Les serveurs MCP utilisent un flux d’approbation à empreinte distinct, décrit dans Intégrations MCP.

Après avoir revu la configuration contrôlée par le dépôt, les utilisateurs peuvent activer, hors du dépôt, pour le processus courant :

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Le commutateur seulement par environnement empêche un checkout de se déclarer lui-même de confiance.

Comment l'application fonctionne

L’application du bac à sable est toujours de couche applicative, contrôlée à chaque invocation d’outil. Lorsque backend vaut os ou auto et que la plateforme le prend en charge, bash est en plus enveloppé dans un bac à sable noyau.

Lorsqu’un outil viole l’isolation, il lève un IsolationDeniedError avec un message clair qui explique ce qui a été bloqué et pourquoi.