Sandboxes E2B

E2B (abréviation de « Environment to Bot ») est le fournisseur de sandbox cloud qui alimente toute l’exécution de code dans CodeCourier. Chaque fois qu’un agent de codage IA exécute une tâche -- que ce soit via une sandbox autonome, un run de workflow ou une session de découverte d’issue -- cela se produit à l’intérieur d’une micro-VM E2B. Cette page explique ce que fournit E2B, comment CodeCourier s’y intègre, les options de configuration et le dépannage des problèmes courants.

Ce que fournit E2B

E2B propose des machines virtuelles cloud isolées à la demande, conçues spécifiquement pour les charges de travail des agents IA. Contrairement aux conteneurs, les sandboxes E2B sont des micro-VM complètes avec leur propre noyau Linux, offrant des garanties d’isolation plus fortes. Les capacités clés incluent :

• Environnement Linux complet -- Chaque sandbox exécute un système Linux complet avec système de fichiers, pile réseau et capacités d’exécution de processus.
• Provisionnement basé sur des templates -- Les sandboxes sont créées à partir de templates préconstruits incluant des outils de développement courants (Node.js, Python, Git, etc.). Des templates personnalisés peuvent être construits avec des outils et configurations supplémentaires.
• Démarrage en moins d’une seconde -- Les micro-VM E2B démarrent en moins d’une seconde, ce qui les rend pratiques pour un usage à la demande.
• Pause et reprise -- Les sandboxes peuvent être mises en pause pour économiser des ressources et reprises plus tard avec leur état complet intact.
• Nettoyage automatique -- Les sandboxes ont des délais d’expiration configurables et sont automatiquement détruites à l’expiration, évitant les fuites de ressources.
• Accès réseau -- Les sandboxes peuvent accéder à Internet pour installer des paquets, cloner des dépôts et communiquer avec des API.

Comment CodeCourier utilise E2B

Provisionnement des sandboxes

Lorsqu’une sandbox est créée (soit par un utilisateur depuis le tableau de bord, soit par une tâche Trigger.dev pendant un run de workflow), CodeCourier appelle le SDK E2B pour provisionner une nouvelle micro-VM. Le processus de provisionnement suit ces étapes :

1. Sélection du template. Le système sélectionne un template de sandbox en fonction de la configuration de l’outil CLI. Des templates personnalisés peuvent être spécifiés, ou le template par défaut pour l’outil CLI choisi est utilisé (par exemple, un template claude pour les sandboxes Claude Code).
2. Configuration de l’environnement. Les variables d’environnement sont injectées dans la sandbox, y compris les clés API (Anthropic, OpenRouter, OpenAI, GitHub), les paramètres de projet, les prompts système et les fichiers de skill.
3. Création de la VM. La méthode Sandbox.create() du SDK E2B est appelée avec le nom du template et les options de configuration, y compris la durée du délai d’expiration.
4. Initialisation de l’agent. Une fois la VM en cours d’exécution, l’outil CLI est lancé à l’intérieur et le prompt initial (le cas échéant) est envoyé à l’agent.

Gestion du cycle de vie

CodeCourier suit l’état de la sandbox selon le cycle de vie suivant :

• "creating" -- E2B provisionne la VM. L’enregistrement Convex existe mais la VM n’est pas encore prête.
• "running" -- La VM est active et l’agent IA s’exécute.
• "paused" -- La VM a été mise en pause pour économiser des ressources. Elle peut être reprise.
• "killed" -- La VM a été terminée. C’est l’état final pour les sandboxes terminées avec succès.
• "error" -- Une erreur est survenue pendant le provisionnement ou l’exécution.

Modèle de communication

CodeCourier communique avec les sandboxes E2B via un modèle d’exécution de processus. La tâche Trigger.dev qui s’exécute dans la couche d’orchestration utilise le SDK E2B pour exécuter des commandes à l’intérieur de la sandbox, lire les flux de sortie et gérer le système de fichiers de la sandbox. Les messages entre l’utilisateur et l’agent IA transitent par Convex (stockés dans la table sandboxMessages) et sont relayés à la sandbox par la tâche Trigger.dev.

Configuration de la clé API E2B

Pour utiliser des sandboxes E2B, vous avez besoin d’une clé API E2B. Cette clé est fournie par chaque utilisateur ou projet, et non au niveau serveur.

Obtenir une clé API E2B

1. Créez un compte sur e2b.dev.
2. Accédez à la section Clés API dans votre tableau de bord E2B.
3. Générez une nouvelle clé API.
4. Dans CodeCourier, allez dans les paramètres de votre projet ou vos préférences utilisateur et ajoutez la clé sous la section du fournisseur E2B.

Stockage de la clé

Les clés API E2B sont chiffrées avant stockage dans la base de données Convex. Seuls les quatre derniers caractères sont stockés en texte clair pour l’affichage (par exemple, ****abcd). Les clés peuvent être définies à deux niveaux :

• Niveau utilisateur -- Stockée dans la table apiKeys. S’applique à tous les projets sauf si remplacée.
• Niveau projet -- Stockée dans la table projectProviderKeys. A priorité sur les clés au niveau utilisateur.

Options de configuration

Lors de la création d’une sandbox, les options de configuration suivantes liées à E2B sont disponibles via l’objet de configuration de la sandbox :

• Template -- Le template E2B à utiliser pour la sandbox. Les templates définissent l’image système de base, les outils préinstallés et la configuration par défaut.
• Délai d’expiration -- Combien de temps la sandbox reste active avant d’être automatiquement terminée. Mesuré en secondes.
• Outil CLI -- Quelle CLI de codage IA exécuter à l’intérieur de la sandbox (Claude Code, OpenCode, Codex, etc.). Cela détermine quel template est sélectionné si un template personnalisé n’est pas spécifié.
• Variables d’environnement -- Variables d’environnement personnalisées injectées dans la sandbox lors de la création. Celles-ci peuvent inclure des paramètres spécifiques au projet, des clés de déploiement et des identifiants de test.

Templates personnalisés

CodeCourier prend en charge les templates E2B personnalisés pour des charges de travail spécialisées. Les templates personnalisés sont utiles lorsque vous avez besoin de :

• Paquets système supplémentaires au-delà du template par défaut
• Frameworks ou runtimes de langage préinstallés
• Configurations système personnalisées ou dotfiles
• Versions spécifiques d’outil CLI

Les builds de templates sont suivis dans la table templateBuilds, qui enregistre l’ID de l’outil, le nom du template, la version CLI, l’état du build et les éventuelles erreurs. Le tableau de bord affiche la progression du build et permet de sélectionner les templates réussis lors de la création de sandboxes.

Considérations de coût

E2B facture en fonction du temps de fonctionnement de la sandbox. Chaque sandbox en cours d’exécution consomme des ressources, que l’agent IA soit activement en train de s’exécuter ou non. Pour optimiser les coûts :

• Définissez des délais d’expiration appropriés pour empêcher les sandboxes oubliées de tourner indéfiniment.
• Utilisez l’action « Arrêter toutes les sandboxes » pour nettoyer une fois votre travail terminé.
• Surveillez le temps d’exécution des sandboxes dans le tableau de bord d’utilisation (voir Suivi de l’utilisation).
• Pour les workflows itératifs, le pattern designer-checker réutilise la même sandbox à travers les itérations plutôt que d’en créer de nouvelles.

Dépannage

La sandbox ne se crée pas

• Vérifiez votre clé API E2B. Assurez-vous qu’elle est valide et non expirée. Essayez de générer une nouvelle clé dans le tableau de bord E2B.
• Vérifiez la disponibilité du template. Si vous utilisez un template personnalisé, assurez-vous qu’il a été construit avec succès.
• Vérifiez le statut du service E2B. Visitez la page de statut E2B pour confirmer que le service est opérationnel.

La sandbox expire prématurément

• Augmentez le paramètre de délai d’expiration dans votre configuration de sandbox ou de workflow. La valeur par défaut peut être trop courte pour des tâches complexes.

L’agent ne peut pas accéder à Internet

• Les sandboxes E2B ont accès à Internet par défaut. Si l’installation de paquets échoue, vérifiez que le registre de paquets est accessible et que la résolution DNS fonctionne à l’intérieur de la sandbox.

Erreurs de clé API à l’intérieur de la sandbox

• Assurez-vous que les clés de fournisseur requises (Anthropic, GitHub, etc.) sont configurées dans les paramètres de votre projet. Les clés manquantes entraîneront l’échec de la CLI de codage IA au démarrage.
• Vérifiez que les clés au niveau projet sont définies pour le bon projet. Les clés au niveau utilisateur peuvent ne pas s’appliquer si une clé au niveau projet (même invalide) existe.