Travailler avec les fichiers

Comprenez le système de fichiers de la sandbox dans CodeCourier - agencement des fichiers, fichiers de projet, intégration Git et persistance des fichiers.

5 min lire

sandboxesfilesfilesystem

Chaque sandbox CodeCourier exécute un système de fichiers Linux complet à l’intérieur d’une micro-VM E2B. Ce système de fichiers est l’espace de travail où les agents IA lisent du code, écrivent des fichiers, installent des paquets et construisent des projets. Comprendre l’agencement des fichiers et la manière dont les fichiers persistent entre les sessions de sandbox est essentiel pour travailler efficacement avec CodeCourier.

Agencement du système de fichiers

Lorsqu’une sandbox démarre, elle a une structure de répertoires Linux standard. Les répertoires clés pour le travail de l’agent IA sont :

Agencement de fichiers standard de la sandbox

/home/user/                    # Home directory (agent working dir)
  project/                     # Cloned Git repository (if configured)
    .claude/                   # Claude Code configuration
      skills/                  # Injected skill files
      commands/                # Injected command files
    CLAUDE.md                  # Project instructions for Claude Code
    .system-prompt.txt         # System prompt file
    package.json               # Project package manifest
    ...                        # All other project files
  .env                         # Environment variables (if configured)
/tmp/                          # Temporary files
/usr/local/                    # Globally installed tools (Node.js, Python, etc.)

Répertoire home

Le répertoire de travail par défaut est /home/user. Lorsque aucun repository Git n’est configuré, l’agent IA travaille directement dans ce répertoire. Tous les outils CLI sont configurés pour l’utiliser comme chemin de base.

Répertoire du projet

Lorsqu’une URL de repository GitHub est configurée (soit depuis les paramètres du projet, soit par sandbox), le repository est cloné dans /home/user/project. Le répertoire de travail de l’agent est défini sur ce chemin. Toutes les opérations Git (création de branche, commits, pushes) se déroulent dans ce répertoire.

Intégration Git

Git est un citoyen de première classe dans les sandboxes CodeCourier. Lorsqu’une sandbox est créée avec une URL de repository GitHub, la séquence de setup gère automatiquement l’intégralité du workflow Git.

Clonage du repository

Pendant le setup de la sandbox, CodeCourier clone le repository configuré dans /home/user/project. Si un token d’accès personnel GitHub est disponible (issu des clés API du projet), il est utilisé pour l’authentification, permettant l’accès aux repositories privés.

Gestion des branches

Pour les workflow runs et les sprint chains, CodeCourier crée automatiquement une branche de fonctionnalité. Le nom de la branche est généralement généré à partir de la description de la tâche. Pour les sandboxes autonomes, l’agent travaille sur la branche qui est checkout après le clonage (généralement main ou master), mais l’agent lui-même peut créer des branches dans le cadre de son travail.

Credential helper

Si un token GitHub est disponible, CodeCourier configure un credential helper Git à l’intérieur de la sandbox. Cela permet à l’agent IA de pousser des commits vers le repository distant sans qu’on lui demande des identifiants. Le credential helper est configuré à l’aide de commandesgit config pendant la phase de setup de la sandbox.

Configuration des credentials Git (simplifiée)

# CodeCourier configures this automatically
git config --global credential.helper store
echo "https://oauth2:${GITHUB_TOKEN}@github.com" > ~/.git-credentials

# Git user identity for commits
git config --global user.name "CodeCourier Agent"
git config --global user.email "agent@codecourier.dev"

Identité Git personnalisée

Vous pouvez configurer un nom et un email de commit Git personnalisés dans les Paramètres du projet. Ces valeurs remplacent l’identité d’agent par défaut pour tous les commits effectués à l’intérieur des sandboxes de ce projet.

Commit et push automatiques

Lorsqu’une sandbox termine son travail ou est tuée, CodeCourier effectue un commit et un push de filet de sécurité. Cela garantit que tout changement non commité effectué par l’agent n’est pas perdu lorsque la VM est détruite :

Stage tous les changements avec git add -A.
Vérifie s’il y a des changements stagés avec git diff --cached --quiet.
Commit avec un message auto-généré si des changements existent.
Push la branche vers le remote.

Il s’agit d’une opération best-effort - si elle échoue (par exemple, aucun remote configuré), l’arrêt de la sandbox se poursuit normalement.

Fichiers de configuration

Pendant le setup de la sandbox, CodeCourier écrit plusieurs fichiers de configuration dans le système de fichiers. Ces fichiers contrôlent le comportement de l’agent IA.

System prompt

Le system prompt est écrit dans /home/user/.system-prompt.txt (ou un chemin similaire selon l’outil). Le CLI IA lit ce fichier au démarrage pour définir les instructions de niveau système de l’agent. Le system prompt provient des paramètres du projet ou du template par défaut.

CLAUDE.md

Pour les outils qui le prennent en charge (Claude Code et Pi), un fichierCLAUDE.md est écrit dans le répertoire du projet. Ce fichier contient des instructions spécifiques au projet, des standards de codage et du contexte que l’agent utilise tout au long de sa session. Le contenu provient du champ claudeMd des paramètres du projet.

Skills et commandes

Les sandboxes Claude Code reçoivent des skills et commandes injectés. Ils sont écrits dans les répertoires .claude/skills/ et .claude/commands/ à l’intérieur du dossier du projet. Chaque skill est une collection de fichiers (généralement un SKILL.md et des fichiers de référence), et chaque commande est un fichier markdown avec des instructions.

Seuls les skills et commandes activés dans les paramètres du projet sont injectés. Cela maintient la fenêtre de contexte concentrée sur les connaissances pertinentes.

Scripts

Des scripts définis par l’utilisateur peuvent aussi être injectés dans la sandbox. Les scripts sont écrits dans le système de fichiers et sont disponibles pour l’agent afin qu’il les exécute. C’est utile pour les scripts de build personnalisés, les runners de test ou les commandes de déploiement.

Learnings compilés

Si le projet dispose de learnings compilés (issus de sessions de sandbox précédentes qui ont été revues et approuvées), ils sont écrits dans la sandbox sous forme de fichier markdown. L’agent peut se référer à ces learnings pour éviter de répéter des erreurs et pour suivre les patterns établis.

Variables d’environnement

Les variables d’environnement au niveau du projet sont injectées dans l’environnement de la sandbox pendant le setup. Elles sont disponibles pour l’agent IA et tous les processus qu’il lance. Les variables d’environnement sont configurées dans les Paramètres du projet et peuvent être marquées comme secrètes (affichées masquées dans l’interface).

En plus des variables configurées par l’utilisateur, CodeCourier injecte plusieurs variables système :

Clés API de provider - Les clés API pour le provider de l’outil CLI configuré (par exemple, ANTHROPIC_API_KEY,OPENROUTER_API_KEY).
Token GitHub - Sous forme de GITHUB_TOKENpour les opérations Git.
Clés Convex - Clés de deploy et de dev pour les projets Convex (si configurées).
Identifiants de test - Email et mot de passe d’utilisateur de test pour les tests E2E (si configurés).

Gestion des secrets

Les clés API et secrets sont récupérés côté serveur via des requêtes Convex internes et injectés directement dans l’environnement de la sandbox. Ils ne sont jamais exposés à l’interface côté client ni stockés dans l’objet de configuration de la sandbox. Les clés chiffrées dans la base de données sont déchiffrées uniquement au moment de la création de la sandbox.

Persistance des fichiers

Les systèmes de fichiers des sandboxes sont éphémères. Lorsqu’une sandbox est tuée ou que son timeout expire, la machine virtuelle E2B est détruite et tous les fichiers sont perdus. Il existe deux mécanismes pour préserver le travail :

Git push

Le mécanisme de persistance principal est Git. Le code commité et poussé vers le repository distant survit à l’arrêt de la sandbox. C’est pourquoi CodeCourier effectue un commit et un push de filet de sécurité lorsque les sandboxes s’arrêtent - cela garantit que le travail de l’agent n’est pas perdu.

Artefacts de pull request

Lorsqu’une pull request est créée à partir du travail de la sandbox, elle sert d’enregistrement durable de ce que l’agent a produit. La PR inclut tous les changements commités et peut être revue, mergée ou rejetée via les workflows GitHub standards.

Pas de téléchargement de fichiers intégré

CodeCourier ne fournit pas actuellement de mécanisme de téléchargement pour des fichiers de sandbox arbitraires. Si vous devez préserver des fichiers qui ne sont pas dans un repository Git, assurez-vous que l’agent les commite ou affiche leur contenu dans le terminal avant que la sandbox ne s’arrête.

Installation des dépendances

Les agents IA installent couramment des dépendances dans le cadre de leur travail. Les templates de sandbox sont livrés avec Node.js et npm préinstallés, et la séquence de setup peut lancer l’installation des paquets automatiquement. CodeCourier inclut un utilitaire npmInstallWithRetry qui gère les échecs transitoires du registre npm en réessayant la commande d’installation.

Les dépendances installées pendant une session de sandbox sont locales à cette sandbox. Elles ne persistent pas entre les sessions à moins d’être commitées dans le repository (par exemple, en mettant à jour package.json et package-lock.json).