Runtime e sandbox

Ciclo di vita del sandbox, ambiente iniettato, famiglie di token e immagine da cui si avvia una sessione.

Ogni sessione viene eseguita nel proprio ambiente isolato. Questa pagina è il riferimento per il ciclo di vita del sandbox, l’ambiente che Beeuni inietta all’avvio, le famiglie di token e l’immagine del sandbox. Per il concetto di sessione, vedi Sessions.

Ciclo di vita del sandbox

Una riga di sessione contiene un status. L’enum definisce queued, branching, provisioning, running, stopped, failed, completed, ma Beeuni ne assegna solo 4.

queued, branching e completed esistono nell’enum, ma non vengono usati nel flusso della sessione. Non considerarli stati attivi.

Il sandbox ha un status separato nella propria riga, con un enum distinto.

Beeuni non limita il numero di sessioni eseguite contemporaneamente, né per account né per progetto. Le sessioni in esecuzione addebitano i costi di calcolo; se un account ha esaurito il credito, alla creazione riceve 402.

Modello dei branch

• Il branch della sessione prende il nome dall’ID della sessione (un UUID). BEEUNI_SESSION_ID e BEEUNI_BRANCH_NAME hanno lo stesso valore.
• Al momento della creazione della sessione, Beeuni crea il branch a partire da base_ref, che per impostazione predefinita è il branch predefinito del progetto.
• I trigger creano il branch della sessione allo stesso modo delle sessioni interattive.
• Nesbeeuni operazione scrive direttamente nel branch predefinito. Lo fa solo una richiesta di modifica dopo il merge.

Sincronizzare un branch di sessione

Quando il branch di base è cambiato, usa Ask Agent: Sync Branch & Reload dalla tavolozza dei comandi della sessione. L’agente esamina il branch della sessione, mantiene il lavoro locale, recupera l’ultimo base_ref, risolve i conflitti, esegue i test pertinenti e registra il commit della sincronizzazione. Beeuni non sceglie quale versione mantenere in caso di conflitto e non ripristina l’albero di lavoro.

L’agente termina con beeuni sessions reload "$BEEUNI_SESSION_ID" --project "$BEEUNI_PROJECT_ID" --no-repo --force --yes. È necessario --no-repo perché l’agente ha già sincronizzato il branch. Il ricaricamento sostituisce il runtime di harness standard dopo che la nuova versione è diventata stabile. Termina il turno corrente, quindi invia continue dopo il riavvio del runtime.

L’intestazione della sessione mostra in tempo reale ogni fase del ricaricamento confermata dal server. Un ricaricamento web controlla la sessione, compila la configurazione dell’agente, applica e convalida la sostituzione del runtime, quindi conferma la configurazione attiva. Non aggiorna il repository. La CLI può aggiornare il repository, a meno che non passi --no-repo.

Convergenza della configurazione

Ogni sessione usa la configurazione del suo branch base. Invia lì le modifiche e ricarica la sessione. Gli aggiornamenti attendono la fine del turno attivo. Config Releases non ha harness sperimentaleù un flag separato.

Usa Reload config o beeuni sessions reload <session id>. Se il caricamento fallisce, consulta i dettagli dell’errore e correggi la configurazione del progetto.

/workspace è la copia in cui modifichi; viene eseguita la configurazione del branch base

Una sessione esegue SEMPRE la configurazione corrente del branch base. Non esiste una modalità di configurazione per sessione.

/workspace è la copia di lavoro che puoi modificare. Consulta lì la configurazione e modificala lì: la modifica raggiunge la sessione in esecuzione quando viene inviata al branch base, dopodiché la normale convergenza la applica. Una modifica presente solo in /workspace non cambia il comportamento della sessione e l’agente in esecuzione ne viene informato: le sue istruzioni indicano il commit da cui proviene la configurazione e avvisano che /workspace potrebbe essere indietro.

La copia della release è di sola lettura, quindi una modifica alla copia sbagliata genera un errore di autorizzazione, invece di non fare nulla senza avvisarti.

Quando la configurazione non dichiara harness sperimentaleù l’agente di una sessione

La sessione viene creata con un agente. Se un commit successivo rimuove o rinomina quell’agente, la sessione passa all’agente predefinito del progetto, una sola volta e solo se il proprietario della sessione può usare quell’agente. Beeuni registra il passaggio nel log di controllo e lo comunica nelle istruzioni dell’agente in esecuzione, così la sessione spiega cosa è successo.

Se il proprietario non può usare l’agente predefinito oppure il progetto non ne dichiara uno, la sessione resta senza agente e senza accesso ad alcun agente. La sessione si avvia comunque e spiega il motivo. Dichiara di nuovo l’agente, imposta un agente predefinito per il progetto oppure chiedi a un responsabile del progetto di concederti l’accesso all’agente predefinito.

Cosa mostra l’intestazione della sessione

Se un ricaricamento termina con un fallback, segnala un errore, non un esito positivo.

Reload config

Reload config — e beeuni sessions reload <session id> — esegue due operazioni in un solo passaggio e indica cosa è successo a ciascuna:

1. Porta la sessione in esecuzione agli agenti, alle skill e agli strumenti correnti del branch base.
2. Aggiorna con un fast-forward il checkout /workspace, in modo che i file consultabili corrispondano alla configurazione eseguita dalla sessione.

Il pull del checkout è solo fast-forward, sul branch della sessione, quindi non elimina nulla. Passa --no-repo dalla CLI per saltarlo. Per portare il CODICE di base_ref nel branch della sessione, usa Ask agent to sync.

Disattivazione

Variabili d’ambiente iniettate

Beeuni inietta queste variabili all’avvio. Solo un segreto del progetto configurato esplicitamente per la consegna runtime entra nella sandbox. Le credenziali dei connettori e dei provider di modelli restano sul server Beeuni.

Beeuni non inserisce BEEUNI_WORKSPACE. L’immagine include /workspace e nessun passaggio specifico della sessione lo imposta. Beeuni non inserisce neanche un token Git: il daemon recupera una credenziale di clonazione di breve durata quando serve; vedi Inviare modifiche da una sessione qui sotto. Beeuni rifiuta un secret utente con un nome che inizia con il prefisso BEEUNI_*, perché riserva tale prefisso alle variabili della piattaforma.

Credenziale della sessione

Beeuni dispone di token esterni creati dall’utente e di una credenziale all’interno di ogni sandbox.

Token esterni

Un token di accesso personale (PAT, con prefisso beeuni_pat_) o un account di servizio (con prefisso beeuni_sa_) autentica le chiamate all’API Beeuni, all’SDK e alla CLI effettuate dall’esterno di una sandbox. Consulta Autenticazione per l’ambito del PAT, la configurazione dell’account di servizio e indicazioni su quale scegliere.

Token nella sandbox

BEEUNI_TOKEN viene generato quando Beeuni avvia l’ambiente della sessione. È associato all’utente che l’ha avviata, al progetto, alla sessione e all’autorizzazione dell’agent. Ogni route API applica comunque il proprio controllo delle capacità.

Gli identificatori del prompt iniziale e del registro dei turni non sono variabili d’ambiente. Dopo l’avvio, il daemon li richiede all’API con BEEUNI_TOKEN.

Inviare modifiche da una sessione

Nessun token Git upstream entra nella sandbox. git push origin HEAD invia i commit al branch della sessione. Per integrarli nel branch predefinito occorre una richiesta di modifica unita.

L’immagine della sandbox

Il Dockerfile definisce l’ambiente di base. Beeuni fornisce gli strumenti della sessione e il collegamento alla dashboard.

Dichiarare un template

Fai riferimento al Dockerfile come template con nome sotto sandbox.templates in beeuni.yaml.

sandbox:
  templates:
    - slug: dev
      name: Dev box
      dockerfile: Dockerfile.dev
  default: dev

Imposta esattamente uno tra dockerfile e image in ogni voce. I percorsi dei Dockerfile devono rimanere all’interno del repository. Imposta default sullo slug del template che vuoi usare per le sessioni; omettilo per usare l’immagine predefinita della piattaforma. I progetti meno recenti su beeuni.toml seguono gli stessi campi: consulta la documentazione legacy beeuni.toml. Elenco completo dei campi: riferimento al manifest.

Vincoli

Specifiche hardware

cpu, memory e disk in una voce del template determinano le dimensioni della sandbox. Sono tutti e tre facoltativi; se un campo viene omesso, si usa il valore predefinito della piattaforma: 2 vCPU, 4 GiB di memoria e 20 GiB di disco.

sandbox:
  templates:
    - slug: big
      image: ubuntu:24.04
      cpu: 4
      memory: 8
      disk: 50

cpu accetta da 1 a 32 core, memory da 1 a 128 GiB e disk da 1 a 500 GiB. Beeuni riduce al limite qualsiasi valore che lo superi. Beeuni non supporta le GPU; una chiave gpu nel template genera un avviso, non un errore.

Le specifiche fanno parte dello snapshot del template, non sono impostazioni per singola sessione. Modificarle ricostruisce lo snapshot e le applica alla sessione successiva. La sessione corrente mantiene le specifiche con cui è stata avviata.

Docker nella sandbox

Imposta container_runtime: true in un template per eseguire Docker nelle relative sandbox: reti bridge e definite dall’utente, driver di archiviazione overlayfs ed egress NAT. Gli stack locali come supabase start e docker compose funzionano come su un laptop.

sandbox:
  templates:
    - slug: dev
      dockerfile: .beeuni/Dockerfile.dev
      container_runtime: true

Porte e URL di anteprima

Il daemon è in ascolto sulla porta 8000 e inoltra qualsiasi altra porta usata dall’app nella sandbox. Solo la porta 8000 è esclusa dal proxy.

La dashboard raggiunge una porta della sandbox in due modi:

• Basato su percorso: https://<api-host>/v1/p/<sandbox-id>/<port>/.... È il formato predefinito ed è l’unico che supporta gli upgrade WebSocket.
• Basato su sottodominio: https://p<port>-<sandbox-id>.<api-host>/.... Usa questo formato per le app che richiedono percorsi relativi alla radice o cookie, come un server di sviluppo Next.js o Vite. Al momento questo formato non supporta gli upgrade WebSocket.

Il proxy di anteprima rimuove X-Frame-Options e qualsiasi criterio frame-ancestors. Una sessione può incorporare l’anteprima dell’app in un iframe senza richiedere alcuna configurazione da parte tua.

L’anteprima di una sessione può anche essere condivisa tramite un link pubblico, in modalità di sola visualizzazione o interattiva. I link di condivisione pubblici bloccano le porte 22, 4096, 8000 e la porta statica per la condivisione di file.

Ricostruzioni degli snapshot

Le modifiche all’immagine o alle impostazioni dell’ambiente ricostruiscono l’ambiente per le sessioni successive. Le impostazioni invariate riutilizzano l’immagine esistente. La prima sessione che richiede una ricostruzione mostra “preparing image”; le successive riutilizzano quella build.

Le modifiche al Dockerfile apportate durante una sessione hanno effetto dalla sessione successiva, non da quella corrente. La modifica raggiunge main solo quando la relativa richiesta di modifica viene unita.