Runtime et environnement sandbox

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

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.

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.

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.

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.

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 fusionnée le fait.

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.

Convergence de la configuration

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.

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

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.

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

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.

Désactivation

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.

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 ci-dessous. Beeuni rejette tout secret utilisateur dont le nom commence par le préfixe BEEUNI_*, réservé aux variables de la plateforme.

Identifiant de session

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

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.

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.

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.

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.

Déclarer un modèle

Référencez votre Dockerfile comme modèle nommé sous sandbox.templates dans beeuni.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. Liste complète des champs : référence du manifeste.

Contraintes

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.

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

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.

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

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.

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 fusionnée.