Sandboxes erstellen

Das Erstellen einer Sandbox in CodeCourier provisioniert eine isolierte Cloud-Linux-Umgebung, in der ein KI-Coding-Agent für Sie arbeiten kann. Diese Anleitung beschreibt, wie Sie Sandboxes über die Dashboard-UI starten, welche Konfigurationsoptionen verfügbar sind und wie Sandboxes während Workflow-Ausführungen programmatisch erstellt werden.

Start vom Dashboard

Der primäre Weg zum Erstellen einer Standalone-Sandbox führt über die Sandboxes-Seite in Ihrem Projekt-Dashboard. Der Start-Dialog lässt Sie jeden Aspekt der Sandbox vor der Erstellung konfigurieren.

Konfigurationsoptionen im Detail

Template-Auswahl

Die Template-ID bestimmt das Basis-E2B-Image, das für die Sandbox verwendet wird. Jedes CLI-Tool hat ein eigenes Template mit vorinstalliertem Tool. CodeCourier unterstützt auch benutzerdefinierte E2B-Templates -- haben Sie ein eigenes Template mit zusätzlichen Tools oder Abhängigkeiten gebaut, können Sie dessen ID angeben. Bei einem benutzerdefinierten Template nutzt CodeCourier diebuildCustomTag-Funktion, um das E2B-Tag zu konstruieren.

Denkleistung

Für Claude-Code-Sandboxes können Sie die Denkleistung pro Modell konfigurieren. Sie wird als --effort-Flag an die Claude-CLI übergeben. Optionen sind high, medium,low oder none. Höhere Denkleistung führt zu gründlicherem Reasoning, kostet aber mehr Tokens.

Checker-Template

Workflow-Sandboxes unterstützen eine separate checkerTemplateId, die es dem Checker-Schritt erlaubt, ein anderes E2B-Template zu nutzen als der Designer-Schritt. Ist sie nicht gesetzt, fällt der Checker auf das Haupt-Template zurück.

CLI-spezifische Overrides

Die Sandbox-Konfiguration unterstützt CLI-Tool-Overrides pro Schritt:

• designerCliId -- Überschreibt das CLI-Tool für Designer-Schritte.
• optimizerCliId -- Überschreibt das CLI-Tool für Optimizer-Schritte.
• checkerCliId -- Überschreibt das CLI-Tool für Checker-Schritte.

So kann ein Workflow z. B. Claude Code für Designarbeit und OpenCode für das Checking verwenden.

Sandbox-Setup-Sequenz

Wird eine Sandbox erstellt, durchläuft CodeCourier eine mehrphasige Setup-Sequenz, bevor der KI-Agent startet. Dieses Setup wird von dersetupSandboxForTool-Funktion ausgeführt und besteht aus:

Gemeinsames Setup (alle Tools)

1. Git-Clone -- Ist eine GitHub-Repo-URL konfiguriert, wird das Repo nach /home/user/project geklont. Ein neuer Feature-Branch wird für die Arbeit der Sandbox erstellt.
2. Git-Credential-Helper -- Ist ein GitHub-Token verfügbar, wird ein Credential-Helper konfiguriert, sodass der Agent Commits pushen kann.
3. Umgebungsvariablen -- Projektweite Umgebungsvariablen werden in die Shell-Umgebung der Sandbox eingespielt.
4. System-Prompt -- Der System-Prompt (aus den Projekteinstellungen oder dem Standard) wird in eine Datei geschrieben, die die KI-CLI liest.

Tool-spezifisches Setup

Jedes CLI-Tool hat zusätzliche Setup-Schritte:

• Claude Code -- Schreibt CLAUDE.md in das Projektverzeichnis, spielt Skills und Commands in .claude/skills/ und .claude/commands/ ein, schreibt kompilierte Learnings und richtet den Anthropic-API-Key ein.
• OpenCode -- Schreibt den System-Prompt als Config-Datei im OpenCode-erwarteten Format und richtet den OpenRouter-API-Key ein.
• Codex -- Konfiguriert den OpenAI-API-Key und installiert die Codex-CLI, falls sie im Template nicht enthalten ist.
• Pi -- Richtet den OpenRouter-API-Key ein und schreibt CLAUDE.md (Pi unterstützt das CLAUDE.md-Format).

Programmatische Erstellung

Sandboxes werden auch in mehreren Kontexten programmatisch erstellt:

Workflow-Ausführungen

Bei einer Workflow-Ausführung erstellt der Trigger.dev-Orchestrator Sandboxes für jeden Schritt. Die Sandbox-Konfiguration stammt aus demdefaultConfig des Workflows, potenziell überschrieben durch Persona-Einstellungen pro Schritt. Jeder Schritt erhält eine eigene Sandbox mit passendem CLI-Tool, Modell und Anweisungen.

Work-Chains

Work-Chains führen eine Sequenz von Issues aus, jedes als separate Workflow-Ausführung. Jeder Run erzeugt eigene Sandboxes und nutzt denselben Branch, um Änderungen über Issues hinweg zu sammeln.

Issue-Sitzungen

Issue-Sitzungen erstellen eine einzelne Sandbox, die einen KI-Scanning-Agenten ausführt. Die Sitzungs-Sandbox erkundet das Repository, identifiziert Probleme und Verbesserungen und liefert eine strukturierte Liste von Issues. Die Sandbox ist über das Feld sessionId mit dem Issue-Sitzungs-Datensatz verknüpft.

Issue-Sitzungen

Issue-Analyse-Sitzungen erstellen eine Sandbox, die das Repository nach möglichen Verbesserungen scannt. Die Sandbox ist über das FeldissueSessionId mit der Issue-Sitzung verknüpft.

// Internal flow: how CodeCourier creates a sandbox
const sandboxId = await ctx.runMutation(internal.sandboxes.create, {
  userId: user._id,
  projectId: project._id,
  sandboxId: e2bSandboxId, // from E2B SDK
  status: "running",
  config: {
    templateId: "claude",
    timeoutMs: 900_000,
    memoryMb: 1024,
    cpuCount: 2,
  },
  createdAt: Date.now(),
});