Creare sandbox

Creare una sandbox in CodeCourier provisiona un ambiente Linux cloud isolato in cui un agente di coding IA può lavorare per te. Questa guida spiega come avviare sandbox dall’interfaccia del dashboard, le opzioni di configurazione disponibili e come le sandbox vengono create in modo programmatico durante i workflow run.

Avviare dal dashboard

Il modo principale per creare una sandbox autonoma è tramite la pagina Sandboxes nel dashboard del tuo progetto. La finestra di dialogo di avvio ti permette di configurare ogni aspetto della sandbox prima che venga creata.

Opzioni di configurazione in dettaglio

Selezione del template

Il template ID determina l’immagine E2B di base usata per la sandbox. Ogni strumento CLI ha il proprio template con lo strumento preinstallato. CodeCourier supporta anche template E2B personalizzati - se hai costruito un template personalizzato con strumenti o dipendenze aggiuntive, puoi specificarne l’ID. Quando viene specificato un template personalizzato, CodeCourier usa la funzione buildCustomTag per costruire il tag E2B.

Thinking effort

Per le sandbox Claude Code, puoi configurare il thinking effort per modello. Viene passato tramite il flag --effort al CLI Claude. Le opzioni sono high, medium,low o none. Un thinking effort più alto produce un ragionamento più approfondito ma costa più token.

Template del checker

Le sandbox di workflow supportano un checkerTemplateId separato che permette allo step checker di usare un template E2B diverso da quello dello step designer. Se non impostato, il checker ricade sul template principale.

Override specifici del CLI

La configurazione della sandbox supporta override dello strumento CLI per singolo step:

• designerCliId - Sovrascrive lo strumento CLI per gli step designer.
• optimizerCliId - Sovrascrive lo strumento CLI per gli step optimizer.
• checkerCliId - Sovrascrive lo strumento CLI per gli step checker.

Questo consente a un workflow di usare Claude Code per il lavoro di progettazione e OpenCode per il controllo, ad esempio.

Sequenza di setup della sandbox

Quando una sandbox viene creata, CodeCourier esegue una sequenza di setup multi-fase prima che l’agente IA inizi a lavorare. Questo setup è gestito dalla funzione setupSandboxForTool ed è composto da:

Setup comune (tutti gli strumenti)

1. Git clone - Se è configurato un URL di repo GitHub, il repo viene clonato in /home/user/project. Una nuova branch di feature viene creata per il lavoro della sandbox.
2. Credential helper Git - Se è disponibile un token GitHub, viene configurato un credential helper affinché l’agente possa pushare i commit.
3. Variabili d’ambiente - Le variabili d’ambiente a livello di progetto vengono iniettate nell’ambiente shell della sandbox.
4. System prompt - Il system prompt (dalle impostazioni del progetto o dal valore predefinito) viene scritto in un file che il CLI IA legge.

Setup specifico dello strumento

Ogni strumento CLI ha step di setup aggiuntivi:

• Claude Code - Scrive CLAUDE.md nella directory del progetto, inietta skill e comandi in .claude/skills/ e .claude/commands/, scrive i learning compilati e imposta la chiave API Anthropic.
• OpenCode - Scrive il system prompt come file di config nel formato atteso da OpenCode e imposta la chiave API OpenRouter.
• Codex - Configura la chiave API OpenAI e installa il CLI Codex se non presente nel template.
• Pi - Imposta la chiave API OpenRouter e scrive CLAUDE.md (Pi supporta il formato CLAUDE.md).

Creazione programmatica

Le sandbox vengono create in modo programmatico anche in diversi contesti:

Workflow run

Quando un workflow run viene eseguito, l’orchestratore Trigger.dev crea sandbox per ogni step. La configurazione della sandbox proviene daldefaultConfig del workflow, potenzialmente sovrascritto dalle impostazioni di persona per singolo step. Ogni step ottiene la propria sandbox con lo strumento CLI, il modello e le istruzioni appropriate.

Work chain

Le work chain eseguono una sequenza di issue, ciascuna come un workflow run separato. Ogni run crea le proprie sandbox, riutilizzando la stessa branch per accumulare le modifiche tra le issue.

Sessioni di issue

Le sessioni di issue creano una singola sandbox che esegue un agente IA di scansione. La sandbox di sessione esplora il repository, identifica problemi e miglioramenti e produce una lista strutturata di issue. La sandbox è collegata al record di sessione di issue tramite il camposessionId.

Sessioni di issue

Le sessioni di analisi di issue creano una sandbox che scansiona il repository alla ricerca di potenziali miglioramenti. La sandbox è collegata alla sessione di issue tramite il campo 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(),
});