E2B Sandboxes

E2B (kurz für "Environment to Bot") ist der Cloud- Sandbox-Anbieter, der die gesamte Codeausführung in CodeCourier antreibt. Jedes Mal, wenn ein KI-Coding-Agent eine Aufgabe ausführt -- ob über eine eigenständige Sandbox, einen Workflow-Run oder eine Issue-Discovery-Session -- geschieht das in einer E2B-Micro-VM. Diese Seite erklärt, was E2B bietet, wie CodeCourier damit integriert, die Konfigurationsoptionen und die Behebung häufiger Probleme.

Was E2B bietet

E2B bietet On-Demand isolierte virtuelle Cloud-Maschinen, die speziell für KI-Agent-Workloads konzipiert sind. Anders als Container sind E2B-Sandboxes vollwertige Micro-VMs mit eigenem Linux-Kernel und bieten dadurch stärkere Isolationsgarantien. Wichtige Fähigkeiten:

• Vollständige Linux-Umgebung -- Jede Sandbox führt ein vollständiges Linux-System mit Dateisystem, Netzwerk-Stack und Prozessausführung aus.
• Template-basierte Provisionierung -- Sandboxes werden aus vorgefertigten Templates erstellt, die gängige Entwicklungs-Tools (Node.js, Python, Git usw.) enthalten. Benutzerdefinierte Templates lassen sich mit zusätzlichen Tools und Konfigurationen bauen.
• Sub-Sekunden-Start -- E2B-Micro-VMs starten in unter einer Sekunde und sind dadurch für On-Demand-Nutzung praktikabel.
• Pausieren und Fortsetzen -- Sandboxes lassen sich pausieren, um Ressourcen zu sparen, und mit vollständigem Zustand wieder fortsetzen.
• Automatische Bereinigung -- Sandboxes haben konfigurierbare Timeouts und werden bei Ablauf automatisch zerstört, was Ressourcenlecks verhindert.
• Netzwerkzugang -- Sandboxes haben Zugriff auf das Internet, um Pakete zu installieren, Repositories zu klonen und mit APIs zu kommunizieren.

Wie CodeCourier E2B nutzt

Sandbox-Provisionierung

Wenn eine Sandbox erstellt wird (entweder durch einen Benutzer aus dem Dashboard oder durch einen Trigger.dev-Task während eines Workflow-Runs), ruft CodeCourier das E2B SDK auf, um eine neue Micro-VM bereitzustellen. Der Provisionierungsprozess umfasst diese Schritte:

1. Template-Auswahl. Das System wählt anhand der CLI-Tool-Konfiguration ein Sandbox-Template aus. Es können benutzerdefinierte Templates angegeben werden, andernfalls wird das Standard-Template für das gewählte CLI-Tool verwendet (z. B. ein claude-Template für Claude-Code-Sandboxes).
2. Umgebungskonfiguration. Umgebungsvariablen werden in die Sandbox injiziert, einschließlich API-Keys (Anthropic, OpenRouter, OpenAI, GitHub), Projekteinstellungen, System-Prompts und Skill-Dateien.
3. VM-Erstellung. Die Methode Sandbox.create() des E2B SDK wird mit Template-Namen und Konfigurationsoptionen, einschließlich Timeout-Dauer, aufgerufen.
4. Agent-Initialisierung. Nachdem die VM läuft, wird das CLI-Tool darin gestartet und der initiale Prompt (falls vorhanden) an den Agent gesendet.

Lebenszyklus-Verwaltung

CodeCourier verfolgt den Sandbox-Zustand entlang des folgenden Lebenszyklus:

• "creating" -- E2B provisioniert die VM. Der Convex-Datensatz existiert, die VM ist aber noch nicht bereit.
• "running" -- Die VM ist aktiv und der KI-Agent läuft.
• "paused" -- Die VM wurde pausiert, um Ressourcen zu sparen. Sie kann fortgesetzt werden.
• "killed" -- Die VM wurde beendet. Dies ist der Endzustand für erfolgreich abgeschlossene Sandboxes.
• "error" -- Während der Provisionierung oder Ausführung trat ein Fehler auf.

Kommunikationsmuster

CodeCourier kommuniziert mit E2B-Sandboxes über ein Prozess- Ausführungsmodell. Der Trigger.dev-Task in der Orchestrierungs- schicht verwendet das E2B SDK, um Befehle innerhalb der Sandbox auszuführen, Ausgabe-Streams zu lesen und das Dateisystem zu verwalten. Nachrichten zwischen Benutzer und KI-Agent fließen über Convex (gespeichert in der Tabelle sandboxMessages) und werden vom Trigger.dev-Task an die Sandbox weitergeleitet.

Einrichtung des E2B API Keys

Um E2B-Sandboxes zu nutzen, benötigen Sie einen E2B-API-Key. Dieser Key wird von jedem Benutzer oder Projekt bereitgestellt, nicht auf Serverebene.

E2B API Key erhalten

1. Erstellen Sie ein Konto auf e2b.dev.
2. Navigieren Sie im E2B-Dashboard zum Bereich API-Keys.
3. Erstellen Sie einen neuen API-Key.
4. Fügen Sie den Key in CodeCourier in den Projekteinstellungen oder Benutzer-Präferenzen im E2B-Provider-Bereich hinzu.

Speicherung des Keys

E2B-API-Keys werden vor der Speicherung in der Convex-Datenbank verschlüsselt. Nur die letzten vier Zeichen werden im Klartext zur Anzeige gespeichert (z. B. ****abcd). Keys lassen sich auf zwei Ebenen setzen:

• Benutzerebene -- Gespeichert in der Tabelle apiKeys. Gilt für alle Projekte, sofern nicht überschrieben.
• Projektebene -- Gespeichert in der Tabelle projectProviderKeys. Hat Vorrang vor Keys auf Benutzerebene.

Konfigurationsoptionen

Beim Erstellen einer Sandbox stehen folgende E2B-bezogene Konfigurationsoptionen über das Sandbox-Config-Objekt zur Verfügung:

• Template -- Das für die Sandbox zu verwendende E2B-Template. Templates definieren das Basis-System-Image, die vorinstallierten Tools und die Standardkonfiguration.
• Timeout -- Wie lange die Sandbox aktiv bleibt, bevor sie automatisch beendet wird. Angabe in Sekunden.
• CLI-Tool -- Welche KI-Coding-CLI in der Sandbox ausgeführt werden soll (Claude Code, OpenCode, Codex usw.). Dies bestimmt das ausgewählte Template, sofern kein benutzer- definiertes Template angegeben wird.
• Umgebungsvariablen -- Benutzerdefinierte Umgebungsvariablen, die beim Erstellen in die Sandbox injiziert werden. Diese können projektspezifische Einstellungen, Deploy Keys und Test-Anmeldedaten umfassen.

Benutzerdefinierte Templates

CodeCourier unterstützt benutzerdefinierte E2B-Templates für spezialisierte Workloads. Benutzerdefinierte Templates sind sinnvoll, wenn Sie benötigen:

• Zusätzliche System-Pakete über das Standard-Template hinaus
• Vorinstallierte Frameworks oder Sprach-Runtimes
• Benutzerdefinierte Systemkonfigurationen oder Dotfiles
• Spezifische CLI-Tool-Versionen

Template-Builds werden in der Tabelle templateBuilds verfolgt, die Tool-ID, Template-Name, CLI-Version, Build-Status und etwaige Fehler erfasst. Das Dashboard zeigt den Build-Fortschritt und erlaubt die Auswahl erfolgreicher Templates beim Erstellen von Sandboxes.

Kostenüberlegungen

E2B berechnet auf Basis der Sandbox-Laufzeit. Jede laufende Sandbox verbraucht Ressourcen, unabhängig davon, ob der KI-Agent aktiv arbeitet. So optimieren Sie die Kosten:

• Setzen Sie angemessene Timeouts, damit vergessene Sandboxes nicht endlos laufen.
• Nutzen Sie die Aktion "Alle Sandboxes beenden", um aufzuräumen, wenn Sie fertig sind.
• Überwachen Sie die Sandbox-Laufzeit im Nutzungs-Dashboard (siehe Nutzungs-Tracking).
• Bei iterativen Workflows wiederverwendet das Designer-Checker- Muster dieselbe Sandbox über mehrere Iterationen, anstatt jedes Mal neue zu erstellen.

Fehlerbehebung

Sandbox kann nicht erstellt werden

• Prüfen Sie Ihren E2B-API-Key. Stellen Sie sicher, dass er gültig und nicht abgelaufen ist. Erzeugen Sie gegebenenfalls einen neuen Key im E2B-Dashboard.
• Verfügbarkeit des Templates prüfen. Wenn Sie ein benutzerdefiniertes Template nutzen, stellen Sie sicher, dass es erfolgreich gebaut wurde.
• E2B-Servicestatus prüfen. Besuchen Sie die E2B-Statusseite, um zu bestätigen, dass der Dienst verfügbar ist.

Sandbox läuft vorzeitig ab

• Erhöhen Sie das Timeout in Ihrer Sandbox- oder Workflow- Konfiguration. Der Standardwert kann für komplexe Aufgaben zu kurz sein.

Agent kann nicht auf das Internet zugreifen

• E2B-Sandboxes haben standardmäßig Internetzugang. Wenn die Paketinstallation fehlschlägt, prüfen Sie, ob die Paket- Registry erreichbar ist und ob die DNS-Auflösung innerhalb der Sandbox funktioniert.

API-Key-Fehler innerhalb der Sandbox

• Stellen Sie sicher, dass die erforderlichen Provider-Keys (Anthropic, GitHub usw.) in Ihren Projekteinstellungen konfiguriert sind. Fehlende Keys führen zum Fehlschlag der KI-Coding-CLI beim Start.
• Prüfen Sie, ob projektspezifische Keys für das richtige Projekt gesetzt sind. Keys auf Benutzerebene greifen möglicherweise nicht, wenn ein (auch ungültiger) Key auf Projektebene existiert.