Sandboxes verwalten

Sobald eine Sandbox läuft, bietet CodeCourier Werkzeuge, ihren Fortschritt zu beobachten, mit dem KI-Agenten zu interagieren und die Sandbox über ihren gesamten Lebenszyklus zu verwalten. Diese Anleitung behandelt Status-Tracking, Messaging, Beendigung, Cleanup und das Soft-Delete-/Restore-System.

Lebenszyklus-Zustände einer Sandbox

Jede Sandbox in CodeCourier befindet sich in einem von fünf Zuständen. Diese werden im status-Feld des Sandbox-Datensatzes gespeichert und bestimmen die verfügbaren Aktionen.

Creating

Die Sandbox wurde angefordert, aber die E2B-VM wird noch provisioniert. In dieser Phase hat CodeCourier einen Datenbankdatensatz erstellt und wartet darauf, dass E2B eine Sandbox-ID zurückgibt. Eine Interaktion ist noch nicht möglich.

Running

Die Sandbox ist aktiv. Der KI-Agent läuft innerhalb der VM, und Sie können Nachrichten senden, gestreamten Terminal-Output sehen und den Fortschritt überwachen. Der Zähler aktiver Sandboxes für das Projekt wird inkrementiert, wenn eine Sandbox in diesen Zustand eintritt.

Paused

Die Sandbox ist angehalten. Der VM-Zustand bleibt erhalten, aber der Agent läuft nicht aktiv. Pausierte Sandboxes können fortgesetzt werden. Dieser Zustand wird primär für die Pause-/Resume-Funktion von E2B bei lang laufenden Umgebungen verwendet.

Killed

Die Sandbox wurde beendet. Die E2B-VM wurde zerstört, und der gesamte In-Memory-Zustand ist verloren. Dateien, die vor der Beendigung in Git commit-et wurden, bleiben im Remote-Repository erhalten. Eine Sandbox geht in den Killed-Zustand über, wenn Sie sie manuell stoppen, das Timeout abläuft oder ein Workflow-Schritt endet.

Error

Die Sandbox ist auf einen fatalen Fehler gestoßen. Das error-Feld des Sandbox-Datensatzes enthält die Fehlermeldung. Häufige Ursachen sind fehlende API-Keys, E2B-Provisionierungsfehler und nicht behebbare Agentenabstürze.

Sandbox-Aktivität überwachen

Gestreamter Terminal-Output

Wenn Sie eine laufende Sandbox im Dashboard öffnen, sehen Sie eine gestreamte Terminal-Ansicht mit der Ausgabe des KI-Agenten in Echtzeit. Dazu gehören:

• Textantworten des KI-Modells.
• Tool-Nutzungs-Indikatoren (Datei-Edits, Befehlausführung, Suchen).
• Fehlermeldungen und Warnungen.
• Fortschritts-Updates, während der Agent seine Aufgabe abarbeitet.

Der Terminal-Output wird durch die Tabelle sandboxMessagesangetrieben. Jede Nachricht hat eine role (user oder assistant), content und optional ein streamLogmit den rohen Streaming-Daten. Nachrichten tragen außerdem einstatus-Feld (streaming, completedoder error), das angibt, ob die Antwort noch generiert wird.

Sandbox-Detailansicht

Die Sandbox-Detailseite zeigt umfassende Informationen zur Sandbox:

• Status-Badge -- Visuelle Anzeige des aktuellen Lebenszyklus-Zustands.
• Konfiguration -- Template, Modell, Timeout, Speicher und CPU-Einstellungen.
• Metadaten -- Erstellungszeit, verknüpfter Run oder Issue-Sitzung, Trigger-Run-ID.
• Git-Informationen -- Repository-URL, Branch-Name und PR-Status (falls ein Pull Request erstellt wurde).
• Learning-Extraktionsstatus -- Ob Learnings aus der Nachrichtenhistorie der Sandbox extrahiert wurden.

Nachrichten senden

Bei Standalone-Sandboxes (nicht Teil einer Workflow-Ausführung) können Sie Folgenachrichten an den KI-Agenten senden, während er läuft. Das ist der interaktive Modus von CodeCourier -- er funktioniert wie ein Chat-Gespräch, bei dem jede Nachricht zusätzliche Arbeit auslöst.

Wenn Sie eine Nachricht senden:

1. Die Nachricht wird in der Tabelle sandboxMessages mit der Rolle user gespeichert.
2. Ein Trigger.dev-Task leitet die Nachricht an die laufende E2B-Sandbox weiter.
3. Die KI-CLI empfängt die Nachricht und beginnt, eine Antwort zu generieren.
4. Die Antwort streamt zurück und wird als Nachricht mit der Rolle assistant gespeichert.

Hat die Sandbox ihre initiale Aufgabe bereits abgeschlossen und der Agent ist im Leerlauf, nutzt die Folgenachricht das Flag --continueder CLI, um den Konversationskontext fortzusetzen.

Sandboxes stoppen und beenden

Manuelles Beenden

Sie können eine laufende Sandbox jederzeit vom Dashboard aus stoppen. Beim Beenden einer Sandbox:

1. CodeCourier sendet ein Kill-Kommando an den KI-CLI-Prozess in der Sandbox (z. B. pkill -9 -f '[c]laude' für Claude Code).
2. Vor dem Zerstören der VM erkennt CodeCourier ein Git-Repository in der Sandbox und versucht best-effort, nicht commit-ete Änderungen zu pushen.
3. Wird ein Nicht-Default-Branch mit Remote erkannt, wird automatisch ein Pull Request erstellt.
4. Die E2B-Sandbox wird beendet und der Status auf killed aktualisiert.

Automatisches Timeout

Jede Sandbox hat ein konfiguriertes Timeout. Läuft das Timeout ab, zerstört E2B die VM automatisch. CodeCourier erkennt dies und aktualisiert den Sandbox-Status entsprechend. Das Standard-Timeout beträgt 15 Minuten für Standalone-Sandboxes und variiert bei Workflow-Schritten je nach Workflow-Konfiguration.

Pull-Request-Erstellung

Wenn eine Sandbox ihre Arbeit beendet (sei es durch Abschluss oder Beenden), kann CodeCourier automatisch einen GitHub-Pull-Request erstellen. Der PR-Erstellungsfluss:

1. Git-Infos aus der Sandbox erkennen: Remote-URL und aktueller Branch.
2. Überspringen, wenn der Branch main oder masterist (kein PR nötig für Default-Branches).
3. Alle nicht gepushten Commits aus der Sandbox pushen.
4. Einen PR über die GitHub-API mit dem konfigurierten GitHub-Token erstellen.
5. PR-URL, -Nummer und -Status im Sandbox-Datensatz speichern.

Das PR-Status-Feld verfolgt den Lebenszyklus des Pull Requests:creating, created, failed,skipped oder merged.

Learning-Extraktion

Nach Abschluss einer Sandbox kann CodeCourier Learnings aus der Nachrichtenhistorie des Agenten extrahieren. Learnings sind Muster, Präferenzen, Stolperfallen und architektonische Erkenntnisse, die der Agent während der Ausführung entdeckt hat. Sie werden in der Tabellelearnings gespeichert und können zu Learning-Versionen kompiliert werden, die in zukünftige Sandboxes eingespielt werden.

Der Extraktionsstatus wird im Sandbox-Datensatz verfolgt:

• pending -- Extraktion wurde in die Warteschlange gestellt.
• running -- Der Extraktionsagent verarbeitet Nachrichten.
• completed -- Learnings wurden extrahiert und gespeichert.
• skipped -- Extraktion war nicht nötig (z. B. keine Nachrichten).
• error -- Extraktion fehlgeschlagen. Der Fehler steht in learningExtractionError.

Soft-Delete und Restore

Sandboxes unterstützen Soft-Deletion. Beim Löschen einer Sandbox aus dem Dashboard wird der Datensatz nicht physisch aus der Datenbank entfernt. Stattdessen wird ein deletedAt-Zeitstempel gesetzt. Soft-gelöschte Sandboxes:

• Sind in der Standard-Sandbox-Liste ausgeblendet.
• Zählen nicht in den Zählern aktiver Sandboxes.
• Können jederzeit wiederhergestellt werden, was das Feld deletedAt zurücksetzt.
• Können dauerhaft gelöscht werden, was den Datenbankdatensatz physisch entfernt.

Dieses zweistufige Löschmuster schützt vor versehentlichem Datenverlust. Die Projektzähler werden sowohl bei Soft-Delete als auch bei Restore angepasst.

Ressourcen-Management

Aktive Sandbox-Verfolgung

CodeCourier führt einen denormalisierten Zähler aktiver Sandboxes pro Projekt. Dieser Zähler wird inkrementiert, wenn eine Sandbox in denrunning-Zustand wechselt, und dekrementiert, wenn sie ihn verlässt. Der Zähler wird in der Projekt-Dashboard-Übersicht angezeigt.

Nutzungsverfolgung

Jede Sandbox-Sitzung erzeugt Nutzungsdatensätze, die Folgendes verfolgen:

• E2B-Compute -- Sandbox-Laufzeit in Sekunden, abgerechnet durch E2B.
• KI-Token-Nutzung -- Input- und Output-Tokens, die das KI-Modell während der Sitzung verbraucht hat.
• Kostenberechnung -- USD-Gesamtkosten basierend auf den für jeden Dienst konfigurierten Nutzungs-Kostensätzen.

Nutzungsdatensätze sind über das Feld sandboxId mit der Sandbox verknüpft und können im Abrechnungs- und Nutzungsbereich des Projekts eingesehen werden.

// 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