Sandbox Codex : autoriser npm avec un profil de permissions
Conservez les protections de l’espace de travail Codex tout en autorisant le registre de paquets. Configurez un profil de permissions et le proxy réseau, testez les opérations autorisées et bloquées, puis vérifiez les droits de lecture, le sandbox natif et les restrictions de profils imposées par votre entreprise.
Sommaire

Si Codex modifie votre dépôt mais ne peut pas télécharger les paquets npm, vérifiez son profil de permissions avant de modifier les paramètres de l’API. Le profil intégré :workspace désactive le réseau pour les commandes, ce qui concerne les développeurs qui installent des dépendances dans des sessions Codex locales. Créez un profil dérivé de :workspace, activez le proxy réseau et autorisez le nom d’hôte du registre plutôt que d’accorder un accès total.
Au 2026-11-19, OpenAI présente les profils de permissions comme une fonctionnalité bêta. Ce guide configure l’exécution locale des commandes et utilise des exemples Bash pour macOS, Linux ou WSL2.
Que permet le profil par défaut de l’espace de travail ?
Avec un dépôt Git comme racine de l’espace de travail, :workspace autorise les commandes du sandbox à modifier le code source, mais protège certains répertoires. Sous chaque racine, .git, .codex, .agents et .aws restent en lecture seule. Cela empêche les modifications directes de la configuration du dépôt, comme .codex/config.toml, et des hooks dans .git/hooks. Ces protections concernent les chemins situés sous les racines de l’espace de travail, pas tous les répertoires portant ces noms sur la machine.
Les droits de lecture sont plus étendus. Les commandes peuvent lire des fichiers hors du dépôt si vos permissions dans le système d’exploitation le permettent. Dans son explication des limites par défaut du sandbox, OpenAI décrit pourquoi cela permet d’utiliser des compilateurs, SDK, bibliothèques et configurations stockés ailleurs. Cela ne rend pas ces fichiers invisibles aux commandes de Codex.
Le réseau est désactivé parce qu’une commande capable de lire des données ne doit pas automatiquement pouvoir les envoyer à l’extérieur. Le téléchargement de dépendances exige donc un accès supplémentaire. OpenAI précise aussi que les processus enfants héritent des restrictions du sandbox de leur parent. Elles continuent de s’appliquer aux descendants qui restent actifs après la fin de la commande d’origine.
Pour un téléchargement occasionnel, examinez la demande d’accès au réseau plutôt que de modifier votre profil par défaut. Codex peut vous transmettre cette demande ou la soumettre à une vérification automatique, comme l’indique son explication du proxy réseau. Pour des téléchargements fréquents de dépendances, utilisez un profil limité au registre. Laissez le réseau désactivé pour les tâches qui n’en ont pas besoin.
Configurer un profil dev pour le registre npm
Votre installation de Codex CLI doit prendre en charge l’interface documentée codex sandbox --permission-profile. Les vérifications ci-dessous nécessitent également npm, curl et Bash. Validez la politique depuis la racine d’une copie de travail Git temporaire, que vous pourrez supprimer ensuite.
Modifiez votre fichier personnel ~/.codex/config.toml. Intégrez les paramètres suivants aux tables existantes au lieu de définir plusieurs fois les mêmes tables. Cette configuration sélectionne dev comme profil de permissions par défaut.
Ne combinez pas cette configuration avec les anciens paramètres sandbox_mode ou [sandbox_workspace_write]. La documentation des profils de permissions impose de choisir un seul système de configuration, sans mélanger les deux.
default_permissions = "dev"
[features]
network_proxy = true
[permissions.dev]
description = "Workspace editing with npm registry access."
extends = ":workspace"
[permissions.dev.filesystem.":workspace_roots"]
".devcontainer" = "read"
".vscode" = "read"
".env" = "deny"
".env.local" = "deny"
"secrets" = "deny"
[permissions.dev.network]
enabled = true
[permissions.dev.network.domains]
"registry.npmjs.org" = "allow"
"example.com" = "deny"
extends = ":workspace" conserve les protections intégrées, notamment la lecture seule pour .git et .codex. Les entrées supplémentaires empêchent de modifier les paramètres de l’éditeur et du conteneur de développement. Elles bloquent aussi l’accès aux fichiers de variables d’environnement indiqués et au répertoire secrets, avec tout son contenu, sous chaque racine. OpenAI définit les valeurs des permissions du système de fichiers ainsi : read pour la lecture seule, write pour la lecture et l’écriture, et deny pour bloquer l’accès.
La configuration réseau comporte deux paramètres distincts. permissions.dev.network.enabled = true autorise le réseau ; network_proxy = true active l’application des règles de domaine. Comme l’explique la documentation des permissions réseau, activer le réseau sans proxy actif accorde un accès direct au réseau. Les règles de domaine ne sont alors pas appliquées. N’omettez pas le paramètre du proxy.
Le guide de sécurité d’OpenAI pour les entreprises inclut registry.npmjs.org dans son exemple d’accès aux dépendances. Ici, example.com est une destination explicitement interdite pour vérifier le blocage. Selon le fonctionnement documenté des règles de domaine, un refus explicite prime sur une règle d’autorisation correspondante. Les autres destinations nécessitent une approbation ou sont bloquées.
Cette configuration n’ouvre pas un accès illimité à tous les hôtes qu’une installation de paquets pourrait contacter. N’ajoutez un autre nom d’hôte qu’après avoir identifié pourquoi votre projet en a besoin.
Vérifier les permissions et les restrictions
Utilisez codex sandbox pour tester directement des commandes avec le profil. Ajoutez --include-managed-config afin que la résolution du profil tienne aussi compte des exigences administrées. Ce point importe lorsqu’une politique d’entreprise limite vos choix.
Commencez par vérifier le registre depuis Bash :
codex sandbox --permission-profile dev --include-managed-config -- \
npm ping --registry=https://registry.npmjs.org \
--cache="$PWD/.npm-cache"
Un npm ping réussi affiche PONG. Ici, l’option cache place le cache npm dans l’espace de travail. Vous n’avez donc pas à accorder une permission d’écriture supplémentaire pour un cache situé ailleurs. Ce test confirme la connexion au registre, pas que toutes les dépendances ou tous les scripts d’installation pourront être traités jusqu’au bout.
Vérifiez ensuite l’écriture dans l’espace de travail, la protection des métadonnées Git et le domaine interdit. Exécutez ces tests séparément. Le test Git suppose que .git est un répertoire existant, et non un fichier pointant vers le véritable répertoire du dépôt.
# Expect success: create and remove a temporary workspace file.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp ./codex-write-check.XXXXXX) && rm "$p"'
# Expect a filesystem permission denial.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp .git/codex-write-check.XXXXXX) && rm "$p"'
# Expect a proxy policy rejection.
codex sandbox --permission-profile dev --include-managed-config -- \
curl --fail --head --max-time 15 https://example.com
Le résultat attendu est une écriture autorisée dans l’espace de travail, une écriture refusée dans .git et une requête réseau rejetée. Une erreur de configuration, un répertoire absent ou une panne de connexion sans rapport avec la politique ne prouvent pas que la restriction fonctionne. Si l’une des opérations interdites réussit, arrêtez-vous et inspectez la configuration effective avant d’utiliser le profil pour vos tâches habituelles. Il s’agit de vérifications à exécuter, pas de résultats de tests déjà réalisés.
Une fois les résultats attendus obtenus, ouvrez une nouvelle session Codex depuis la racine du dépôt. Lancez /permissions et vérifiez l’entrée dev et sa description, comme l’indique l’exemple de configuration de profil d’OpenAI. Avec ce profil actif, relancez votre installation de dépendances initiale. Gardez son cache dans l’espace de travail ou accordez write uniquement au répertoire externe précis dont elle a besoin.
Que vérifier si les téléchargements échouent encore ?
Si le profil ne s’applique pas, cherchez d’abord les anciens paramètres du sandbox dans la configuration chargée. Vérifiez ensuite la priorité des configurations : les options de ligne de commande ou la configuration d’un projet approuvé peuvent remplacer vos choix par défaut. N’ajoutez pas des permissions à un profil que la session n’utilise pas.
Si npm ping fonctionne mais que l’installation échoue, examinez séparément la destination de la requête en échec et le chemin du système de fichiers. Une requête vers un autre nom d’hôte nécessite sa propre décision d’accès au réseau. Un cache situé hors de l’espace de travail exige une règle appropriée pour y écrire. Les permissions du système de fichiers et du réseau sont distinctes : ouvrir le réseau n’autorise pas l’écriture de fichiers.
Si une destination autorisée reste inaccessible, vérifiez que le client respecte les paramètres du proxy. Les notes d’implémentation du proxy réseau d’OpenAI indiquent que certains programmes ignorent les variables d’environnement du proxy. Diagnostiquez le client ou sa configuration plutôt que de supprimer les restrictions du sandbox.
Un échec de connexion entre Codex et son fournisseur de modèles est différent du blocage d’un gestionnaire de paquets dans le sandbox. Pour l’authentification du fournisseur, la Base URL ou le protocole, consultez le guide de connexion d’une API à Codex.
Les droits de lecture étendus exposent-ils les clés API ?
Oui, elles peuvent rester lisibles. La protection en lecture seule empêche les modifications, pas la lecture. OpenAI précise ce compromis dans son article sur le sandbox Codex. En voici la traduction :
En contrepartie, les fichiers sensibles situés ailleurs sur la machine peuvent aussi rester accessibles en lecture, par exemple les fichiers de configuration contenant des clés API.
Le profil par défaut ne garantit donc pas que les secrets situés hors du dépôt soient cachés.
L’exemple bloque uniquement les chemins précis .env et .env.local, relatifs à la racine, ainsi que le répertoire secrets et son contenu. Il ne couvre pas tous les noms ou emplacements possibles de fichiers contenant des identifiants. Ajoutez les règles deny adaptées aux chemins sensibles de votre environnement, y compris hors de l’espace de travail si nécessaire. Testez-les avec des fichiers inoffensifs plutôt qu’en affichant de véritables identifiants.
Les fichiers modifiables présentent aussi un risque. OpenAI décrit comment la modification d’un paquet installé, comme node_modules/prettier, peut affecter un outil de formatage que l’éditeur exécutera ensuite hors du sandbox. Comme Git ignore souvent node_modules, cette modification peut ne pas apparaître dans git status. Examinez les outils et les dépendances générées qui sont modifiables, en plus des changements du code source suivi par Git.
Les équipes qui utilisent plusieurs agents de programmation devraient aussi vérifier leurs permissions Claude Code pour les secrets et Git. Appliquez la configuration propre à chaque outil au lieu de copier les clés de permissions de Codex dans un autre client.
Pourquoi utiliser le sandbox natif plutôt que Docker ?
Le sandbox natif permet à Codex d’utiliser vos outils de développement existants tout en appliquant des restrictions du système d’exploitation aux commandes lancées. OpenAI présente cette architecture de sandbox natif comme une alternative à la reproduction de tout l’environnement de développement dans un conteneur.
Le développement d’une application iOS sur Mac en est un exemple concret. Dans le scénario décrit par OpenAI, un conteneur Docker ne peut ni exécuter la chaîne de compilation native du Mac, ni lancer le simulateur iPhone. Déléguer ces opérations au Mac hôte les fait sortir du sandbox du conteneur. Les opérations sur l’hôte ont donc besoin de leurs propres restrictions.
Sur macOS, Codex utilise Seatbelt. Pour Linux et WSL2, les instructions d’installation du sandbox d’OpenAI recommandent d’installer bubblewrap avec le gestionnaire de paquets de la distribution. Distinguez un échec de démarrage du sandbox d’une requête refusée vers le registre.
L’exécution native sous Windows nécessite une validation distincte. La documentation du sandbox Windows recommande MXC sur les appareils compatibles. Elle précise aussi que l’ancienne implémentation unelevated ne permet pas d’interdire la lecture de chemins. Réussir les vérifications Bash dans WSL2 ne remplace pas les tests d’application des restrictions sous Windows natif.
Un conteneur reste une option lorsque l’ensemble du travail s’y déroule. Si vos outils dépendent de l’hôte, identifiez et limitez les opérations exécutées sur cet hôte. Ne supposez pas que le conteneur protège aussi les tâches déléguées à l’hôte.
Une entreprise peut-elle interdire le profil dev ?
Oui. Les administrateurs peuvent utiliser un fichier requirements.toml administré pour limiter les profils que les utilisateurs peuvent sélectionner. Une définition locale ne permet pas de contourner cette restriction. L’exemple d’exigences administrées d’OpenAI présente cette politique :
default_permissions = ":read-only"
[allowed_permission_profiles]
":read-only" = true
":danger-full-access" = false
Lorsque allowed_permission_profiles est présent, la table finale fusionnée constitue la liste complète des profils autorisés. Les profils absents de cette table sont refusés, comme ceux explicitement définis sur false. Si l’exemple représente la liste finale après fusion des exigences, votre profil personnalisé dev est indisponible puisqu’il n’est pas autorisé. Demandez à l’administrateur d’approuver un profil adapté à la compilation plutôt que de tenter de contourner la politique.
La documentation de la configuration administrée fixe une condition de version importante : les listes de profils autorisés nécessitent Codex 0.138.0 ou ultérieur. Codex 0.137.0 et les versions antérieures ignorent allowed_permission_profiles et le paramètre administré default_permissions. Vérifiez chaque client administré avant de vous appuyer sur ce contrôle.
Avant le déploiement, testez une compilation autorisée et une action volontairement interdite sur chaque système d’exploitation pris en charge. Limitez les permissions aux registres nécessaires, confirmez que le profil prévu est sélectionné et conservez les tests de blocage lors des mises à jour des clients.