Exécuter Claude Code ou des agents gérés dans un bac à sable isolé

Exécutez des agents de codage de type Claude Code ou des agents gérés dans un bac à sable en donnant à chaque agent un espace de travail limité, des permissions de fichiers explicites, une exécution de shell contrôlée, une politique réseau et de paquets, des limites claires pour les secrets, des journaux durables, des artefacts capturés et une révision humaine avant que les modifications ne soient fusionnées ou déployées. L’agent peut toujours lire le code, modifier des fichiers, installer des dépendances, exécuter des tests et produire un correctif, mais l’environnement qui l’entoure décide ce qu’il peut toucher, ce qu’il peut récupérer, quelles informations d’identification il peut voir et quand une personne doit approuver l’étape suivante.

Ce qui doit être isolé

Un agent de codage n’est pas seulement un chatbot attaché à un dépôt. Dès qu’il peut modifier des fichiers et exécuter des commandes, il commence à ressembler à un ouvrier de build junior avec un raisonnement de modèle de langage dans la boucle. Cet ouvrier peut exécuter npm test, inspecter des fichiers générés, démarrer un serveur de développement ou essayer une installation de paquet parce qu’un message d’erreur le suggère. Si l’espace de travail est votre ordinateur portable, un runner CI partagé ou une VM de production à longue durée de vie, le rayon d’explosion est trop large.

La cible d’isolation est l’ensemble de la boucle de travail de l’agent :

• Le checkout du dépôt et la branche que l’agent peut lire ou modifier.
• Les chemins du système de fichiers que l’agent peut écrire.
• Les commandes qu’il peut exécuter automatiquement.
• Les commandes qui nécessitent une approbation.
• Les registres de paquets, domaines et API qu’il peut atteindre.
• Les informations d’identification exposées à la session.
• Les journaux, diffs, sorties de test, captures d’écran et artefacts préservés pour la révision.
• Le comportement de nettoyage après succès, échec ou dépassement de délai.

Claude Code et d’autres produits d’agents de codage gérés peuvent inclure leurs propres systèmes de permissions. La documentation de Claude Code d’Anthropic, par exemple, décrit les paramètres de permission pour les outils autorisés et refusés, le comportement d’approbation et les conseils de sandboxing pour une utilisation locale. Traitez ces contrôles comme une couche, et non comme la limite entière. Une conception plus solide place également l’agent à l’intérieur d’un environnement d’exécution isolé, puis applique les permissions d’outils à l’intérieur de cet environnement.

Architecture de référence

Un flux de travail pratique d’agent en bac à sable comporte quatre couches :

Couche	Objectif	Contrôle typique
Contrôleur d’agent	Décide le plan de tâche et les appels d’outils	Permissions du modèle/outils, mode d’approbation, invite de tâche
Environnement d’exécution du bac à sable	Héberge l’espace de travail où les commandes s’exécutent	Système de fichiers isolé, limites de processus, contrôles de cycle de vie
Passerelle de politique	Décide quelles actions sont autorisées	Règles de commande, règles de sortie réseau, politique de paquets, périmètre des secrets
Surface de révision	Permet aux humains d’inspecter les résultats	Diff, journaux, résultats de test, artefacts, pull request

Gardez ces couches séparées. Si le contrôleur d’agent est compromis par une injection d’invite, l’environnement d’exécution du bac à sable et la passerelle de politique devraient toujours limiter ce qui se passe. Si une installation de paquet tire un code inattendu, le réseau et les journaux d’artefacts devraient le rendre visible. Si l’agent produit un correctif plausible, la surface de révision devrait toujours montrer exactement ce qui a changé et quels tests ont été exécutés.

Un objet de politique conceptuel pourrait ressembler à ceci :

workspace:
  mode: ephemeral
  repo_ref: pull-request-branch
  writable_paths:
    - /workspace/project
  readonly_paths:
    - /workspace/reference
commands:
  auto_allow:
    - git status
    - npm test
    - npm run lint
    - pytest
  require_approval:
    - npm install
    - pip install
    - docker build
    - git push
  deny:
    - rm -rf /
    - curl ... | sh
network:
  default: deny
  allow:
    - registry.npmjs.org
    - pypi.org
    - files.pythonhosted.org
secrets:
  expose:
    - READ_ONLY_PACKAGE_TOKEN
  deny:
    - PRODUCTION_DATABASE_URL
    - CLOUD_ADMIN_TOKEN
artifacts:
  capture:
    - git diff
    - test-results/
    - screenshots/
    - command-log.jsonl

Ce n’est intentionnellement pas un exemple de SDK. Le format exact de la politique dépend de votre framework d’agent et de votre fournisseur de bac à sable. Le point important est que les permissions doivent être exprimées en dehors du raisonnement libre du modèle, puis appliquées par l’environnement d’exécution ou la couche d’orchestration.

Configuration de l’espace de travail et du dépôt

Commencez chaque exécution d’agent à partir d’un espace de travail propre. Un agent géré ne devrait pas hériter de l’historique du shell d’un développeur, de l’agent SSH, des fichiers dotfiles, de la connexion CLI cloud ou des fichiers locaux non suivis, sauf s’il y a une raison délibérée.

Pour le travail sur le dépôt, utilisez un checkout dédié :

• Clonez ou montez uniquement le dépôt nécessaire à la tâche.
• Créez une nouvelle branche de tâche au lieu de modifier la branche par défaut.
• Fixez le commit de base afin que la révision puisse reproduire le point de départ.
• Gardez les caches de dépendances séparés des chemins source accessibles en écriture.
• Stockez les artefacts générés en dehors de l’arborescence source, sauf s’ils font partie du diff prévu.

L’isolation de la branche est importante car les agents de codage essaient souvent plusieurs approches avant d’en choisir une. Une branche de tâche propre donne aux réviseurs un diff de pull request normal au lieu d’un espace de travail mélangé contenant des expériences temporaires. Si l’agent doit comparer avec une implémentation de référence, montez cette référence en lecture seule.

Pour les agents gérés de longue durée, décidez si le bac à sable est éphémère, mis en pause ou instantané. Les espaces de travail éphémères sont plus faciles à raisonner. Les instantanés et la pause/reprise sont utiles pour les longs travaux, les sessions de navigateur et les étapes de configuration coûteuses, mais ils doivent toujours préserver une piste d’audit claire : quand l’instantané a été créé, quels fichiers étaient présents et quelles informations d’identification étaient disponibles.

Permissions du système de fichiers

La portée du système de fichiers devrait être plus étroite que « l’agent peut lire toute la machine ». La plupart des tâches de codage nécessitent :

• Un accès en lecture/écriture à l’espace de travail du dépôt.
• Un accès en lecture seule à certains contextes de tâche, fixtures ou documentation.
• Un répertoire temporaire pour les sorties de build et les fichiers temporaires.
• Aucun accès aux répertoires personnels de l’hôte, aux dépôts non liés, aux informations d’identification cloud, aux profils de navigateur ou aux dumps de données de production.

Les permissions d’écriture méritent une attention particulière. Un agent de codage qui peut modifier un dépôt peut également modifier des scripts, des tests, des lockfiles, la configuration CI et les fichiers de déploiement. Cela peut être exactement ce que la tâche nécessite, mais cela doit être visible lors de la révision. Pour les chemins sensibles, tels que .github/workflows/, les manifests de déploiement ou la configuration de publication de paquets, exigez soit une étape d’approbation plus forte, soit une révision finale appartenant à un humain.

Utilisez des listes d’autorisation de fichiers lorsque la tâche est étroite. Par exemple, un agent de documentation peut n’avoir besoin que du dossier docs/ et d’un répertoire d’aperçu généré. Un agent de mise à jour de dépendances peut avoir besoin de package.json, des lockfiles et des instantanés de test. Une refonte large nécessite un accès plus large, mais la révision devra alors s’attendre à un diff plus important et à des tests plus complets.

Politique d’exécution du shell

L’accès au shell est l’endroit où les agents de codage deviennent utiles et risqués. Ils ont besoin d’exécuter des commandes pour lancer des tests, formater du code, inspecter les erreurs de build et vérifier les correctifs. Ils n’ont pas besoin d’une autorité illimitée pour exécuter n’importe quelle commande sans pause.

Une bonne politique de shell comporte trois catégories :

Catégorie	Exemples	Pourquoi c’est important
Auto-autorisées	git status, npm test, pytest, go test ./..., npm run lint	Maintient les boucles normales de test-édition rapides
Nécessitant une approbation	installations de paquets, migrations, services longue durée, CLI externes, git push	Ajoute une friction là où l’état, le coût ou le risque réseau change
Refusées	commandes destructrices de l’hôte, récupération d’informations d’identification, piping shell dangereux, écriture en dehors de l’espace de travail	Bloque les actions qui ne devraient pas être déléguées

Ne vous fiez pas uniquement à la correspondance de texte de commande. Les agents peuvent exécuter des commandes via des scripts, des hooks de gestionnaire de paquets ou des shells imbriqués. Pour les environnements à plus haut risque, combinez la politique de commande avec des limites du système de fichiers au niveau de l’exécution, des limites de ressources et des contrôles réseau.

Les commandes de longue durée ont besoin d’un comportement de délai d’attente. Un serveur de test, une exécution d’automatisation de navigateur ou un watcher de build peuvent rester actifs après que l’agent est passé à autre chose. Capturez les identifiants de processus, stdout, stderr, le statut de sortie, la durée d’exécution et la raison de la terminaison. Si une commande ouvre un port de prévisualisation, enregistrez le mappage de port et fermez-le lors du nettoyage.

Installations de paquets et trafic réseau sortant

L’installation de paquets est l’une des fonctionnalités les plus utiles d’un espace de travail d’agent et l’un des endroits les plus faciles pour que le risque entre. Un agent de codage peut installer un paquet parce qu’une réponse Stack Overflow, un README ou un plan généré par le modèle l’a suggéré. Cela peut modifier le graphe de dépendances, exécuter des scripts d’installation et atteindre des registres externes.

Pour les guides d’implémentation et les workflows de production, commencez par une posture réseau par défaut-refus, puis autorisez ce dont la tâche a besoin :

• Les registres de paquets tels que npm ou PyPI, de préférence via un miroir ou un cache de registre.
• Les hôtes sources nécessaires pour le dépôt et les sous-modules.
• Les domaines de documentation nécessaires pour la tâche.
• Les API internes uniquement lorsque le bac à sable a la classification de données appropriée.

Évitez de donner à chaque agent un accès Internet sortant large par défaut. Si un accès large est requis pour la recherche ou l’automatisation de navigateur, séparez cette exécution des exécutions de modification de code et étiquetez l’artefact en conséquence.

Pour les installations de paquets, enregistrez :

• La commande du gestionnaire de paquets.
• L’hôte du registre.
• Les modifications du lockfile.
• Les noms et versions des paquets téléchargés lorsque disponibles.
• Tous les scripts d’installation qui ont été exécutés.
• Si un humain a approuvé l’installation.

Cela ne rend pas les paquets arbitraires sûrs. Cela rend le changement révisable.

Limites des secrets

Les secrets doivent être limités à la tâche, de courte durée et absents par défaut. Le bac à sable le plus sûr n’est pas celui qui promet qu’un modèle ne révélera jamais un secret ; c’est celui où le secret n’est pas présent à moins que la tâche ne l’exige vraiment.

Utilisez ces valeurs par défaut :

• Aucune information d’identification de base de données de production dans les espaces de travail des agents.
• Aucun jeton d’administration cloud.
• Aucune clé SSH personnelle ni information d’identification de machine de développeur.
• Des informations d’identification en lecture seule lorsque cela est possible.
• Des jetons séparés pour les lectures de paquets, les fixtures de test ou les API propres au staging.
• Une rédaction dans les journaux avant le partage des artefacts.

Si l’agent doit appeler un service externe, fournissez un jeton restreint et enregistrez quel outil ou commande l’a utilisé. Évitez de placer des informations d’identification larges dans des fichiers que l’agent peut modifier. Les variables d’environnement sont pratiques, mais elles peuvent toujours être imprimées par des commandes, incluses dans des journaux ou copiées dans des fichiers générés. Traitez-les comme exposées au processus de l’agent.

Journaux, artefacts et pistes d’audit

La révision humaine n’est utile que lorsque les réviseurs peuvent voir ce qui s’est passé. Une exécution d’agent de codage en bac à sable devrait préserver plus que le correctif final.

Capturez au moins :

• L’invite de tâche ou le résumé des instructions.
• Le commit de base et la branche.
• Les fichiers lus et écrits lorsque votre outillage peut les enregistrer.
• Les commandes exécutées, avec horodatages, répertoire de travail, statut de sortie, stdout et stderr.
• Les résumés d’installation de paquets et d’accès réseau.
• Les résultats de test et de build.
• Les fichiers générés, captures d’écran, rapports ou liens de prévisualisation.
• Le diff final.

Stockez les journaux dans une surface de révision qui survit au bac à sable. Si le bac à sable est détruit immédiatement après l’exécution, les preuves doivent toujours être disponibles dans la pull request, le magasin d’artefacts CI ou l’enregistrement de la plateforme d’agent.

Pour les équipes utilisant des agents gérés, cette piste d’audit aide également à comparer les performances des agents. Vous pouvez voir si les échecs provenaient de dépendances manquantes, d’une commande refusée, d’une invite peu claire, de tests instables ou d’un vrai problème de code.

Nettoyage et réinitialisation

Le nettoyage du bac à sable est un contrôle de sécurité et de coût, pas seulement une question de rangement. À la fin d’une exécution :

• Arrêtez les processus en arrière-plan.
• Fermez les ports exposés.
• Révoquez les jetons limités à la tâche.
• Exportez les artefacts requis.
• Supprimez les fichiers temporaires qui ne font pas partie de la révision.
• Détruisez, mettez en pause ou prenez un instantané du bac à sable selon le type d’exécution.

La réinitialisation éphémère est la valeur par défaut la plus propre pour un travail non fiable ou exploratoire. Pour les agents de longue durée, prenez un instantané uniquement après une étape de configuration connue comme bonne, et non après une activité arbitraire de l’agent. Si une exécution échouée nécessite une enquête, préservez le bac à sable ou l’instantané avec une date d’expiration claire.

Où se situe Novita Agent Sandbox

Novita Agent Sandbox est conçu pour les flux de travail d’exécution d’agents IA où le code s’exécute dans des espaces de travail cloud isolés plutôt que sur un ordinateur portable de développeur ou un hôte partagé. La documentation de Novita Sandbox décrit les primitives de base qui correspondent au modèle de ce guide : gestion du cycle de vie du bac à sable, opérations sur le système de fichiers, exécution de commandes, modèles et gestion de l’exécution pour les charges de travail des agents.

Cela fait de Novita un choix approprié pour les équipes qui construisent des flux de travail d’agents de codage, d’analyse de données, d’agents navigateurs, d’évaluation ou d’agents de longue durée qui ont besoin d’un environnement d’exécution en plus des API de modèle. Gardez la limite claire, cependant : cet article est un modèle d’implémentation général pour les agents de codage de type Claude Code et les agents gérés. Il ne revendique pas une intégration officielle avec Claude Code, un partenariat ou une compatibilité universelle avec chaque produit d’agent géré.

Si vous concevez un flux de travail basé sur Novita, utilisez les documents du produit pour la surface API exacte publiée et gardez votre couche de politique explicite. Le bac à sable peut fournir l’espace de travail d’exécution isolé ; votre application doit toujours décider des approbations de commandes, de la politique réseau, de la portée des secrets, de la conservation des artefacts et des points de contrôle de révision humaine.

Liste de contrôle de révision de sécurité

Utilisez cette liste de contrôle avant d’autoriser un agent de codage à fonctionner au-delà d’un dépôt jouet :

Question	Ce qu’il faut rechercher
Quelle est la limite d’isolation ?	Espace de travail dédié, limites de processus, séparation du système de fichiers et documentation claire du fournisseur
Que peut lire l’agent ?	Accès au dépôt uniquement par défaut, pas de répertoire personnel de l’hôte, pas de dépôts non liés
Que peut écrire l’agent ?	Les chemins source accessibles en écriture sont explicites ; les chemins de configuration sensibles bénéficient d’une révision supplémentaire
Quelles commandes s’exécutent automatiquement ?	Les commandes de test et de formatage sont autorisées ; les commandes modifiant l’état nécessitent une approbation
Quel accès réseau existe ?	Par défaut-refus ou sortie limitée ; les registres de paquets et les domaines de documentation sont intentionnels
Comment les installations de paquets sont-elles gérées ?	Les modifications du lockfile, les hôtes de registre et les scripts d’installation sont enregistrés
Quels secrets sont présents ?	Informations d’identification limitées à la tâche, de courte durée et de moindre privilège uniquement
Que deviennent les journaux ?	Les commandes, les sorties, les diffs et les artefacts survivent au nettoyage du bac à sable
Comment le nettoyage est-il appliqué ?	Les processus en arrière-plan, les ports, les jetons et les fichiers temporaires sont fermés ou révoqués
Qui approuve la fusion ou le déploiement ?	Un réviseur humain vérifie le code, les tests, les fichiers sensibles à la sécurité et les artefacts générés

La règle la plus importante est simple : ne confondez pas « l’agent a demandé la permission » avec « le système a appliqué une limite ». Le modèle peut aider à expliquer ce qu’il veut faire. L’environnement d’exécution et la couche de politique doivent décider ce qu’il est autorisé à faire.

FAQ

Peut-on exécuter Claude Code dans un bac à sable ?

Oui, si votre configuration place l’agent de type Claude Code dans un espace de travail limité et applique des politiques de système de fichiers, de shell, de réseau, de secrets, de journalisation et de révision autour de lui. Ne supposez pas qu’une simple invite de permission locale suffit pour la production ou les dépôts sensibles.

Un conteneur est-il suffisant pour l’isolation d’un agent de codage ?

Parfois, mais la réponse dépend de votre modèle de menace. Les conteneurs peuvent être utiles pour des builds reproductibles et la séparation des dépendances, mais les charges de travail sensibles à la sécurité doivent évaluer la limite du noyau, les montages de l’hôte, les valeurs par défaut du réseau, les privilèges d’exécution et la documentation du fournisseur avant de traiter un conteneur comme la limite complète du bac à sable.

Les agents devraient-ils être autorisés à installer des paquets ?

Ils peuvent l’être, mais les installations de paquets doivent être traitées comme des événements de chaîne d’approvisionnement contrôlés. Préférez les listes d’autorisation de registre ou les miroirs, la révision des lockfiles, la journalisation des scripts d’installation et l’approbation pour les nouvelles dépendances ou les commandes qui récupèrent et exécutent du code distant.

Que doit vérifier un réviseur humain avant la fusion ?

Révisez le diff final, les commandes exécutées, les tests effectués, les modifications des paquets et des lockfiles, les fichiers CI/déploiement touchés, les artefacts générés et toute action refusée ou nécessitant une approbation. Pour les dépôts sensibles à la sécurité, révisez la politique du bac à sable elle-même dans le cadre du changement.

Novita Agent Sandbox s’intègre-t-il officiellement à Claude Code ?

Cet article ne fait pas cette affirmation. Novita Agent Sandbox fournit des primitives d’exécution isolées pour les flux de travail des agents, tandis que Claude Code et les produits d’agents gérés ont leurs propres interfaces et modèles de permission spécifiques au produit. Validez le chemin d’intégration exact par rapport aux documents actuels du produit avant de publier des commandes exécutables.

Articles recommandés

• Construire un agent de codage avec Novita Agent Sandbox
• Exécuter des évaluations d’agents Harbor sur Novita Agent Sandbox
• Comment utiliser Codex avec les modèles Novita AI