Mode sandbox de Gemini CLI : activation, backends, sécurité YOLO
Le guide illustré sans blabla du sandbox de Gemini CLI : lancer avec -s, l'activer en permanence, choisir le bon backend selon votre OS et offrir un garde-fou au mode YOLO.
L'essentiel
- Lancez gemini -s et toute la session — commandes shell, modifications de fichiers, appels réseau — s'exécute dans un sandbox isolé ; un badge sandbox apparaît dans le pied de page pour confirmer qu'il est actif.
- Trois moyens d'activation, appliqués par ordre de priorité : le flag -s / --sandbox, la variable d'environnement GEMINI_SANDBOX, puis "sandbox": true dans l'objet tools de settings.json.
- Le backend dépend de l'OS : profils Seatbelt sur macOS (permissive-open par défaut), gVisor runsc sur Linux pour l'isolation la plus forte, conteneurs Docker ou Podman ailleurs.
- Le mode YOLO (--yolo) saute toutes les demandes de permission — associez-le au sandbox. La v0.61.0 (23 sept. 2026) a durci les frontières du système de fichiers du sandbox et isolé l'état du runtime.
Gemini CLI Essentials – Full Course (sandboxing chapter)
Chaîne : freeCodeCamp.org3:49:40
Gemini CLI: Everything You Need To Know (Full Tutorial)
Chaîne : lustoykov42:54
Sandboxing in Gemini CLI — official documentation
Docs : google-gemini/gemini-cli (GitHub)
Les captures viennent du chapitre sandbox du cours freeCodeCamp ; noms de flags, réglages et profils ont été vérifiés contre la documentation officielle du sandbox et les notes de version v0.61.0.
Crédits captures : freeCodeCamp.org et lustoykov — enregistrements utilisés comme référence visuelle avec attribution ; tout le texte des étapes est le nôtre.
Sandboxer Gemini CLI, étape par étape
Lancez votre première session en sandbox
- 1
Comprenez ce que le sandbox isole vraiment
Le sandbox met à l'écart de votre système les opérations qui rendent un agent IA dangereux — commandes shell, écritures de fichiers, appels réseau. Gemini CLI v0.61.0 (23 septembre 2026) a durci les frontières du système de fichiers du sandbox et isolé son état d'exécution, fermant les vecteurs d'injection indirecte de prompt via les fichiers de build et les flags non fiables.
Où se situe le sandbox : une bibliothèque d'isolation OS, choisie selon la plateforme.Voir à 140:00 - 2
Lancez-vous directement en sandbox avec le flag
Le plus rapide, c'est le flag en ligne de commande : lancez gemini -s (forme longue --sandbox). Le premier démarrage peut prendre une minute car l'image du sandbox doit parfois être téléchargée. Pour un usage unique, combinez avec un prompt : gemini -s -p "analyze the code structure".
Flag activé, badge dans le pied de page — la vérification express en deux secondes.Voir à 140:50 - 3
Retenez les trois moyens d'activation — et lequel gagne
Gemini CLI résout le sandbox par ordre de priorité : d'abord le flag -s / --sandbox, puis la variable d'environnement GEMINI_SANDBOX (true, docker, podman, sandbox-exec, runsc ou lxc), puis l'entrée "sandbox" dans l'objet tools de votre settings.json.
La doc officielle liste les trois méthodes d'activation par ordre de priorité.Voir à 145:45 - 4
Confirmez la session sandboxée dans le pied de page
Une fois le CLI lancé, la barre d'état affiche un badge sandbox avec la version du composant, juste à côté du sélecteur de modèle. Pas de badge, pas de sandbox — retournez vérifier le flag ou le réglage qui devait l'activer.
Une session réelle en sandbox : le badge côtoie Auto (Gemini 3).Voir à 146:40
Choisissez le bon backend pour votre OS
- 5
Sur macOS, profitez du Seatbelt intégré
macOS n'exige aucun conteneur : Gemini CLI enveloppe le processus avec Seatbelt (sandbox-exec). Le profil par défaut, permissive-open, confine les écritures au répertoire du projet tout en laissant lectures et réseau ouverts. Durcissez le profil via la variable d'environnement SEATBELT_PROFILE : permissive-proxied, restrictive-open, restrictive-proxied, strict-open ou strict-proxied.
- 6
Sur Linux ou WSL2, voici gVisor runsc
gVisor de Google — le runtime runsc — offre l'isolation la plus forte disponible : les conteneurs tournent sur un noyau en espace utilisateur qui intercepte chaque appel système. Sélectionnez-le explicitement avec GEMINI_SANDBOX=runsc ou "sandbox": "runsc" (jamais détecté automatiquement) et Gemini CLI lancera docker run --runtime=runsc pour vous.
La doc positionne runsc comme le backend le plus fort, réservé à Linux.Voir à 141:20 - 7
Installez le runtime runsc
Sur Ubuntu — natif ou dans WSL2 — une commande apt suffit : sudo apt get install runsc. Docker doit aussi être installé et lancé, car Gemini CLI pilote runsc comme un runtime Docker et non comme un outil autonome.
Saisie de la commande d'installation dans un terminal WSL2 Ubuntu.Voir à 143:35 - 8
Vérifiez que l'installation est en place
apt dépaquette runsc directement depuis le dépôt des mises à jour de sécurité d'Ubuntu — pas de PPA supplémentaire. Sans cette étape, un futur gemini -s sous Linux échoue ou retombe silencieusement sur le backend conteneur : vérifiez le paquet avant votre premier run sandboxé.
apt achève le dépaquetage de runsc sur Ubuntu 24.04.Voir à 144:15 - 9
Vous préférez les conteneurs ? Docker ou Podman partout
Le sandbox par conteneur fonctionne partout où tourne Docker ou Podman, et les deux doivent être installés et lancés avant de commencer — exécutez docker une fois pour vérifier que le CLI répond. Le sandbox utilise l'image ghcr.io/google/gemini-cli:latest par défaut et monte votre répertoire de travail exactement au même chemin absolu dans le conteneur.
Une exécution unique de docker pour confirmer que le moteur répond.Voir à 145:30
Lancez le mode YOLO sans transpirer
- 10
Associez le sandbox au mode YOLO
gemini --yolo (raccourci de --approval-mode=yolo) saute dangereusement toutes les demandes de permission — exactement ce que réclament les exécutions autonomes, et exactement à quoi sert un sandbox. Lancez vos sessions YOLO avec le flag sandbox pour que les permissions sautées restent confinées dans l'environnement isolé.
Le mode YOLO en une diapo : zéro interruption, toutes les permissions passées.Voir à 148:20 - 11
Vérifiez que les runs autonomes sont restés sandboxés
Pendant les sessions YOLO, le pied de page affiche un badge bleu YOLO Mode — le signe que les permissions sont sautées. Après le run, le récapitulatif /stats montre quels outils ont tourné, et le badge sandbox reste la preuve que le travail s'est fait dans la boîte.
Le badge YOLO Mode dans le pied de page d'une session autonome terminée.Voir à 147:40
Images de sandbox personnalisées et flags de conteneurs
L'image de conteneur par défaut convient au codage courant. Quand votre projet exige sa propre toolchain — ou quand votre environnement conteneur vous résiste — Gemini CLI vous donne quatre leviers.
- 1Pointez n'importe quelle image : définissez GEMINI_SANDBOX_IMAGE, ou la forme objet dans settings.json — "sandbox": "command": "docker", "image": "..." (a JSON object). Toute image Docker/Podman embarquant bash convient.
- 2Construisez la vôtre : déposez un .gemini/sandbox.Dockerfile à la racine et lancez avec BUILD_SANDBOX=1 — Gemini CLI construit l'image automatiquement. La construction automatique ne fonctionne qu'en exécutant le CLI depuis les sources ; pour une install npm, référencez une image préconstruite.
- 3Ajustez la commande conteneur : SANDBOX_FLAGS injecte des flags docker/podman supplémentaires — par exemple export SANDBOX_FLAGS="--security-opt label=disable" soigne les refus de montage SELinux sur Podman.
- 4Corrigez la propriété des fichiers sous Linux : le sandbox mappe automatiquement les permissions, mais SANDBOX_SET_UID_GID=true force l'UID/GID de l'hôte quand les fichiers générés sortent avec le mauvais propriétaire.
Vous lancez Gemini CLI lui-même dans un conteneur et voulez sandboxer dedans ? Montez /var/run/docker.sock pour que le CLI puisse créer des conteneurs frères via le démon hôte, et alignez le chemin de l'espace de travail sur le chemin absolu de l'hôte — c'est le démon hôte qui résout les montages, pas le conteneur.
Dépannage : erreurs, accès fichiers, désactivation
La plupart des soucis de sandbox tiennent en cinq schémas. Avant tout, reproduisez avec la sortie debug : DEBUG=1 gemini -s -p "your prompt".
- 1"Operation not permitted" — la commande réclame un accès hors sandbox. Passez à un profil plus permissif (macOS : SEATBELT_PROFILE) ou ajoutez les montages requis.
- 2Commandes manquantes dans le sandbox — cuisinez vos outils dans une image personnalisée ou installez-les via sandbox.bashrc. Rappel : l'automatisation BUILD_SANDBOX est réservée aux sources.
- 3Échecs réseau — vérifiez que le profil actif autorise le réseau et contrôlez le proxy ; les profils -proxied acheminent le trafic via le proxy du sandbox.
- 4Fichiers créés avec le mauvais propriétaire sous Linux — basculez SANDBOX_SET_UID_GID (true force l'UID/GID hôte, false désactive le mapping).
- 5Windows a laissé des fichiers marqués Low integrity — le sandbox natif utilise icacls pour marquer les chemins inscriptibles ; rétablissez avec icacls "C:\path\to\dir" /setintegritylevel Medium.
Pour savoir ce que le sandbox peut atteindre, interrogez le CLI : gemini -s -p "run shell command: env | grep SANDBOX" liste les variables d'environnement du sandbox et mount | grep workspace montre les montages. Aucune étape d'export n'est requise — les sandbox conteneurs montent votre projet au même chemin absolu, les modifications tombent directement dans votre dossier. Pour désactiver : retirez le flag -s, faites unset GEMINI_SANDBOX ou supprimez l'entrée "sandbox" de settings.json ; le sandbox au niveau des outils a son propre interrupteur, "security": "toolSandboxing": false (redémarrage requis).