Gestire le sandbox

Gestisci il ciclo di vita delle sandbox in CodeCourier - monitora lo status, invia messaggi, termina le sessioni e gestisci la pulizia.

7 min letto
sandboxesmanagelifecycle

Una volta che una sandbox è in esecuzione, CodeCourier fornisce strumenti per monitorarne l’avanzamento, interagire con l’agente IA e gestire la sandbox per tutto il suo ciclo di vita. Questa guida copre il tracciamento dello status, la messaggistica, la terminazione, la pulizia e il sistema di soft-delete/ripristino.

Stati del ciclo di vita della sandbox

Ogni sandbox in CodeCourier si trova in uno di cinque stati. Sono memorizzati nel campo status del record della sandbox e determinano quali azioni sono disponibili.

Creating

La sandbox è stata richiesta ma la macchina virtuale E2B è ancora in fase di provisioning. Durante questa fase, CodeCourier ha creato un record nel database e attende che E2B restituisca un ID di sandbox. Nessuna interazione è ancora possibile.

Running

La sandbox è attiva. L’agente IA è in esecuzione dentro la VM e puoi inviare messaggi, visualizzare l’output del terminale in streaming e monitorare l’avanzamento. Il contatore delle sandbox attive del progetto viene incrementato quando una sandbox entra in questo stato.

Paused

La sandbox è stata sospesa. Lo stato della VM è preservato ma l’agente non è attivamente in esecuzione. Le sandbox in pausa possono essere riprese. Questo stato è usato principalmente dalla funzionalità pausa/ripresa di E2B per gli ambienti di lunga durata.

Killed

La sandbox è stata terminata. La VM E2B è stata distrutta e tutto lo stato in memoria è perso. I file commitati su Git prima della terminazione sono preservati nel repository remoto. Una sandbox passa a killed quando la fermi manualmente, quando il timeout scade o quando uno step di workflow si completa.

Error

La sandbox ha incontrato un errore fatale. Il campo error del record della sandbox contiene il messaggio di errore. Le cause comuni includono chiavi API mancanti, fallimenti di provisioning E2B e crash irrecuperabili dell’agente.

Transizioni di stato

Il dashboard mostra aggiornamenti di status in tempo reale alimentati da query reattive Convex. Quando una sandbox passa da uno stato all’altro, l’interfaccia si aggiorna automaticamente. Il contatore delle sandbox attive nella panoramica del tuo progetto riflette il numero di sandbox nello stato « running ».

Monitorare l’attività della sandbox

Output del terminale in streaming

Quando apri una sandbox in esecuzione nel dashboard, vedi una vista di terminale in streaming che mostra l’output dell’agente IA in tempo reale. Questo include:

  • Le risposte testuali del modello IA.
  • Gli indicatori di uso degli strumenti (modifiche di file, esecuzione di comandi, ricerche).
  • I messaggi di errore e gli avvisi.
  • Gli aggiornamenti di avanzamento man mano che l’agente procede nel task.

L’output del terminale è alimentato dalla tabella sandboxMessages. Ogni messaggio ha un role(user o assistant), un content e un streamLog opzionale per i dati grezzi di streaming. I messaggi portano anche un campo status (streaming, completed o error) per indicare se la risposta è ancora in fase di generazione.

Vista di dettaglio della sandbox

La pagina di dettaglio della sandbox mostra informazioni complete sulla sandbox:

  • Badge di status - Indicatore visivo dello stato attuale del ciclo di vita.
  • Configurazione - Impostazioni di template, modello, timeout, memoria e CPU.
  • Metadati - Ora di creazione, run o sessione di issue collegata, trigger run ID.
  • Informazioni Git - URL del repository, nome della branch e status della PR (se è stata creata una pull request).
  • Status di estrazione dei learning - Se i learning sono stati estratti dalla cronologia dei messaggi della sandbox.

Inviare messaggi

Per le sandbox autonome (non parte di un workflow run), puoi inviare messaggi di follow-up all’agente IA mentre è in esecuzione. È la modalità interattiva di CodeCourier - funziona come una conversazione di chat in cui ogni messaggio innesca ulteriore lavoro da parte dell’agente.

Quando invii un messaggio:

  1. Il messaggio viene memorizzato nella tabella sandboxMessages con role user.
  2. Un task Trigger.dev inoltra il messaggio alla sandbox E2B in esecuzione.
  3. Il CLI IA riceve il messaggio e inizia a generare una risposta.
  4. La risposta viene restituita in streaming e memorizzata come messaggio con role assistant.

Se la sandbox ha già completato il suo task iniziale e l’agente è inattivo, il messaggio di follow-up usa il flag --continue del CLI per riprendere il contesto della conversazione.

Sandbox di workflow

Non puoi inviare messaggi interattivi alle sandbox che fanno parte di un workflow run. Le sandbox di workflow sono gestite dall’orchestratore e ricevono i loro prompt dalla configurazione dello step della pipeline.

Fermare e terminare le sandbox

Terminazione manuale

Puoi fermare una sandbox in esecuzione in qualsiasi momento dal dashboard. Quando termini una sandbox:

  1. CodeCourier invia un comando di terminazione al processo CLI IA dentro la sandbox (ad esempio, pkill -9 -f '[c]laude' per Claude Code).
  2. Prima di distruggere la VM, CodeCourier rileva qualsiasi repository Git nella sandbox e tenta un push best-effort delle modifiche non commitate.
  3. Se viene rilevata una branch non predefinita con un remote, una pull request viene creata automaticamente.
  4. La sandbox E2B viene terminata e lo status viene aggiornato a killed.

Timeout automatico

Ogni sandbox ha un timeout configurato. Quando il timeout scade, E2B distrugge automaticamente la VM. CodeCourier lo rileva e aggiorna lo status della sandbox di conseguenza. Il timeout predefinito è di 15 minuti per le sandbox autonome e varia per gli step di workflow in base alla configurazione del workflow.

Creazione di pull request

Quando una sandbox termina il lavoro (completando il task o venendo terminata), CodeCourier può creare automaticamente una pull request GitHub. Il flusso di creazione della PR:

  1. Rileva le info Git dalla sandbox: URL del remote e branch attuale.
  2. Salta se la branch è main o master (nessuna PR necessaria per le branch predefinite).
  3. Pusha eventuali commit non pushati dalla sandbox.
  4. Crea una PR tramite l’API GitHub usando il token GitHub configurato.
  5. Memorizza URL, numero e status della PR sul record della sandbox.

Il campo di status della PR traccia il ciclo di vita della pull request:creating, created, failed,skipped o merged.

Estrazione dei learning

Dopo che una sandbox si completa, CodeCourier può estrarre learning dalla cronologia dei messaggi dell’agente. I learning sono pattern, preferenze, insidie e insight architetturali che l’agente ha scoperto durante l’esecuzione. Vengono memorizzati nella tabella learnings e possono essere compilati in versioni di learning che vengono iniettate nelle sandbox future.

Lo status di estrazione è tracciato sul record della sandbox:

  • pending - L’estrazione è stata messa in coda.
  • running - L’agente di estrazione sta elaborando i messaggi.
  • completed - I learning sono stati estratti e memorizzati.
  • skipped - L’estrazione non era necessaria (ad esempio, nessun messaggio).
  • error - L’estrazione è fallita. L’errore è in learningExtractionError.

Soft-delete e ripristino

Le sandbox supportano la soft-delete. Quando elimini una sandbox dal dashboard, il record non viene rimosso fisicamente dal database. Invece, viene impostato un timestamp deletedAt. Le sandbox in soft-delete:

  • Sono nascoste dalla lista predefinita delle sandbox.
  • Non contano nei contatori delle sandbox attive.
  • Possono essere ripristinate in qualsiasi momento, azzerando il campo deletedAt.
  • Possono essere eliminate definitivamente, rimuovendo fisicamente il record.

Questo pattern di eliminazione in due fasi protegge dalla perdita accidentale di dati. I contatori del progetto vengono aggiustati durante le operazioni sia di soft-delete che di ripristino.

Gestione delle risorse

Tracciamento delle sandbox attive

CodeCourier mantiene un contatore denormalizzato delle sandbox attive per progetto. Questo contatore viene incrementato quando una sandbox entra nello stato running e decrementato quando lo lascia. Il contatore è mostrato nella panoramica del dashboard del progetto.

Tracciamento dell’usage

Ogni sessione di sandbox genera record di usage che tracciano:

  • Compute E2B - Il runtime della sandbox in secondi, fatturato da E2B.
  • Uso dei token IA - I token di input e output consumati dal modello IA durante la sessione.
  • Calcolo del costo - Il costo totale in USD basato sulle tariffe di costo dell’usage configurate per ogni servizio.

I record di usage sono collegati alla sandbox tramite il campo sandboxId e possono essere visualizzati nella sezione di fatturazione e usage del progetto.

Aggiornamento dello status della sandbox (interno)
// How CodeCourier tracks sandbox state transitions
await ctx.runMutation(internal.sandboxes.updateStatus, {
  id: sandboxId,
  status: "killed",
});
// Active counter is automatically decremented
// when transitioning from "running" to any other state