Sandbox
Ce document explique comment exécuter Qwen Code dans un sandbox pour réduire les risques lorsque les outils exécutent des commandes shell ou modifient des fichiers.
Prérequis
Avant d’utiliser le sandboxing, vous devez installer et configurer Qwen Code :
npm install -g @qwen-code/qwen-codePour vérifier l’installation
qwen --versionPrésentation du sandboxing
Le sandboxing isole les opérations potentiellement dangereuses (comme les commandes shell ou les modifications de fichiers) de votre système hôte, fournissant une barrière de sécurité entre le CLI et votre environnement.
Les avantages du sandboxing incluent :
- Sécurité : Empêche les dommages accidentels au système ou la perte de données.
- Isolation : Limite l’accès au système de fichiers au répertoire du projet.
- Cohérence : Garantit des environnements reproductibles sur différents systèmes.
- Sûreté : Réduit les risques lorsque vous travaillez avec du code non fiable ou des commandes expérimentales.
Remarque sur le nommage : Certaines variables d’environnement liées au sandbox peuvent avoir historiquement utilisé le préfixe GEMINI_*. Toutes les nouvelles variables d’environnement utilisent le préfixe QWEN_*.
Méthodes de sandboxing
Votre méthode idéale de sandboxing peut différer selon votre plateforme et votre solution de conteneur préférée.
1. macOS Seatbelt (macOS uniquement)
Sandboxing léger intégré utilisant sandbox-exec.
Profil par défaut : permissive-open – restreint les écritures en dehors du répertoire du projet, mais permet la plupart des autres opérations et l’accès réseau sortant.
Idéal pour : Rapide, pas besoin de Docker, garde-fous solides pour les écritures de fichiers.
2. Basé sur conteneur (Docker/Podman)
Sandboxing multiplateforme avec une isolation complète des processus.
Par défaut, Qwen Code utilise une image sandbox publiée (configurée dans le package CLI) et la téléchargera si nécessaire.
Le sandbox conteneur monte votre espace de travail et votre répertoire ~/.qwen dans le conteneur afin que l’authentification et les paramètres persistent entre les exécutions.
Idéal pour : Isolation forte sur n’importe quel OS, outils cohérents dans une image connue.
Choisir une méthode
- Sur macOS :
- Utilisez Seatbelt lorsque vous souhaitez un sandboxing léger (recommandé pour la plupart des utilisateurs).
- Utilisez Docker/Podman lorsque vous avez besoin d’un environnement Linux complet (par exemple, des outils nécessitant des binaires Linux).
- Sur Linux/Windows :
- Utilisez Docker ou Podman.
Prise en main rapide
# Enable sandboxing with command flag
qwen -s -p "analyze the code structure"
# Or enable sandboxing for your shell session (recommended for CI / scripts)
export QWEN_SANDBOX=true # true auto-picks a provider (see notes below)
qwen -p "run the test suite"
# Configure in settings.json
{
"tools": {
"sandbox": true
}
}Remarques sur la sélection du fournisseur :
- Sur macOS,
QWEN_SANDBOX=truesélectionne généralementsandbox-exec(Seatbelt) s’il est disponible. - Sur Linux/Windows,
QWEN_SANDBOX=truenécessite quedockeroupodmansoit installé. - Pour forcer un fournisseur, définissez
QWEN_SANDBOX=docker|podman|sandbox-exec.
Configuration
Activer le sandboxing (par ordre de priorité)
- Variable d’environnement :
QWEN_SANDBOX=true|false|docker|podman|sandbox-exec - Option de commande / argument :
-s,--sandbox, ou--sandbox=<fournisseur> - Fichier de paramètres :
tools.sandboxdans votresettings.json(par exemple,{"tools": {"sandbox": true}}).
Si QWEN_SANDBOX est défini, il remplace l’option CLI et settings.json.
Configurer l’image sandbox (Docker/Podman)
- Option CLI :
--sandbox-image <image> - Variable d’environnement :
QWEN_SANDBOX_IMAGE=<image> - Fichier de paramètres :
tools.sandboxImagedans votresettings.json(par exemple,{"tools": {"sandboxImage": "ghcr.io/qwenlm/qwen-code:0.14.1"}})
Ordre de priorité (du plus élevé au plus bas) :
--sandbox-imageQWEN_SANDBOX_IMAGEtools.sandboxImage- Image par défaut intégrée du package CLI (par exemple
ghcr.io/qwenlm/qwen-code:<version>)
settings.env.QWEN_SANDBOX_IMAGE fonctionne également comme un mécanisme d’injection d’environnement générique, mais tools.sandboxImage est le paramètre persistant préféré.
Profils Seatbelt macOS
Profils intégrés (définis via la variable d’environnement SEATBELT_PROFILE) :
permissive-open(par défaut) : Restrictions d’écriture, réseau autorisépermissive-closed: Restrictions d’écriture, pas de réseaupermissive-proxied: Restrictions d’écriture, réseau via proxyrestrictive-open: Restrictions strictes, réseau autorisérestrictive-closed: Restrictions maximalesrestrictive-proxied: Restrictions strictes, réseau via proxy
Commencez avec permissive-open, puis resserrez vers restrictive-closed si votre workflow fonctionne toujours.
Profils Seatbelt personnalisés (macOS)
Pour utiliser un profil Seatbelt personnalisé :
- Créez un fichier nommé
.qwen/sandbox-macos-<nom_profil>.sbdans votre projet. - Définissez
SEATBELT_PROFILE=<nom_profil>.
Options sandbox personnalisées
Pour le sandboxing basé sur conteneur, vous pouvez injecter des options personnalisées dans la commande docker ou podman en utilisant la variable d’environnement SANDBOX_FLAGS. Cela est utile pour des configurations avancées, comme la désactivation des fonctionnalités de sécurité pour des cas d’utilisation spécifiques.
Exemple (Podman) :
Pour désactiver l’étiquetage SELinux pour les montages de volumes, vous pouvez définir la variable suivante :
export SANDBOX_FLAGS="--security-opt label=disable"Plusieurs options peuvent être fournies sous forme de chaîne séparée par des espaces :
export SANDBOX_FLAGS="--flag1 --flag2=value"Proxy réseau (toutes les méthodes de sandbox)
Si vous souhaitez restreindre l’accès réseau sortant à une liste d’autorisation, vous pouvez exécuter un proxy local aux côtés du sandbox :
- Définissez
QWEN_SANDBOX_PROXY_COMMAND=<commande> - La commande doit démarrer un serveur proxy qui écoute sur
:::8877
Ceci est particulièrement utile avec les profils Seatbelt *-proxied.
Pour un exemple fonctionnel de proxy de type liste d’autorisation, voir : Script proxy d’exemple.
Gestion UID/GID sous Linux
Sous Linux, Qwen Code active par défaut le mappage UID/GID afin que le sandbox s’exécute en tant que votre utilisateur (et réutilise le ~/.qwen monté). Remplacez par :
export SANDBOX_SET_UID_GID=true # Force l'UID/GID de l'hôte
export SANDBOX_SET_UID_GID=false # Désactive le mappage UID/GIDDépannage
Problèmes courants
“Operation not permitted”
- L’opération nécessite un accès en dehors du sandbox.
- Sur macOS Seatbelt : essayez un
SEATBELT_PROFILEplus permissif. - Sur Docker/Podman : vérifiez que l’espace de travail est monté et que votre commande ne nécessite pas d’accès en dehors du répertoire du projet.
Commandes manquantes
- Sandbox conteneur : ajoutez-les via
.qwen/sandbox.Dockerfileou.qwen/sandbox.bashrc. - Seatbelt : les binaires de votre hôte sont utilisés, mais le sandbox peut restreindre l’accès à certains chemins.
Java non disponible dans le sandbox Docker
L’image Docker officielle de Qwen Code est intentionnellement minimale pour rester petite, sécurisée et rapide à télécharger. Différents utilisateurs ont besoin de différents environnements d’exécution (Java, Python, Node.js, etc.), et il n’est pas pratique de regrouper tous les environnements dans une seule image. Par conséquent, Java n’est pas inclus par défaut dans le sandbox Docker.
Si votre workflow nécessite Java, vous pouvez étendre l’image de base en créant un fichier .qwen/sandbox.Dockerfile dans votre projet :
FROM ghcr.io/qwenlm/qwen-code:latest
RUN apt-get update && \
apt-get install -y openjdk-17-jre && \
apt-get clean && \
rm -rf /var/lib/apt/lists/*Ensuite, reconstruisez l’image sandbox :
QWEN_SANDBOX=docker BUILD_SANDBOX=1 qwen -sPour plus de détails sur la personnalisation du sandbox, voir Personnalisation de l’environnement sandbox.
Problèmes réseau
- Vérifiez que le profil sandbox autorise le réseau.
- Vérifiez la configuration du proxy.
Mode débogage
DEBUG=1 qwen -s -p "debug command"Remarque : Si vous avez DEBUG=true dans un fichier .env du projet, cela n’affectera pas le CLI en raison de l’exclusion automatique. Utilisez les fichiers .qwen/.env pour les paramètres de débogage spécifiques à Qwen Code.
Inspecter le sandbox
# Check environment
qwen -s -p "run shell command: env | grep SANDBOX"
# List mounts
qwen -s -p "run shell command: mount | grep workspace"Notes de sécurité
- Le sandboxing réduit mais n’élimine pas tous les risques.
- Utilisez le profil le plus restrictif qui permette votre travail.
- La surcharge du conteneur est minime après le premier téléchargement/construction.
- Les applications GUI peuvent ne pas fonctionner dans les sandbox.
Documentation associée
- Configuration : Options de configuration complètes.
- Commandes : Commandes disponibles.
- Dépannage : Dépannage général.