# Runtime et environnement sandbox

Cycle de vie du sandbox, environnement injecté, familles de jetons et image utilisée au démarrage d’une session.

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

Chaque session s’exécute dans son propre sandbox isolé. Cette page est la référence pour le cycle de vie du sandbox, l’environnement que Beeuni injecte au démarrage, les familles de jetons et l’image du sandbox elle-même. Pour comprendre le concept de session, consultez [Sessions](/docs/fr/work/sessions).

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

## Cycle de vie du sandbox

Une ligne de session contient un `status`. L’énumération définit `queued`, `branching`, `provisioning`, `running`, `stopped`, `failed`, `completed`, mais Beeuni n’en utilise que 4.

| Statut | Défini lorsque |
| --- | --- |
| `provisioning` | À la création de la session. Beeuni crée la branche de session et demande le sandbox. |
| `running` | Une fois le sandbox démarré et accessible. |
| `stopped` | Lors d’un arrêt explicite, ou par le nettoyage périodique qui met en veille les sandbox inactifs. |
| `failed` | En cas d’échec du provisionnement. |

`queued`, `branching` et `completed` existent dans l’énumération, mais ne sont jamais utilisés dans le flux de session. Ne les considérez pas comme des états actifs.

Le sandbox possède un `status` distinct dans sa propre ligne, avec sa propre énumération.

| Statut | Défini lorsque |
| --- | --- |
| `provisioning` | Le fournisseur démarre le sandbox. |
| `active` | Le fournisseur confirme que le sandbox est actif. |
| `stopped` | Lors d’un arrêt explicite, d’un arrêt automatique pour inactivité ou d’un redémarrage en cours. |
| `error` | Le fournisseur signale un échec au démarrage ou à l’exécution. |
| `archived` | État terminal. Vous avez supprimé la session et le fournisseur a détruit le sandbox, sans le mettre en pause. |

Beeuni ne limite pas le nombre de sessions exécutées simultanément, par compte ou par projet. Les sessions en cours facturent des ressources de calcul ; un compte à court de crédits reçoit `402` lors de la création.

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

### Modèle de branche

- La branche de session porte le nom de l’ID de session (un UUID). `BEEUNI_SESSION_ID` et `BEEUNI_BRANCH_NAME` ont la même valeur.
- Beeuni crée la branche à partir de `base_ref`, qui correspond par défaut à la branche par défaut du projet, au moment de la création de la session.
- Les déclencheurs créent leur branche de session de la même manière qu’une session interactive.
- Rien n’écrit directement dans la branche par défaut. Seule une [demande de fusion](/docs/fr/work/change-requests) fusionnée le fait.

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

### Réconcilier une branche de session

Utilisez **Ask Agent: Sync Branch & Reload** dans la palette de commandes de la session lorsque la branche de base a changé. L’agent inspecte la branche de session, préserve le travail local, récupère la dernière version de `base_ref`, résout les conflits, exécute les tests pertinents et valide la réconciliation. Beeuni ne choisit pas un côté du conflit et ne réinitialise pas l’arborescence de travail.

L’agent termine avec `beeuni sessions reload "$BEEUNI_SESSION_ID" --project "$BEEUNI_PROJECT_ID" --no-repo --force --yes`. `--no-repo` est nécessaire, car l’agent a déjà réconcilié la branche. Le rechargement remplace l’environnement d’exécution harness standard une fois que le remplacement est opérationnel. Il met fin au tour en cours ; envoyez donc `continue` une fois l’environnement d’exécution rétabli.

L’en-tête de session affiche en temps réel chaque phase de rechargement confirmée par le serveur. Un rechargement Web vérifie la session, compile la configuration de l’agent, applique et valide le remplacement de l’environnement d’exécution, puis confirme la configuration active. Il n’actualise pas le dépôt. La CLI peut actualiser le dépôt, sauf si vous passez `--no-repo`.

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

### Convergence de la configuration

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

Chaque session utilise la configuration de sa branche de base. Poussez les changements vers cette branche, puis rechargez la session. Les mises à jour attendent la fin du tour actif. Config Releases n’a plus de drapeau distinct.

Utilisez **Reload config** ou `beeuni sessions reload <session id>`. En cas d’échec, consultez les détails de l’erreur et corrigez la configuration du projet.

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

#### `/workspace` est l’endroit où vous modifiez la configuration ; la branche de base est celle qui est exécutée

Une session exécute TOUJOURS la configuration actuelle de la branche de base. Il n’existe pas de mode de configuration par session.

`/workspace` est votre copie de travail modifiable. Consultez la configuration à cet endroit et modifiez-la à cet endroit — la modification est appliquée à la session en cours dès qu’elle est **poussée vers la branche de base**, puis la convergence habituelle la récupère. Une modification présente uniquement dans `/workspace` ne change pas le comportement de la session, et l’agent en cours en est informé : ses instructions indiquent le commit d’où provient sa configuration et précisent que `/workspace` peut être en retard.

La copie de la version est en lecture seule ; une modification apportée à la mauvaise copie échoue donc avec une erreur d’autorisation au lieu de ne rien faire silencieusement.

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

#### Lorsque la configuration ne déclare plus l’agent d’une session

Une session est créée avec un agent. Si un commit ultérieur supprime ou renomme cet agent, la session passe à l’agent par défaut du projet — une seule fois, et uniquement si le propriétaire de la session peut utiliser cet agent. Beeuni consigne ce changement dans le journal d’audit et l’indique dans les instructions de l’agent en cours, afin que la session explique ce qui s’est passé.

Si le propriétaire ne peut pas utiliser l’agent par défaut, ou si le projet ne déclare aucun agent par défaut, la session n’a plus d’agent ni d’accès à un agent. Elle démarre quand même et explique la raison. Déclarez à nouveau l’agent, définissez un agent par défaut pour le projet ou demandez à un gestionnaire de projet de vous donner accès à l’agent par défaut.

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

#### Ce que montre l’en-tête de la session

| État | Condition | En-tête |
| --- | --- | --- |
| À jour | Pas obsolète, aucun repli | Rien |
| Mise à jour disponible | `stale: true` | Le badge de mise à jour, avec **Reload config** |
| Repli | `fallback_reason` défini | Une pastille rouge : **Config failed to load** |

Un rechargement qui aboutit à un repli signale une erreur, pas une réussite.

#### Reload config

**Reload config** — et `beeuni sessions reload <session id>` — effectue deux opérations en une seule étape et indique ce qui s’est passé pour chacune :

1. La session en cours passe aux agents, compétences et outils actuels de la branche de base.
2. La copie de travail `/workspace` avance par fast-forward, de sorte que les fichiers que vous consultez à cet endroit correspondent à la configuration exécutée par la session.

La récupération de la copie de travail se fait uniquement par fast-forward, sur la branche propre à la session ; elle ne supprime donc rien. Transmettez `--no-repo` sur la CLI pour l’ignorer. Pour intégrer le CODE de `base_ref` à la branche de session, utilisez **Ask agent to sync**.

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

#### Désactivation

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

## Variables d’environnement injectées

Beeuni injecte ces variables au démarrage. Seul un secret de projet explicitement configuré pour la livraison `runtime` entre dans le bac à sable. Les identifiants des connecteurs et des fournisseurs de modèles restent sur le serveur Beeuni.

| Variable | Description |
| --- | --- |
| `BEEUNI_PROJECT_ID` | UUID de ce projet. |
| `BEEUNI_SESSION_ID` | UUID de cette session. Également le nom de la branche. |
| `BEEUNI_BRANCH_NAME` | Même valeur que `BEEUNI_SESSION_ID`. |
| `BEEUNI_REPO_URL` | URL de clonage du dépôt du projet. |
| `BEEUNI_DEFAULT_BRANCH` | Branche par défaut du projet. |
| `BEEUNI_BASE_REF` | Référence à partir de laquelle cette session a créé sa branche. |
| `BEEUNI_API_URL` | URL de base de l’API de la plateforme (`.../v1`). |
| `BEEUNI_AGENT_NAME` | Agent avec lequel la session a été créée. |
| `BEEUNI_MODEL` | Modèle à exécuter, le cas échéant. `BEEUNI_OPENCODE_MODEL` contient la même valeur pour les daemons créés avant l’apparition de ce nom. |
| `BEEUNI_LLM_BASE_URL` | URL de base de la passerelle LLM Beeuni. La passerelle résout les identifiants des fournisseurs côté serveur. |
| `BEEUNI_TOKEN` | Identifiant Beeuni associé à la session. Voir ci-dessous. |

Beeuni n’injecte pas `BEEUNI_WORKSPACE`. L’image intègre `/workspace` et aucune étape propre à la session ne le définit. Beeuni n’injecte pas non plus de jeton Git : le daemon récupère un identifiant de clonage à courte durée de vie lorsqu’il en a besoin ; voir [Envoyer des modifications depuis une session](#pushing-from-a-session) ci-dessous. Beeuni rejette tout secret utilisateur dont le nom commence par le préfixe `BEEUNI_*`, réservé aux variables de la plateforme.

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

## Identifiant de session

Beeuni propose des jetons externes que vous créez vous-même et un identifiant dans chaque bac à sable.

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

### Jetons externes

Un jeton d’accès personnel (PAT, préfixé par `beeuni_pat_`) ou un compte de service (préfixé par `beeuni_sa_`) authentifie les appels à l’API Beeuni, au SDK et à l’interface de ligne de commande depuis l’extérieur d’un bac à sable. Consultez la section Authentification pour connaître la portée des PAT, la configuration des comptes de service et savoir lequel choisir.

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

### Jeton dans le bac à sable

`BEEUNI_TOKEN` est généré au démarrage de l’environnement de session par Beeuni. Il est associé à l’utilisateur qui lance la session, au projet, à la session et aux autorisations de l’agent. Chaque route d’API applique néanmoins son propre contrôle de capacité.

Les identifiants de la requête initiale et du registre des tours ne sont pas des variables d’environnement. Après le démarrage, le daemon les récupère auprès de l’API avec `BEEUNI_TOKEN`.

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

## Envoyer des modifications depuis une session

Aucun jeton Git en amont n’entre dans le bac à sable. `git push origin HEAD` envoie les commits vers la branche de la session. Pour intégrer des modifications à la branche par défaut, il faut fusionner une [demande de modification](/docs/fr/work/change-requests).

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

## Image du bac à sable

Votre Dockerfile définit l’environnement de base. Beeuni fournit les outils de session et la connexion au tableau de bord.

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

### Déclarer un modèle

Référencez votre Dockerfile comme modèle nommé sous `sandbox.templates` dans `beeuni.yaml`.

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

Définissez exactement l’un de `dockerfile` ou `image` pour chaque entrée. Les chemins des Dockerfiles doivent rester dans le dépôt. Définissez `default` sur le slug du modèle à utiliser pour vos sessions ; omettez-le pour utiliser l’image par défaut de la plateforme. Les anciens projets sur `beeuni.toml` utilisent les mêmes champs — consultez [l’ancien `beeuni.toml`](/docs/fr/project/legacy-toml). Liste complète des champs : [référence du manifeste](/docs/fr/project/manifest).

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

### Contraintes

| Règle | Pourquoi |
| --- | --- |
| Ne définissez pas `ENTRYPOINT` ni `CMD`. | Beeuni remplace les deux pour démarrer le daemon. |
| Ne réservez pas le port `8000`. | Il est réservé au proxy inverse du daemon. Utilisez d’autres ports pour les serveurs de développement. |
| `FROM` une base Debian ou Ubuntu. | La couche d’exécution lance `apt-get`. Alpine, Fedora et Arch entraînent un échec de la compilation. |
| Ne lancez pas `apt-get clean` sans `rm -rf /var/lib/apt/lists/*`. | La couche d’exécution relance `apt-get update` ; un cache défectueux fait échouer la compilation. |
| N’intégrez pas d’identifiants dans l’image. | Déclarez le nom dans `env:` et définissez la valeur comme secret du projet. Beeuni l’injecte au démarrage de la session. |

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

### Caractéristiques matérielles

`cpu`, `memory` et `disk` dans une entrée de modèle définissent la taille du bac à sable. Ces trois champs sont facultatifs ; un champ omis utilise les valeurs par défaut de la plateforme : 2 vCPU, 4 Gio de mémoire, 20 Gio de disque.

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

`cpu` accepte de 1 à 32 cœurs, `memory` de 1 à 128 Gio et `disk` de 1 à 500 Gio. Beeuni ramène toute valeur qui dépasse ces limites à la limite correspondante. Beeuni ne prend pas en charge les GPU ; la présence d’une clé `gpu` dans un modèle génère un avertissement, pas une erreur.

Les caractéristiques font partie de l’instantané du modèle, et non d’un paramètre par session. Leur modification reconstruit l’instantané et s’applique à la session suivante. La session en cours conserve les caractéristiques avec lesquelles elle a démarré.

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

### Docker dans le bac à sable

Définissez `container_runtime: true` sur un modèle pour exécuter Docker dans ses bacs à sable : réseaux bridge et définis par l’utilisateur, pilote de stockage `overlayfs` et sortie NAT. Les piles locales telles que `supabase start` et `docker compose` fonctionnent comme sur un ordinateur portable.

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

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

### Ports et URL d’aperçu

Le daemon écoute sur le port `8000` et sert de proxy pour tout autre port utilisé par votre application dans le bac à sable. Seul le port `8000` lui-même est bloqué par le proxy.

Le tableau de bord accède à un port du bac à sable de deux façons :

- **Par chemin** : `https://<api-host>/v1/p/<sandbox-id>/<port>/...`. C’est le format par défaut et le seul qui prend en charge les mises à niveau WebSocket.
- **Par sous-domaine** : `https://p<port>-<sandbox-id>.<api-host>/...`. Utilisez ce format pour les applications qui nécessitent des chemins relatifs à la racine ou des cookies, comme un serveur de développement Next.js ou Vite. Les mises à niveau WebSocket ne fonctionnent pas encore avec ce format.

Le proxy d’aperçu supprime `X-Frame-Options` ainsi que toute politique `frame-ancestors`. Une session peut intégrer l’aperçu de votre application dans une iframe sans configuration de votre côté.

L’aperçu d’une session peut aussi être partagé via un lien public, en mode consultation seule ou interactif. Les liens de partage publics bloquent les ports `22`, `4096`, `8000` ainsi que le port de partage de fichiers statiques.

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

### Reconstructions des instantanés

Les modifications de l’image ou des paramètres de l’environnement reconstruisent celui-ci pour les sessions suivantes. Les paramètres inchangés réutilisent l’image existante. La première session qui nécessite une reconstruction affiche « préparation de l’image » ; les sessions suivantes réutilisent cette compilation.

La modification du Dockerfile dans une session ne prend effet que lors de la session suivante, pas dans celle en cours. La modification n’atteint `main` qu’une fois sa [demande de modification](/docs/fr/work/change-requests) fusionnée.