Panoramica delle sandbox

Le sandbox sono la spina dorsale di esecuzione di CodeCourier. Ogni volta che un agente di coding IA esegue un task, scrive codice o lancia un comando, lo fa all’interno di una sandbox - una macchina virtuale Linux cloud isolata ed effimera, alimentata da E2B. Questa architettura garantisce che l’attività dell’agente sia completamente contenuta, riproducibile e sicura, senza alcun rischio per la tua macchina locale o la tua infrastruttura di produzione.

Cos’è una sandbox?

Una sandbox in CodeCourier è un ambiente Linux completo che gira nel cloud. Ogni sandbox è dotata di un file system completo, accesso di rete, capacità di esecuzione dei processi e strumenti di sviluppo preinstallati. Dietro le quinte, CodeCourier usa l’SDK E2B per provisionare questi ambienti on-demand. Quando avvii una sandbox, E2B crea una macchina virtuale leggera a partire da un template, vi inietta la tua configurazione (chiavi API, system prompt, skill, learning) e passa il controllo all’agente di coding IA che hai scelto.

Le sandbox non sono container - sono vere e proprie micro-VM con un proprio kernel, che offrono garanzie di isolamento più forti di Docker. Questo significa che un agente IA in esecuzione dentro una sandbox non può influenzare le altre sandbox, il tuo sistema host né l’ambiente di un altro utente.

Perché le sandbox sono importanti

Eseguire agenti di coding IA sulla tua macchina locale comporta rischi reali. Un agente con accesso al file system può sovrascrivere file, installare pacchetti malevoli o accedere ai segreti memorizzati nel tuo ambiente. Eseguendo ogni task dell’agente all’interno di una sandbox, CodeCourier elimina completamente questi rischi.

• Sicurezza - Ogni sandbox è una micro-VM isolata. Gli agenti non possono evadere verso l’host, accedere alle altre sandbox né leggere file al di fuori del proprio ambiente.
• Riproducibilità - Le sandbox partono da uno stato di template noto. Ogni run comincia con lo stesso ambiente di base, rendendo i risultati deterministici e debuggabili.
• Controllo delle risorse - Configuri CPU, memoria e timeout per ogni sandbox. Se un agente gira troppo a lungo o consuma troppa memoria, la sandbox viene terminata automaticamente.
• Esecuzione parallela - Più sandbox possono girare simultaneamente, ciascuna lavorando su un task diverso. Gli step di workflow, le sessioni di issue e le sandbox autonome operano tutte in modo indipendente.

Architettura

L’architettura delle sandbox in CodeCourier prevede tre livelli:

Infrastruttura E2B

E2B fornisce l’infrastruttura delle macchine virtuali. Quando CodeCourier richiede una sandbox, E2B provisiona una micro-VM a partire da un template (ad esempio, il template claude per le sandbox Claude Code o il template opencode per OpenCode). La VM provisionata include un ambiente Linux di base con Node.js, Python, Git e i comuni strumenti di sviluppo preinstallati.

Orchestrazione Trigger.dev

Le operazioni di sandbox di lunga durata sono gestite dai task in background di Trigger.dev. Quando un workflow run parte, Trigger.dev crea la sandbox E2B, esegue gli script di setup (Git clone, installazione delle dipendenze, iniezione della configurazione), lancia il comando dell’agente IA, streama l’output verso il database e gestisce la pulizia al completamento o in caso di errore.

Database Convex

Ogni sandbox ha un record corrispondente nel database Convex che ne traccia lo stato. Il database memorizza lo status della sandbox (creating, running, paused, killed o error), la sua configurazione (template, timeout, CPU, memoria), le sue relazioni con run e workflow, oltre a metadati come URL di PR, nomi di branch e stato di estrazione dei learning. Poiché Convex è reattivo, l’interfaccia del dashboard si aggiorna in tempo reale quando lo stato della sandbox cambia.

Tipi di sandbox

Le sandbox in CodeCourier vengono create in contesti diversi, ciascuno con caratteristiche di ciclo di vita leggermente differenti:

Sandbox autonome

Create direttamente dalla pagina Sandboxes. Sono ambienti interattivi in cui puoi inviare messaggi all’agente IA, visualizzare l’output del terminale in streaming e gestire manualmente il ciclo di vita della sandbox. Le sandbox autonome sono ideali per task ad hoc, debugging ed esplorazione.

Sandbox di workflow run

Create automaticamente quando un workflow run viene eseguito. Ogni step della pipeline (designer, checker, optimizer) ottiene la propria sandbox. Queste sandbox sono gestite dall’orchestratore di workflow - di solito le monitori tramite la vista di dettaglio del run anziché dalla pagina Sandboxes.

Sandbox di sessione di issue

Create durante le sessioni di issue. Una sandbox di sessione di issue esegue un agente IA che analizza il tuo repository, esplora la codebase e identifica problemi e miglioramenti. Le sandbox di sessione di issue operano indipendentemente dai workflow.

Sandbox di sessione di issue

Create durante le sessioni di analisi di issue. Queste sandbox eseguono un agente IA che revisiona il tuo repository GitHub, identifica issue e miglioramenti e produce card di issue strutturate con prompt suggeriti.

Configurazione della sandbox

Ogni sandbox viene creata con un oggetto di configurazione che ne controlla le risorse e il comportamento:

• Template ID - Quale template E2B usare (ad esempio,claude, opencode, codex, pi). Determina lo strumento CLI preinstallato e l’ambiente di base.
• Timeout - Tempo massimo di esecuzione, da 1 minuto a 4 ore (da 60.000 a 14.400.000 millisecondi). Se la sandbox supera questo timeout, viene terminata automaticamente.
• Memoria - Allocazione di RAM in MB, tra 256 MB e 8.192 MB. Una memoria maggiore serve per codebase grandi e compilazioni pesanti.
• CPU - Numero di CPU, tra 1 e 8. Più CPU aiutano con build paralleli ed esecuzione dei test.
• Modello designer - Il modello IA da usare per gli step designer (ad esempio, claude-opus-4-6, claude-sonnet-4-6).
• Modello checker - Il modello IA da usare per gli step checker (può differire dal modello designer).
• Thinking effort - Impostazioni di thinking effort per modello (ad esempio, high, medium, low).

Relazione con le altre funzionalità

Le sandbox sono collegate a quasi ogni funzionalità di CodeCourier:

• Workflow usano le sandbox per eseguire ogni step.
• Persona definiscono la configurazione dell’agente iniettata nelle sandbox durante i workflow run.
• Sessioni di issue girano all’interno di sandbox dedicate.
• Learning vengono estratti dalla cronologia dei messaggi della sandbox dopo il completamento.
• Pull request vengono create a partire dallo stato della branch della sandbox quando una sandbox termina il lavoro.
• Tracciamento dell’usage registra il costo di ogni sessione di sandbox (compute E2B, uso dei token IA).