# Runtime e sandbox

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

Canonical page: https://beeuni.ai/docs/it/work/runtime

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](/docs/it/work/sessions).

<a id="sandbox-lifecycle"></a>

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

| Stato | Quando viene impostato |
| --- | --- |
| `provisioning` | Alla creazione della sessione. Beeuni crea il branch della sessione e richiede il sandbox. |
| `running` | Quando il sandbox è attivo e raggiungibile. |
| `stopped` | All'arresto esplicito o durante la procedura di inattività che manda in ibernazione i sandbox inattivi. |
| `failed` | Se il provisioning non riesce. |

`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.

| Stato | Quando viene impostato |
| --- | --- |
| `provisioning` | Il provider avvia il sandbox. |
| `active` | Il provider conferma che il sandbox è attivo. |
| `stopped` | Arresto esplicito, arresto automatico per inattività o riavvio in corso. |
| `error` | Il provider segnala un errore di avvio o di runtime. |
| `archived` | Terminale. Hai eliminato la sessione e il provider ha distrutto il sandbox, senza metterlo in pausa. |

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`.

<a id="branch-model"></a>

### 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](/docs/it/work/change-requests) dopo il merge.

<a id="reconcile-a-session-branch"></a>

### 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`.

<a id="config-convergence"></a>

### Convergenza della configurazione

<a id="where-a-box-gets-the-release"></a>

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.

<a id="workspace-is-where-you-edit-the-base-branch-is-what-runs"></a>

#### `/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.

<a id="when-the-configuration-no-longer-declares-a-sessions-agent"></a>

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

<a id="what-the-session-header-shows"></a>

#### Cosa mostra l'intestazione della sessione

| Stato | Condizione | Intestazione |
| --- | --- | --- |
| Aggiornata | Non obsoleta, nessun fallback | Nulla |
| Aggiornamento disponibile | `stale: true` | Il badge di aggiornamento con **Reload config** |
| Fallback | `fallback_reason` impostato | Un chip rosso: **Config failed to load** |

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**.

<a id="turning-it-off"></a>

#### Disattivazione

<a id="injected-environment"></a>

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

| Variabile | Descrizione |
| --- | --- |
| `BEEUNI_PROJECT_ID` | UUID di questo progetto. |
| `BEEUNI_SESSION_ID` | UUID di questa sessione. È anche il nome del branch. |
| `BEEUNI_BRANCH_NAME` | Stesso valore di `BEEUNI_SESSION_ID`. |
| `BEEUNI_REPO_URL` | URL di clonazione del repository del progetto. |
| `BEEUNI_DEFAULT_BRANCH` | Branch predefinito del progetto. |
| `BEEUNI_BASE_REF` | Ref da cui è stato creato il branch di questa sessione. |
| `BEEUNI_API_URL` | URL di base dell'API della piattaforma (`.../v1`). |
| `BEEUNI_AGENT_NAME` | L'agent con cui è stata creata la sessione. |
| `BEEUNI_MODEL` | Il modello da eseguire, se impostato. `BEEUNI_OPENCODE_MODEL` ha lo stesso valore per i daemon compilati prima che esistesse questo nome. |
| `BEEUNI_LLM_BASE_URL` | URL di base del gateway LLM di Beeuni. Il gateway risolve le credenziali del provider lato server. |
| `BEEUNI_TOKEN` | La credenziale Beeuni associata alla sessione. Vedi sotto. |

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](#pushing-from-a-session) qui sotto. Beeuni rifiuta un secret utente con un nome che inizia con il prefisso `BEEUNI_*`, perché riserva tale prefisso alle variabili della piattaforma.

<a id="session-credential"></a>

## Credenziale della sessione

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

<a id="external-tokens"></a>

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

<a id="in-sandbox-token"></a>

### 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`.

<a id="pushing-from-a-session"></a>

## 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](/docs/it/work/change-requests) unita.

<a id="the-sandbox-image"></a>

## L'immagine della sandbox

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

<a id="declare-a-template"></a>

### Dichiarare un template

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

```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`](/docs/it/project/legacy-toml). Elenco completo dei campi: [riferimento al manifest](/docs/it/project/manifest).

<a id="constraints"></a>

### Vincoli

| Regola | Motivo |
| --- | --- |
| Non impostare `ENTRYPOINT` né `CMD`. | Beeuni sovrascrive entrambi per avviare il daemon. |
| Non usare la porta `8000`. | È riservata al proxy inverso del daemon. Avvia i server di sviluppo su altre porte. |
| Usa `FROM` come base Debian o Ubuntu. | Il livello runtime esegue `apt-get`. Alpine, Fedora e Arch causano il fallimento della build. |
| Non eseguire `apt-get clean` senza `rm -rf /var/lib/apt/lists/*`. | Il livello runtime esegue di nuovo `apt-get update`; una cache danneggiata interrompe la build. |
| Non includere credenziali nell’immagine. | Dichiara il nome in `env:` e imposta il valore come segreto del progetto. Beeuni lo inietta all’avvio della sessione. |

<a id="hardware-spec"></a>

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

```yaml
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.

<a id="docker-in-the-sandbox"></a>

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

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

<a id="ports-and-preview-urls"></a>

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

<a id="snapshot-rebuilds"></a>

### 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](/docs/it/work/change-requests) viene unita.