Gérer les sandboxes

Gérez le cycle de vie des sandboxes dans CodeCourier - surveillez le statut, envoyez des messages, arrêtez les sessions et gérez le nettoyage.

7 min lire
sandboxesmanagelifecycle

Une fois qu’une sandbox est en cours d’exécution, CodeCourier fournit des outils pour surveiller sa progression, interagir avec l’agent IA et gérer la sandbox tout au long de son cycle de vie. Ce guide couvre le suivi du statut, la messagerie, l’arrêt, le nettoyage et le système de suppression douce/restauration.

États du cycle de vie de la sandbox

Chaque sandbox dans CodeCourier se trouve dans l’un des cinq états. Ils sont stockés dans le champ status de l’enregistrement de la sandbox et déterminent quelles actions sont disponibles.

Creating

La sandbox a été demandée mais la machine virtuelle E2B est encore en cours de provisionnement. Pendant cette phase, CodeCourier a créé un enregistrement en base de données et attend que E2B renvoie un ID de sandbox. Aucune interaction n’est encore possible.

Running

La sandbox est active. L’agent IA s’exécute à l’intérieur de la VM et vous pouvez envoyer des messages, visualiser la sortie de terminal en streaming et surveiller la progression. Le compteur de sandboxes actives du projet est incrémenté lorsqu’une sandbox entre dans cet état.

Paused

La sandbox a été suspendue. L’état de la VM est préservé mais l’agent ne s’exécute pas activement. Les sandboxes en pause peuvent être reprises. Cet état est principalement utilisé par la fonctionnalité pause/reprise d’E2B pour les environnements de longue durée.

Killed

La sandbox a été arrêtée. La VM E2B a été détruite et tout l’état en mémoire est perdu. Les fichiers commités dans Git avant l’arrêt sont préservés dans le repository distant. Une sandbox passe à killed lorsque vous l’arrêtez manuellement, lorsque le timeout expire ou lorsqu’une étape de workflow se termine.

Error

La sandbox a rencontré une erreur fatale. Le champ error de l’enregistrement de la sandbox contient le message d’erreur. Les causes courantes incluent des clés API manquantes, des échecs de provisionnement E2B et des crashs d’agent irrécupérables.

Transitions d’état

Le dashboard affiche des mises à jour de statut en temps réel propulsées par des requêtes réactives Convex. Lorsqu’une sandbox passe d’un état à un autre, l’interface se met à jour automatiquement. Le compteur de sandboxes actives dans la vue d’ensemble de votre projet reflète le nombre de sandboxes à l’état « running ».

Surveiller l’activité de la sandbox

Sortie de terminal en streaming

Lorsque vous ouvrez une sandbox en cours d’exécution dans le dashboard, vous voyez une vue de terminal en streaming qui affiche la sortie de l’agent IA en temps réel. Cela inclut :

  • Les réponses texte du modèle IA.
  • Les indicateurs d’utilisation d’outils (éditions de fichiers, exécution de commandes, recherches).
  • Les messages d’erreur et avertissements.
  • Les mises à jour de progression à mesure que l’agent avance dans sa tâche.

La sortie de terminal est propulsée par la table sandboxMessages. Chaque message a un role (user ou assistant), un content et un streamLog optionnel pour les données de streaming brutes. Les messages portent aussi un champ status (streaming, completed ou error) pour indiquer si la réponse est encore en cours de génération.

Vue détaillée de la sandbox

La page de détail de la sandbox affiche des informations complètes sur la sandbox :

  • Badge de statut - Indicateur visuel de l’état actuel du cycle de vie.
  • Configuration - Réglages de template, modèle, timeout, mémoire et CPU.
  • Métadonnées - Heure de création, run ou session d’issue liée, trigger run ID.
  • Informations Git - URL du repository, nom de branche et statut de PR (si une pull request a été créée).
  • Statut d’extraction des learnings - Si des learnings ont été extraits de l’historique de messages de la sandbox.

Envoyer des messages

Pour les sandboxes autonomes (ne faisant pas partie d’un workflow run), vous pouvez envoyer des messages de suivi à l’agent IA pendant son exécution. C’est le mode interactif de CodeCourier - il fonctionne comme une conversation de chat où chaque message déclenche un travail supplémentaire de l’agent.

Lorsque vous envoyez un message :

  1. Le message est stocké dans la table sandboxMessages avec le role user.
  2. Une tâche Trigger.dev transmet le message à la sandbox E2B en cours d’exécution.
  3. Le CLI IA reçoit le message et commence à générer une réponse.
  4. La réponse est renvoyée en streaming et stockée comme message avec le role assistant.

Si la sandbox a déjà terminé sa tâche initiale et que l’agent est inactif, le message de suivi utilise le flag --continue du CLI pour reprendre le contexte de la conversation.

Sandboxes de workflow

Vous ne pouvez pas envoyer de messages interactifs aux sandboxes qui font partie d’un workflow run. Les sandboxes de workflow sont gérées par l’orchestrateur et reçoivent leurs prompts depuis la configuration de l’étape du pipeline.

Arrêter et tuer les sandboxes

Arrêt manuel

Vous pouvez arrêter une sandbox en cours d’exécution à tout moment depuis le dashboard. Lorsque vous tuez une sandbox :

  1. CodeCourier envoie une commande d’arrêt au processus CLI IA à l’intérieur de la sandbox (par exemple, pkill -9 -f '[c]laude' pour Claude Code).
  2. Avant de détruire la VM, CodeCourier détecte tout repository Git dans la sandbox et tente un push best-effort des changements non commités.
  3. Si une branche non par défaut avec un remote est détectée, une pull request est créée automatiquement.
  4. La sandbox E2B est arrêtée et le statut est mis à jour vers killed.

Timeout automatique

Chaque sandbox a un timeout configuré. Lorsque le timeout expire, E2B détruit automatiquement la VM. CodeCourier détecte cela et met à jour le statut de la sandbox en conséquence. Le timeout par défaut est de 15 minutes pour les sandboxes autonomes et varie pour les étapes de workflow selon la configuration du workflow.

Création de pull request

Lorsqu’une sandbox termine son travail (soit en achevant sa tâche, soit en étant tuée), CodeCourier peut créer automatiquement une pull request GitHub. Le flux de création de PR :

  1. Détecter les infos Git de la sandbox : URL du remote et branche actuelle.
  2. Ignorer si la branche est main ou master(aucune PR nécessaire pour les branches par défaut).
  3. Pousser tous les commits non poussés de la sandbox.
  4. Créer une PR via l’API GitHub en utilisant le token GitHub configuré.
  5. Stocker l’URL, le numéro et le statut de la PR sur l’enregistrement de la sandbox.

Le champ de statut de PR suit le cycle de vie de la pull request :creating, created, failed,skipped ou merged.

Extraction des learnings

Après qu’une sandbox se termine, CodeCourier peut extraire des learnings de l’historique de messages de l’agent. Les learnings sont des patterns, préférences, pièges et insights architecturaux que l’agent a découverts pendant l’exécution. Ils sont stockés dans la table learnings et peuvent être compilés en versions de learning qui sont injectées dans les sandboxes futures.

Le statut d’extraction est suivi sur l’enregistrement de la sandbox :

  • pending - L’extraction a été mise en file d’attente.
  • running - L’agent d’extraction traite les messages.
  • completed - Les learnings ont été extraits et stockés.
  • skipped - L’extraction n’était pas nécessaire (par exemple, aucun message).
  • error - L’extraction a échoué. L’erreur est dans learningExtractionError.

Suppression douce et restauration

Les sandboxes prennent en charge la suppression douce. Lorsque vous supprimez une sandbox depuis le dashboard, l’enregistrement n’est pas physiquement retiré de la base de données. À la place, un timestampdeletedAt est défini. Les sandboxes en suppression douce :

  • Sont masquées de la liste par défaut des sandboxes.
  • Ne comptent pas dans les compteurs de sandboxes actives.
  • Peuvent être restaurées à tout moment, ce qui efface le champ deletedAt.
  • Peuvent être supprimées définitivement, ce qui retire physiquement l’enregistrement.

Ce pattern de suppression en deux phases protège contre la perte accidentelle de données. Les compteurs du projet sont ajustés lors des opérations de suppression douce et de restauration.

Gestion des ressources

Suivi des sandboxes actives

CodeCourier maintient un compteur dénormalisé de sandboxes actives par projet. Ce compteur est incrémenté lorsqu’une sandbox entre à l’étatrunning et décrémenté lorsqu’elle le quitte. Le compteur est affiché dans la vue d’ensemble du dashboard de projet.

Suivi d’usage

Chaque session de sandbox génère des enregistrements d’usage qui suivent :

  • Compute E2B - Le temps d’exécution de la sandbox en secondes, facturé par E2B.
  • Usage des tokens IA - Les tokens d’entrée et de sortie consommés par le modèle IA pendant la session.
  • Calcul du coût - Le coût total en USD basé sur les taux de coût d’usage configurés pour chaque service.

Les enregistrements d’usage sont liés à la sandbox via le champ sandboxId et peuvent être consultés dans la section facturation et usage du projet.

Mise à jour du statut de la sandbox (interne)
// How CodeCourier tracks sandbox state transitions
await ctx.runMutation(internal.sandboxes.updateStatus, {
  id: sandboxId,
  status: "killed",
});
// Active counter is automatically decremented
// when transitioning from "running" to any other state