Sandbox E2B

E2B (abbreviazione di « Environment to Bot ») è il provider di sandbox cloud che alimenta tutta l’esecuzione di codice in CodeCourier. Ogni volta che un agente di coding IA esegue un task -- che sia tramite una sandbox autonoma, un run di workflow o una sessione di issue discovery -- lo fa all’interno di una micro-VM E2B. Questa pagina spiega cosa offre E2B, come CodeCourier si integra con esso, le opzioni di configurazione e la risoluzione dei problemi comuni.

Cosa offre E2B

E2B offre macchine virtuali cloud isolate on-demand, progettate specificamente per i carichi di lavoro degli agenti IA. A differenza dei container, le sandbox E2B sono micro-VM complete con un proprio kernel Linux, che offrono garanzie di isolamento più forti. Le capacità principali includono:

• Ambiente Linux completo -- Ogni sandbox esegue un sistema Linux completo con file system, stack di rete e capacità di esecuzione dei processi.
• Provisioning basato su template -- Le sandbox vengono create da template predefiniti che includono strumenti di sviluppo comuni (Node.js, Python, Git, ecc.). È possibile creare template personalizzati con strumenti e configurazioni aggiuntivi.
• Avvio in meno di un secondo -- Le micro-VM E2B si avviano in meno di un secondo, rendendole pratiche per l’uso on-demand.
• Pausa e ripresa -- Le sandbox possono essere messe in pausa per risparmiare risorse e riprese in seguito con il loro stato completo intatto.
• Pulizia automatica -- Le sandbox hanno timeout configurabili e vengono distrutte automaticamente alla scadenza, evitando fughe di risorse.
• Accesso alla rete -- Le sandbox possono accedere a Internet per installare pacchetti, clonare repository e comunicare con le API.

Come CodeCourier usa E2B

Provisioning delle sandbox

Quando viene creata una sandbox (da un utente dalla dashboard oppure da un task Trigger.dev durante un run di workflow), CodeCourier chiama l’SDK E2B per fornire una nuova micro-VM. Il processo di provisioning segue questi passaggi:

1. Selezione del template. Il sistema seleziona un template di sandbox in base alla configurazione dello strumento CLI. È possibile specificare template personalizzati, oppure viene usato il template predefinito per lo strumento CLI scelto (ad esempio, un template claude per le sandbox Claude Code).
2. Configurazione dell’ambiente. Le variabili d’ambiente vengono iniettate nella sandbox, incluse le chiavi API (Anthropic, OpenRouter, OpenAI, GitHub), le impostazioni del progetto, i prompt di sistema e i file di skill.
3. Creazione della VM. Il metodo Sandbox.create() dell’SDK E2B viene chiamato con il nome del template e le opzioni di configurazione, inclusa la durata del timeout.
4. Inizializzazione dell’agente. Dopo che la VM è in esecuzione, lo strumento CLI viene avviato al suo interno e il prompt iniziale (se presente) viene inviato all’agente.

Gestione del ciclo di vita

CodeCourier traccia lo stato della sandbox lungo il seguente ciclo di vita:

• "creating" -- E2B sta fornendo la VM. Il record Convex esiste ma la VM non è ancora pronta.
• "running" -- La VM è attiva e l’agente IA è in esecuzione.
• "paused" -- La VM è stata messa in pausa per risparmiare risorse. Può essere ripresa.
• "killed" -- La VM è stata terminata. È lo stato finale per le sandbox completate con successo.
• "error" -- Si è verificato un errore durante il provisioning o l’esecuzione.

Modello di comunicazione

CodeCourier comunica con le sandbox E2B tramite un modello di esecuzione dei processi. Il task Trigger.dev in esecuzione nel livello di orchestrazione usa l’SDK E2B per eseguire comandi all’interno della sandbox, leggere i flussi di output e gestire il file system della sandbox. I messaggi tra l’utente e l’agente IA transitano tramite Convex (memorizzati nella tabella sandboxMessages) e vengono inoltrati alla sandbox dal task Trigger.dev.

Configurazione della chiave API E2B

Per usare le sandbox E2B, hai bisogno di una chiave API E2B. Questa chiave viene fornita da ogni utente o progetto, non a livello server.

Ottenere una chiave API E2B

1. Crea un account su e2b.dev.
2. Vai alla sezione Chiavi API nella tua dashboard E2B.
3. Genera una nuova chiave API.
4. In CodeCourier, vai nelle impostazioni del tuo progetto o nelle preferenze utente e aggiungi la chiave nella sezione del provider E2B.

Archiviazione della chiave

Le chiavi API E2B vengono criptate prima della memorizzazione nel database Convex. Solo gli ultimi quattro caratteri vengono memorizzati in chiaro a scopo di visualizzazione (ad esempio, ****abcd). Le chiavi possono essere impostate a due livelli:

• Livello utente -- Memorizzata nella tabella apiKeys. Si applica a tutti i progetti a meno che non venga sovrascritta.
• Livello progetto -- Memorizzata nella tabella projectProviderKeys. Ha la precedenza sulle chiavi a livello utente.

Opzioni di configurazione

Quando si crea una sandbox, le seguenti opzioni di configurazione relative a E2B sono disponibili tramite l’oggetto di configurazione della sandbox:

• Template -- Il template E2B da usare per la sandbox. I template definiscono l’immagine di sistema di base, gli strumenti preinstallati e la configurazione predefinita.
• Timeout -- Per quanto tempo la sandbox resta attiva prima di essere terminata automaticamente. Misurato in secondi.
• Strumento CLI -- Quale CLI di coding IA eseguire all’interno della sandbox (Claude Code, OpenCode, Codex, ecc.). Questo determina quale template viene selezionato se non è specificato un template personalizzato.
• Variabili d’ambiente -- Variabili d’ambiente personalizzate iniettate nella sandbox al momento della creazione. Possono includere impostazioni specifiche del progetto, chiavi di deploy e credenziali di test.

Template personalizzati

CodeCourier supporta i template E2B personalizzati per carichi di lavoro specializzati. I template personalizzati sono utili quando hai bisogno di:

• Pacchetti di sistema aggiuntivi oltre al template predefinito
• Framework o runtime di linguaggio preinstallati
• Configurazioni di sistema personalizzate o dotfile
• Versioni specifiche dello strumento CLI

I build dei template vengono tracciati nella tabella templateBuilds, che registra l’ID dello strumento, il nome del template, la versione CLI, lo stato del build ed eventuali errori. La dashboard mostra l’avanzamento del build e consente di selezionare i template riusciti durante la creazione delle sandbox.

Considerazioni sui costi

E2B addebita in base al tempo di attività della sandbox. Ogni sandbox in esecuzione consuma risorse, indipendentemente dal fatto che l’agente IA sia attivamente in esecuzione. Per ottimizzare i costi:

• Imposta timeout appropriati per evitare che le sandbox dimenticate girino all’infinito.
• Usa l’azione « Termina tutte le sandbox » per fare pulizia quando hai finito di lavorare.
• Monitora il tempo di esecuzione delle sandbox nella dashboard di utilizzo (vedi Monitoraggio dell’utilizzo).
• Per i workflow iterativi, il pattern designer-checker riutilizza la stessa sandbox attraverso le iterazioni invece di crearne di nuove.

Risoluzione dei problemi

La sandbox non viene creata

• Controlla la tua chiave API E2B. Assicurati che sia valida e non scaduta. Prova a generare una nuova chiave nella dashboard E2B.
• Verifica la disponibilità del template. Se usi un template personalizzato, assicurati che sia stato costruito con successo.
• Controlla lo stato del servizio E2B. Visita la pagina di stato di E2B per confermare che il servizio sia operativo.

La sandbox scade prematuramente

• Aumenta l’impostazione del timeout nella configurazione della tua sandbox o del workflow. Il valore predefinito potrebbe essere troppo breve per task complessi.

L’agente non riesce ad accedere a Internet

• Le sandbox E2B hanno accesso a Internet per impostazione predefinita. Se l’installazione dei pacchetti fallisce, verifica che il registro dei pacchetti sia raggiungibile e che la risoluzione DNS funzioni all’interno della sandbox.

Errori della chiave API all’interno della sandbox

• Assicurati che le chiavi di provider richieste (Anthropic, GitHub, ecc.) siano configurate nelle impostazioni del tuo progetto. Le chiavi mancanti causeranno il fallimento della CLI di coding IA all’avvio.
• Verifica che le chiavi a livello progetto siano impostate per il progetto corretto. Le chiavi a livello utente potrebbero non applicarsi se esiste una chiave a livello progetto (anche se non valida).