Arbeiten mit Dateien

Jede CodeCourier-Sandbox betreibt ein vollwertiges Linux-Dateisystem innerhalb einer E2B-Mikro-VM. Dieses Dateisystem ist der Arbeitsbereich, in dem KI-Agenten Code lesen, Dateien schreiben, Pakete installieren und Projekte bauen. Das Dateilayout und die Persistenz über Sandbox-Sitzungen hinweg zu verstehen, ist essenziell, um effektiv mit CodeCourier zu arbeiten.

Dateisystem-Layout

Beim Start einer Sandbox liegt eine Standard-Linux-Verzeichnisstruktur vor. Die wichtigsten Verzeichnisse für die Arbeit der KI-Agenten sind:

/home/user/                    # Home directory (agent working dir)
  project/                     # Cloned Git repository (if configured)
    .claude/                   # Claude Code configuration
      skills/                  # Injected skill files
      commands/                # Injected command files
    CLAUDE.md                  # Project instructions for Claude Code
    .system-prompt.txt         # System prompt file
    package.json               # Project package manifest
    ...                        # All other project files
  .env                         # Environment variables (if configured)
/tmp/                          # Temporary files
/usr/local/                    # Globally installed tools (Node.js, Python, etc.)

Home-Verzeichnis

Das Standard-Arbeitsverzeichnis ist /home/user. Ist kein Git-Repository konfiguriert, arbeitet der KI-Agent direkt in diesem Verzeichnis. Alle CLI-Tools sind so konfiguriert, dass sie dies als Basispfad verwenden.

Projektverzeichnis

Ist eine GitHub-Repository-URL konfiguriert (aus den Projekteinstellungen oder pro Sandbox), wird das Repository nach /home/user/project geklont. Das Arbeitsverzeichnis des Agenten wird auf diesen Pfad gesetzt. Alle Git-Operationen (Branch-Erstellung, Commits, Pushes) finden in diesem Verzeichnis statt.

Git-Integration

Git ist in CodeCourier-Sandboxes ein First-Class-Citizen. Wird eine Sandbox mit einer GitHub-Repository-URL erstellt, übernimmt die Setup-Sequenz den gesamten Git-Workflow automatisch.

Repository-Klonen

Während des Sandbox-Setups klont CodeCourier das konfigurierte Repository nach /home/user/project. Ist ein GitHub-Personal-Access-Token verfügbar (aus den API-Keys des Projekts), wird er zur Authentifizierung verwendet, sodass auch private Repositories zugänglich sind.

Branch-Management

Für Workflow-Ausführungen und Sprint-Chains erstellt CodeCourier automatisch einen Feature-Branch. Der Branch-Name wird typischerweise aus der Aufgabenbeschreibung generiert. Bei Standalone-Sandboxes arbeitet der Agent auf dem nach dem Klonen ausgecheckten Branch (üblicherweise main oder master); der Agent kann jedoch im Zuge seiner Arbeit eigene Branches anlegen.

Credential-Helper

Ist ein GitHub-Token verfügbar, konfiguriert CodeCourier einen Git-Credential-Helper in der Sandbox. So kann der KI-Agent Commits an das Remote-Repository pushen, ohne nach Credentials gefragt zu werden. Der Credential-Helper wird mit git config-Kommandos während der Sandbox-Setup-Phase eingerichtet.

# CodeCourier configures this automatically
git config --global credential.helper store
echo "https://oauth2:${GITHUB_TOKEN}@github.com" > ~/.git-credentials

# Git user identity for commits
git config --global user.name "CodeCourier Agent"
git config --global user.email "agent@codecourier.dev"

Automatischer Commit und Push

Wenn eine Sandbox ihre Arbeit beendet oder beendet wird, führt CodeCourier einen Sicherheits-Commit und -Push aus. So gehen nicht-commit-ete Änderungen des Agenten beim Zerstören der VM nicht verloren:

1. Alle Änderungen mit git add -A stagen.
2. Prüfen, ob gestagte Änderungen existieren via git diff --cached --quiet.
3. Mit automatisch generierter Nachricht commit-en, falls Änderungen vorliegen.
4. Den Branch zum Remote pushen.

Das ist eine Best-Effort-Operation -- schlägt sie fehl (z. B. kein Remote konfiguriert), läuft die Sandbox-Beendigung normal weiter.

Konfigurationsdateien

Während des Sandbox-Setups schreibt CodeCourier mehrere Konfigurationsdateien in das Dateisystem. Diese Dateien steuern das Verhalten des KI-Agenten.

System-Prompt

Der System-Prompt wird in /home/user/.system-prompt.txtgeschrieben (oder einen ähnlichen Pfad je nach Tool). Die KI-CLI liest diese Datei beim Start, um die System-Anweisungen für den Agenten zu setzen. Der System-Prompt stammt aus den Projekteinstellungen oder dem Standard-Template.

CLAUDE.md

Für Tools mit Unterstützung (Claude Code und Pi) wird eineCLAUDE.md-Datei ins Projektverzeichnis geschrieben. Sie enthält projektspezifische Anweisungen, Coding-Standards und Kontext, den der Agent während seiner Sitzung nutzt. Der Inhalt stammt aus dem Feld claudeMd der Projekteinstellungen.

Skills und Commands

Claude-Code-Sandboxes erhalten eingespielte Skills und Commands. Sie werden in die Verzeichnisse .claude/skills/ und .claude/commands/ innerhalb des Projektordners geschrieben. Jeder Skill ist eine Sammlung von Dateien (typischerweise eineSKILL.md plus Referenzdateien), und jeder Command ist eine Markdown-Datei mit Anweisungen.

Nur die in den Projekteinstellungen aktivierten Skills und Commands werden eingespielt. So bleibt das Kontextfenster auf relevantes Wissen fokussiert.

Scripts

Benutzerdefinierte Scripts können ebenfalls in die Sandbox eingespielt werden. Scripts werden ins Dateisystem geschrieben und stehen dem Agenten zur Ausführung bereit. Das ist nützlich für eigene Build-Skripte, Test-Runner oder Deployment-Kommandos.

Kompilierte Learnings

Hat das Projekt kompilierte Learnings (aus früheren Sandbox-Sitzungen, die geprüft und genehmigt wurden), werden sie als Markdown-Datei in die Sandbox geschrieben. Der Agent kann darauf verweisen, um Fehler nicht zu wiederholen und etablierten Mustern zu folgen.

Umgebungsvariablen

Projektweite Umgebungsvariablen werden während des Setups in die Sandbox-Umgebung eingespielt. Sie stehen dem KI-Agenten und allen von ihm gestarteten Prozessen zur Verfügung. Umgebungsvariablen werden in den Projekteinstellungen konfiguriert und können als geheim markiert werden (in der UI maskiert dargestellt).

Zusätzlich zu nutzer-konfigurierten Variablen spielt CodeCourier mehrere Systemvariablen ein:

• Provider-API-Keys -- Die API-Keys für den konfigurierten CLI-Tool-Provider (z. B. ANTHROPIC_API_KEY,OPENROUTER_API_KEY).
• GitHub-Token -- Als GITHUB_TOKEN für Git-Operationen.
• Convex-Keys -- Deploy- und Dev-Keys für Convex-Projekte (falls konfiguriert).
• Test-Credentials -- Test-Nutzer-E-Mail und Passwort für E2E-Tests (falls konfiguriert).

Dateipersistenz

Sandbox-Dateisysteme sind ephemer. Wenn eine Sandbox beendet wird oder ihr Timeout abläuft, wird die E2B-VM zerstört, und alle Dateien gehen verloren. Es gibt zwei Mechanismen, um Arbeit zu bewahren:

Git-Push

Der primäre Persistenzmechanismus ist Git. Code, der ins Remote-Repository commit-et und gepusht wurde, überlebt die Sandbox-Beendigung. Deshalb führt CodeCourier beim Beenden einer Sandbox einen Sicherheits-Commit und -Push aus -- um sicherzustellen, dass die Arbeit des Agenten nicht verloren geht.

Pull-Request-Artefakte

Wird aus der Sandbox-Arbeit ein Pull Request erstellt, dient er als dauerhafter Nachweis dessen, was der Agent produziert hat. Der PR enthält alle commit-eten Änderungen und kann über Standard-GitHub- Workflows reviewt, gemergt oder verworfen werden.

Abhängigkeits-Installation

KI-Agenten installieren häufig Abhängigkeiten als Teil ihrer Arbeit. Die Sandbox-Templates bringen Node.js und npm vorinstalliert mit, und die Setup-Sequenz kann die Paketinstallation automatisch ausführen. CodeCourier enthält eine npmInstallWithRetry-Utility, die vorübergehende npm-Registry-Fehler durch Wiederholungen behandelt.

Während einer Sandbox-Sitzung installierte Abhängigkeiten sind lokal in dieser Sandbox. Sie überdauern Sitzungen nicht, sofern sie nicht ins Repository commit-et werden (z. B. durch Aktualisieren vonpackage.json und package-lock.json).