Lavorare con i file

Comprendi il file system della sandbox in CodeCourier - layout dei file, file di progetto, integrazione Git e persistenza dei file.

5 min letto

sandboxesfilesfilesystem

Ogni sandbox CodeCourier esegue un file system Linux completo dentro una micro-VM E2B. Questo file system è lo spazio di lavoro in cui gli agenti IA leggono codice, scrivono file, installano pacchetti e costruiscono progetti. Comprendere il layout dei file e come i file persistono tra le sessioni di sandbox è essenziale per lavorare efficacemente con CodeCourier.

Layout del file system

Quando una sandbox parte, ha una struttura di directory Linux standard. Le directory chiave per il lavoro dell’agente IA sono:

Layout standard dei file della sandbox

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

La working directory predefinita è /home/user. Quando nessun repository Git è configurato, l’agente IA lavora direttamente in questa directory. Tutti gli strumenti CLI sono configurati per usarla come percorso di base.

Directory del progetto

Quando un URL di repository GitHub è configurato (dalle impostazioni del progetto o per singola sandbox), il repository viene clonato in /home/user/project. La working directory dell’agente è impostata su questo percorso. Tutte le operazioni Git (creazione di branch, commit, push) avvengono all’interno di questa directory.

Integrazione Git

Git è un cittadino di prima classe nelle sandbox CodeCourier. Quando una sandbox viene creata con un URL di repository GitHub, la sequenza di setup gestisce automaticamente l’intero workflow Git.

Clonazione del repository

Durante il setup della sandbox, CodeCourier clona il repository configurato in /home/user/project. Se è disponibile un personal access token GitHub (dalle chiavi API del progetto), viene usato per l’autenticazione, abilitando l’accesso ai repository privati.

Gestione delle branch

Per i workflow run e le sprint chain, CodeCourier crea automaticamente una branch di feature. Il nome della branch viene tipicamente generato dalla descrizione del task. Per le sandbox autonome, l’agente lavora su qualunque branch sia in checkout dopo la clonazione (di solito main o master), ma l’agente stesso può creare branch come parte del suo lavoro.

Credential helper

Se è disponibile un token GitHub, CodeCourier configura un credential helper Git dentro la sandbox. Questo permette all’agente IA di pushare commit al repository remoto senza che gli vengano richieste credenziali. Il credential helper viene impostato tramite comandi git config durante la fase di setup della sandbox.

Setup delle credenziali Git (semplificato)

# 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"

Identità Git personalizzata

Puoi configurare nome ed email di commit Git personalizzati nelle Impostazioni del progetto. Questi valori sovrascrivono l’identità predefinita dell’agente per tutti i commit effettuati dentro le sandbox di quel progetto.

Commit e push automatici

Quando una sandbox termina il lavoro o viene terminata, CodeCourier esegue un commit e un push di rete di sicurezza. Questo garantisce che eventuali modifiche non commitate fatte dall’agente non vadano perse quando la VM viene distrutta:

Fa lo stage di tutte le modifiche con git add -A.
Verifica se ci sono modifiche in stage con git diff --cached --quiet.
Fa il commit con un messaggio auto-generato se esistono modifiche.
Pusha la branch verso il remote.

È un’operazione best-effort - se fallisce (ad esempio, nessun remote configurato), la terminazione della sandbox procede normalmente.

File di configurazione

Durante il setup della sandbox, CodeCourier scrive diversi file di configurazione nel file system. Questi file controllano il comportamento dell’agente IA.

System prompt

Il system prompt viene scritto in /home/user/.system-prompt.txt (o un percorso simile a seconda dello strumento). Il CLI IA legge questo file all’avvio per impostare le istruzioni a livello di sistema per l’agente. Il system prompt proviene dalle impostazioni del progetto o dal template predefinito.

CLAUDE.md

Per gli strumenti che lo supportano (Claude Code e Pi), un file CLAUDE.md viene scritto nella directory del progetto. Questo file contiene istruzioni specifiche del progetto, standard di codifica e contesto che l’agente usa durante tutta la sessione. Il contenuto proviene dal campo claudeMd delle impostazioni del progetto.

Skill e comandi

Le sandbox Claude Code ricevono skill e comandi iniettati. Vengono scritti nelle directory .claude/skills/ e .claude/commands/ all’interno della cartella del progetto. Ogni skill è una collezione di file (tipicamente un SKILL.md e file di riferimento), e ogni comando è un file markdown con istruzioni.

Vengono iniettati solo gli skill e i comandi abilitati nelle impostazioni del progetto. Questo mantiene la finestra di contesto concentrata sulla conoscenza rilevante.

Script

Anche script definiti dall’utente possono essere iniettati nella sandbox. Gli script vengono scritti nel file system e sono disponibili affinché l’agente li esegua. Questo è utile per script di build personalizzati, runner di test o comandi di deploy.

Learning compilati

Se il progetto ha learning compilati (da sessioni di sandbox precedenti che sono state revisionate e approvate), vengono scritti nella sandbox come file markdown. L’agente può fare riferimento a questi learning per evitare di ripetere errori e per seguire pattern consolidati.

Variabili d’ambiente

Le variabili d’ambiente a livello di progetto vengono iniettate nell’ambiente della sandbox durante il setup. Sono disponibili per l’agente IA e per qualsiasi processo che avvia. Le variabili d’ambiente vengono configurate nelle Impostazioni del progetto e possono essere contrassegnate come segrete (mostrate mascherate nell’interfaccia).

Oltre alle variabili configurate dall’utente, CodeCourier inietta diverse variabili di sistema:

Chiavi API di provider - Le chiavi API per il provider dello strumento CLI configurato (ad esempio, ANTHROPIC_API_KEY, OPENROUTER_API_KEY).
Token GitHub - Come GITHUB_TOKEN per le operazioni Git.
Chiavi Convex - Chiavi di deploy e dev per i progetti Convex (se configurate).
Credenziali di test - Email e password dell’utente di test per il testing E2E (se configurate).

Gestione dei segreti

Le chiavi API e i segreti vengono recuperati lato server tramite query Convex interne e iniettati direttamente nell’ambiente della sandbox. Non vengono mai esposti all’interfaccia lato client né memorizzati nell’oggetto di configurazione della sandbox. Le chiavi cifrate nel database vengono decifrate solo al momento della creazione della sandbox.

Persistenza dei file

I file system delle sandbox sono effimeri. Quando una sandbox viene terminata o il suo timeout scade, la macchina virtuale E2B viene distrutta e tutti i file vengono persi. Esistono due meccanismi per preservare il lavoro:

Git push

Il meccanismo di persistenza principale è Git. Il codice commitato e pushato al repository remoto sopravvive alla terminazione della sandbox. È per questo che CodeCourier esegue un commit e un push di rete di sicurezza quando le sandbox terminano - garantisce che il lavoro dell’agente non vada perso.

Artefatti di pull request

Quando una pull request viene creata dal lavoro della sandbox, funge da registro durevole di ciò che l’agente ha prodotto. La PR include tutte le modifiche commitate e può essere revisionata, mergiata o scartata tramite i workflow GitHub standard.

Nessun download di file integrato

CodeCourier attualmente non fornisce un meccanismo di download per file di sandbox arbitrari. Se devi preservare file che non sono in un repository Git, assicurati che l’agente li commiti o ne mostri il contenuto nel terminale prima che la sandbox termini.

Installazione delle dipendenze

Gli agenti IA installano comunemente dipendenze come parte del loro lavoro. I template di sandbox sono forniti con Node.js e npm preinstallati, e la sequenza di setup può eseguire l’installazione dei pacchetti automaticamente. CodeCourier include un’utility npmInstallWithRetry che gestisce i fallimenti transitori del registro npm riprovando il comando di installazione.

Le dipendenze installate durante una sessione di sandbox sono locali a quella sandbox. Non persistono tra le sessioni a meno che non vengano commitate nel repository (ad esempio, aggiornando package.json e package-lock.json).