Créer des sandboxes

Créer une sandbox dans CodeCourier provisionne un environnement Linux cloud isolé où un agent de codage IA peut travailler pour vous. Ce guide couvre comment lancer des sandboxes depuis l’interface du dashboard, les options de configuration disponibles et la manière dont les sandboxes sont créées de façon programmatique pendant les workflow runs.

Lancer depuis le dashboard

La principale façon de créer une sandbox autonome passe par la page Sandboxes de votre dashboard de projet. La boîte de dialogue de lancement vous permet de configurer chaque aspect de la sandbox avant sa création.

Options de configuration en détail

Sélection du template

Le template ID détermine l’image E2B de base utilisée pour la sandbox. Chaque outil CLI a son propre template avec l’outil préinstallé. CodeCourier prend aussi en charge des templates E2B personnalisés - si vous avez construit un template personnalisé avec des outils ou dépendances supplémentaires, vous pouvez spécifier son ID. Lorsqu’un template personnalisé est spécifié, CodeCourier utilise la fonctionbuildCustomTag pour construire le tag E2B.

Thinking effort

Pour les sandboxes Claude Code, vous pouvez configurer le thinking effort par modèle. Il est transmis via le flag --effort au CLI Claude. Les options sont high, medium,low ou none. Un thinking effort plus élevé produit un raisonnement plus approfondi mais coûte plus de tokens.

Template de checker

Les sandboxes de workflow prennent en charge un checkerTemplateId distinct qui permet à l’étape checker d’utiliser un template E2B différent de celui de l’étape designer. S’il n’est pas défini, le checker se rabat sur le template principal.

Surcharges spécifiques au CLI

La configuration de la sandbox prend en charge des surcharges d’outil CLI par étape :

• designerCliId - Remplacer l’outil CLI pour les étapes designer.
• optimizerCliId - Remplacer l’outil CLI pour les étapes optimizer.
• checkerCliId - Remplacer l’outil CLI pour les étapes checker.

Cela permet à un workflow d’utiliser Claude Code pour le travail de conception et OpenCode pour la vérification, par exemple.

Séquence de setup de la sandbox

Lorsqu’une sandbox est créée, CodeCourier exécute une séquence de setup en plusieurs phases avant que l’agent IA ne commence à travailler. Ce setup est géré par la fonction setupSandboxForTool et se compose de :

Setup commun (tous les outils)

1. Git clone - Si une URL de repo GitHub est configurée, le repo est cloné dans /home/user/project. Une nouvelle branche de fonctionnalité est créée pour le travail de la sandbox.
2. Credential helper Git - Si un token GitHub est disponible, un credential helper est configuré pour que l’agent puisse pousser des commits.
3. Variables d’environnement - Les variables d’environnement au niveau du projet sont injectées dans l’environnement shell de la sandbox.
4. System prompt - Le system prompt (issu des paramètres du projet ou de la valeur par défaut) est écrit dans un fichier que le CLI IA lit.

Setup spécifique à l’outil

Chaque outil CLI a des étapes de setup supplémentaires :

• Claude Code - Écrit CLAUDE.md dans le répertoire du projet, injecte les skills et commandes dans .claude/skills/ et .claude/commands/, écrit les learnings compilés et configure la clé API Anthropic.
• OpenCode - Écrit le system prompt sous forme de fichier de config dans le format attendu par OpenCode et configure la clé API OpenRouter.
• Codex - Configure la clé API OpenAI et installe le CLI Codex s’il n’est pas présent dans le template.
• Pi - Configure la clé API OpenRouter et écrit CLAUDE.md (Pi prend en charge le format CLAUDE.md).

Création programmatique

Les sandboxes sont également créées de façon programmatique dans plusieurs contextes :

Workflow runs

Lorsqu’un workflow run s’exécute, l’orchestrateur Trigger.dev crée des sandboxes pour chaque étape. La configuration de la sandbox provient dudefaultConfig du workflow, potentiellement remplacée par les réglages de persona par étape. Chaque étape obtient sa propre sandbox avec l’outil CLI, le modèle et les instructions appropriés.

Work chains

Les work chains exécutent une séquence d’issues, chacune comme un workflow run distinct. Chaque run crée ses propres sandboxes, en réutilisant la même branche pour accumuler les changements à travers les issues.

Sessions d’issue

Les sessions d’issue créent une seule sandbox qui exécute un agent IA de scan. La sandbox de session explore le repository, identifie les problèmes et améliorations, et produit une liste structurée d’issues. La sandbox est liée à l’enregistrement de session d’issue via le champsessionId.

Sessions d’issue

Les sessions d’analyse d’issue créent une sandbox qui scanne le repository à la recherche d’améliorations potentielles. La sandbox est liée à la session d’issue via le champ issueSessionId.

// Internal flow: how CodeCourier creates a sandbox
const sandboxId = await ctx.runMutation(internal.sandboxes.create, {
  userId: user._id,
  projectId: project._id,
  sandboxId: e2bSandboxId, // from E2B SDK
  status: "running",
  config: {
    templateId: "claude",
    timeoutMs: 900_000,
    memoryMb: 1024,
    cpuCount: 2,
  },
  createdAt: Date.now(),
});