Référence des variables d'environnement

Cette référence indique les variables de déploiement, leurs valeurs par défaut et les processus concernés. Le fichier .env du projet est une source possible ; l’environnement des conteneurs et un gestionnaire de secrets peuvent aussi fournir les valeurs. Le fichier d’exemple contient la configuration correspondante.

Après une modification, recrée les services concernés avec ta procédure de déploiement. docker compose restart conserve l’environnement existant. Les fichiers de configuration d’organisation ont un cycle distinct.

Comment lire cette page

Les tableaux indiquent le nom, la valeur par défaut et le rôle de chaque variable. Les valeurs requises doivent atteindre le service concerné ; certaines sont générées par le déploiement. Les variables facultatives peuvent rester absentes. Une valeur par défaut peut venir de Compose plutôt que du processus lui-même.

Consulte aussi les commentaires du fichier d’exemple et vérifie l’environnement effectif du service lorsqu’une valeur manque.

Identité de domaine (obligatoire au premier boot)

SITE_URL désigne l’origine publique canonique. Protocole, hôte et port doivent correspondre à l’adresse du navigateur et aux callbacks enregistrés. BASE_PATH ajoute le préfixe de chemin ; le proxy normalise une barre oblique finale. Les adresses supplémentaires sont des origines sans chemin dans ADDITIONAL_SITE_URLS. Une origine supplémentaire invalide empêche le backend de démarrer.

La documentation utilise sa propre origine. Sur l’origine de la plateforme, /docs ouvre la référence API interactive et /openapi.json fournit son schéma. DOCS_URL change l’hôte de documentation du proxy ; cette variable n’installe pas le service docs et ne réécrit pas les liens des clients déjà compilés. TALE_DOCS_URL dans les outils de compilation SEO et le préfixe DOCS_BASE_URL du service docs, utilisé à la compilation comme à l’exécution, sont des réglages distincts.

Une modification de TOTP_CLIENT_NAME ou de TOTP_ENVIRONMENT s’applique aux nouveaux codes QR et URI de configuration, y compris lorsqu’un secret existant est affiché à nouveau, ainsi qu’aux codes de secours téléchargés ensuite. Elle ne change ni les secrets ni les noms des entrées déjà enregistrées sur ton appareil ; tu peux renommer ces entrées dans ton application d’authentification.

TLS

selfsigned crée un certificat Caddy local. Fais confiance à sa CA uniquement pour ta propre installation contrôlée. letsencrypt exige un domaine public et les ports 80/443 accessibles. Avec external, Caddy sert HTTP derrière un proxy TLS.

Secrets de sécurité (obligatoire)

Remplace les valeurs livrées dans .env.example avant d'exposer l'instance — ce sont des espaces réservés volontairement non sûrs.

Base de données

Tale utilise tale_app pour les données applicatives et tale_knowledge pour les fragments, embeddings et pages web. Le déploiement standard conserve les deux dans le service Postgres db, avec l’alias knowledge-db. Tu peux configurer des connexions externes séparément.

L’URL générée est postgresql://tale:${DB_PASSWORD}@db:5432/tale_app ; APP_DB_NAME change le nom de base. Le corpus utilise les schémas private_knowledge et public_web. Une organisation peut choisir ses propres connexions sous Paramètres > Résidence des données. Enregistrer une autre URL ne migre aucune donnée. Consulte Résidence des données.

Deux points à connaître avant de diriger l’une des deux bases vers ta propre infrastructure :

• Le corpus de connaissances exige pgvector déjà installé. Tale crée lui-même ses schémas et ses tables sur une base vide, mais n’installe jamais d’extension — la table des chunks porte une colonne vector, donc CREATE EXTENSION vector; doit avoir été lancé sur la base cible. Le pg_search de ParadeDB reste optionnel : sans lui la recherche retombe sur le vectoriel seul au lieu d’échouer. La base opérationnelle, elle, n’a besoin d’aucune extension.
• Utilise une connexion Postgres directe ou compatible avec les sessions. Notifications de tâches, verrous de migration et requêtes préparées dépendent de ces propriétés. Vérifie tout proxy de connexion géré selon ces exigences.

Store d'objets

Les fichiers et médias utilisent un stockage compatible S3. Ces variables règlent la connexion par défaut. Une connexion propre à l’organisation est prioritaire ; une panne du stockage par défaut ne signifie pas que les buckets de toutes les organisations sont inaccessibles.

Le proxy fourni expose la route des objets au navigateur sans publier le port d’administration du stockage. Un stockage externe peut utiliser son propre endpoint public.

Comment ces variables arrivent dans le déploiement en cours

Au démarrage, le backend rapproche default/object-storage/connection.json de son environnement. Recrée backend-api et backend-worker avec les nouvelles valeurs. Les messages de démarrage distinguent les résultats suivants :

Si tu préfères gérer le store à la main, mets "managedBy": "operator" dans connection.json : le backend ne touchera plus jamais ce fichier. Un fichier sans managedBy du tout — écrit avant ce comportement — n’est repris que s’il nomme encore le même bucket sur le même endpoint que l’environnement ; si tu l’avais repointé à la main, ta modification reste.

Droits sur le bucket : le backend vérifie l’existence du bucket avec HeadBucket et ne le crée que s’il est absent. Une clé qui peut lire, écrire et supprimer des objets sans pouvoir créer de bucket suffit donc, à condition que tu crées le bucket toi-même. Les téléversements et téléchargements présignés passent par le navigateur : un bucket externe a donc aussi besoin d’une politique CORS autorisant l’origine de ton déploiement en GET, PUT et HEAD — voir Résidence des données.

Confidentialité du journal d'audit

Un pepper pseudonymise les données personnelles enregistrées lors des connexions échouées. Les versions précédentes généraient aussi TALE_AUDIT_SIGNING_KEY et TALE_AUDIT_SIGNING_KEY_PREVIOUS. Plus rien ne les lit : tu peux conserver ou supprimer une valeur existante.

Voir Intégrité du journal d'audit pour le modèle de vérification.

Observabilité

Définir METRICS_BEARER_TOKEN expose les endpoints de métriques derrière le token : /metrics/platform, /metrics/backend (les métriques du backend applicatif) et /metrics/sla-rules. Voir Configuration d'observabilité pour la configuration de scrape.

Chiffrement des secrets de fournisseur

SOPS protège les fichiers de secrets de configuration compatibles. Les identifiants actuels des fournisseurs en base utilisent ENCRYPTION_SECRET_HEX, décrit avec les secrets de sécurité plus haut.

Sans clé age, le module SOPS écrit les fichiers compatibles en clair avec les permissions 0600. Les fichiers déjà chiffrés exigent toujours leur clé. Lis Secrets avec SOPS avant de modifier ces variables.

Les identifiants de fournisseurs peuvent référencer une variable préfixée par TALE_PROVIDER_KEY_ (40 caractères maximum). Les courtiers d’abonnement utilisent le préfixe distinct TALE_TOKEN_SOURCE_ (60 maximum). Ces champs contiennent des noms de variables, pas les secrets. Injecte les valeurs dans les processus backend et recrée les conteneurs concernés après modification. Fournisseurs décrit ce fonctionnement.

Applications OAuth des connectors

Les connectors OAuth (Gmail, Google Drive, Outlook, Teams, Slack, …) résolvent leur application fournisseur d’abord par organisation : une app configurée sous Paramètres > Connectors > Apps OAuth gagne pour cette organisation. L’environnement fournit la valeur par défaut du déploiement en dessous (et reste la seule source pour Slack, dont la vérification de signature des événements s’exécute avant qu’aucune organisation ne soit connue). Pour chaque slug de connector :

Enregistre ${SITE_URL}${BASE_PATH}/api/connectors/oauth2/callback sur l’application fournisseur, et pour Slack aussi ${SITE_URL}${BASE_PATH}/api/connectors/slack/events comme Events Request URL. Détails : Connectors (développement).

Import cloud Knowledge (Documents)

Les autorisations OneDrive / Google Drive par utilisateur pour Connaissances → Documents sont distinctes des connectors d’organisation et de la connexion. Ici aussi, une app d’organisation configurée sous Paramètres > Connectors > Apps OAuth prime — l’entrée google-drive est partagée avec la voie connector, et OneDrive / SharePoint (import de connaissances) a sa propre entrée ; les chaînes ci-dessous s’appliquent partout où l’organisation n’en a pas configuré. Enregistre cette URI de redirection sur l’app Microsoft (ou Google) :

${SITE_URL}${BASE_PATH}/api/cloud-import/oauth2/callback

Résolution des identifiants pour OneDrive (premier match gagne) :

Les inscriptions d’app Entra mono-tenant exigent une URL d’autorisation propre au tenant — /common échoue avec AADSTS50194. Définis l’ID de tenant (ou organizations / common pour une app multi-tenant). S’il est absent, Tale reprend le tenant de l’issuer SSO Entra de l’organisation s’il est configuré.

L’écran de consentement Microsoft demande Graph Files.Read et Sites.Read.All (liste/téléchargement OneDrive et SharePoint), User.Read (libellé du compte) et offline_access (jeton de rafraîchissement pour la sync). Cette autorisation est intentionnelle et par utilisateur — elle n’est pas attachée à la connexion à Tale.

Google Drive utilise uniquement une app dédiée (pas de repli sur l’app de connexion) :

Enregistre la même URI de callback cloud-import sur le client OAuth Google. Le consentement demande drive.readonly et userinfo.email.

Drapeaux de fonctionnalité

Ces variables règlent l’authentification backend, les événements de fichiers et les droits opérateur. Recrée les rôles backend concernés après un changement d’environnement. Modifier seulement le conteneur web ne suffit pas.

L’autorisation des cibles privées concerne deux contrôles : l’enregistrement des sites et les requêtes du crawler, ainsi que la validation de l’imageUrl d’un produit. Sans elle, une cible de site privée renvoie 400 WEBSITE_DOMAIN_NOT_CRAWLABLE ; une URL d’image privée renvoie 400 INVALID_BODY. Pour un produit, seule la chaîne du nom d’hôte est contrôlée, sans télécharger l’image ni résoudre le DNS. L’enregistrement d’un site et le crawler vérifient aussi les adresses résolues. Active cette variable uniquement si le déploiement a besoin de ces destinations privées. Elle est distincte de l’autorisation des fournisseurs privés.

Topologie du déploiement

Ces valeurs façonnent les rôles applicatifs d’un déploiement de workspace : le nombre de réplicas, que tale deploy lit dans l’environnement du projet et ramène dans la plage autorisée avec un avertissement, et la quantité de travail qu’un réplica de worker prend en charge à la fois.

Un déploiement de workspace fait temporairement tourner les deux couleurs. Prévois cette capacité supplémentaire. Augmente le rôle qui limite le débit selon tes mesures ; davantage de réplicas consomment aussi plus de connexions et de mémoire. Consulte Mises à jour.

Sessions

Laisse-le non défini pour conserver la durée de session par défaut. Si défini, une session inactive expire côté serveur une fois la fenêtre écoulée, tandis qu'une session active continue de glisser à chaque requête. Les Administrateurs d'organisation peuvent raccourcir la fenêtre effective par organisation — jamais l'allonger au-delà de ce plafond — via la politique de gouvernance du délai d'inactivité de session ; les sessions inactives sous cette politique sont révoquées par une passe qui tourne environ toutes les cinq minutes.

Lien vers le support

Indique ici ton propre service d’assistance pour que les personnes confrontées à une erreur joignent l’équipe qui exploite ton déploiement. Quand l’écran d’erreur connaît l’organisation, le lien ajoute organizationId=<id> à la chaîne de requête, après les paramètres que l’URL contient déjà, et remplace un paramètre organizationId qu’elle porte déjà. Toute autre valeur, par exemple mailto: ou une URL sans schéma, est ignorée avec un avertissement dans le journal du service platform, et le lien garde sa valeur par défaut.

Point d’accès MCP

Les agents de code lancés dans un terminal et les clients côté serveur n’envoient pas d’Origin : la vérification ne s’applique jamais à eux. Une page web d’un autre site en envoie une, et c’est avec une clé API placée dans une telle page que ce site atteindrait le point d’accès. Tant que la vérification n’est pas imposée, chaque requête venant d’une origine hors de la liste est journalisée comme [mcp] origin-mismatch, avec l’origine, l’organisation et la personne. Lis ces lignes pour savoir lesquels de tes clients envoient une origine avant de définir TALE_MCP_ORIGIN_ENFORCE=true, et ajoute leurs origines à TALE_MCP_ALLOWED_ORIGINS.

Les quatre réglages en bas du tableau appartiennent à la connexion des agents de code, qui permet à un agent de se connecter au point d’accès MCP sans clé API. Tant qu’elle n’est pas complète, les agents se connectent avec une clé API et les deux voies restent désactivées. Pour lire un document de métadonnées client, le backend a besoin d’un accès HTTPS sortant vers l’hôte de l’agent. Il ne récupère jamais de document depuis une adresse privée ou depuis le déploiement lui-même, et ne suit jamais de redirection. L’enregistrement autonome n’accepte que les portées des agents de code, et son débit est limité par adresse source et par déploiement.

Infrastructure sandbox

Le spawner sandbox lit les paramètres ci-dessous. Transmets-les dans son environnement et recrée ce service après une modification. SANDBOX_MAX_SESSIONS fixe la capacité partagée par toutes les organisations. Le total des trois limites de travail d’une organisation se recalcule automatiquement ; tu ne peux pas enregistrer ces limites s’il dépasse cette capacité. Gère les limites dans Sandboxes, où les environnements réellement actifs et les mesures de l’hôte apparaissent séparément des allocations.

Les réglages backend ci-dessus doivent parvenir à l’API et au worker. Recrée ces services après une modification. Le spawner vérifie aussi la mémoire et le disque lors de la reprise d’une session libérée : un espace déjà démarré peut donc attendre de la capacité.

Les appareils connectés appliquent les mêmes contrôles de mémoire et d’espace disque qu’un hôte Docker local, tout en conservant leur plafond de sessions configuré.

Un daemon Docker arrêté volontairement reste prêt pour la prochaine commande ; les contrôles de santé ne le démarrent pas. Un contrôle qui échoue bloque immédiatement le nouveau travail, mais ne suffit pas à arrêter la session. La reprise après des contrôles défaillants exige au moins trois contrôles terminés en échec sur une période d’au moins cinq secondes. Un contrôle réussi ou un nouveau moteur efface cet historique. Un échec de démarrage confirmé ou un arrêt inattendu du moteur peut déclencher la reprise immédiatement. Après une vérification atomique de l’activité, le spawner peut alors arrêter une session inactive et non épinglée, en gardant son espace de travail pour le prochain démarrage. Sur Docker, l’arrêt de toute la session supprime son stockage Docker interne ; l’arrêt automatique du seul moteur interne inactif le conserve. Les sessions occupées ou épinglées restent en place et refusent de nouveaux démarrages jusqu’à ce que Docker réponde de nouveau ou qu’un opérateur résolve le problème.

Lors d’une mise à niveau progressive, garde chaque ancien spawner sur la référence fixe de son image runtime actuelle jusqu’à son remplacement. Ne déplace pas un tag runtime encore utilisé par un ancien spawner : il ne distingue pas les erreurs de contrôle passagères des pannes confirmées. Un nouveau spawner avec un ancien runtime refuse le nouveau travail quand Docker est indisponible et conserve les limites habituelles d’inactivité et de durée de vie.

Un spawner en conteneur contrôle automatiquement le système de fichiers des données Docker lorsqu’il peut vérifier son montage /etc/hostname existant auprès du daemon. Si cette détection est indisponible, le contrôle des espaces de travail reste actif et /health indique unavailable pour la surveillance du disque Docker. Un montage explicite en lecture seule du répertoire de données est prioritaire ; s’il ne peut être vérifié ou lu, l’admission attend qu’il soit disponible. Pour le configurer, consulte docker info --format '{{.DockerRootDir}}' et utilise ce chemin réel sur l’hôte. Docker Desktop et les daemons distants peuvent nécessiter une autre configuration. Avec Compose directement, ajoute la surcharge suivante et transmets les deux variables au service sandbox :

services:
  sandbox:
    environment:
      SANDBOX_DOCKER_DATA_ROOT: ${SANDBOX_DOCKER_DATA_ROOT}
      SANDBOX_DOCKER_DATA_PATH: /var/lib/tale-sandbox/docker-data
    volumes:
      - ${SANDBOX_DOCKER_DATA_ROOT}:/var/lib/tale-sandbox/docker-data:ro

Un seuil d’admission n’est pas un quota de stockage par session. Les volumes nommés Docker n’ont pas de limite de taille portable, et le respect de la taille demandée par un PVC Kubernetes dépend du stockage utilisé. Pour des quotas stricts, choisis un système de fichiers ou une classe de stockage qui les applique. Surveille séparément les espaces de stockage de containerd et les répertoires de volumes montés à part, ainsi que les volumes gérés par un pilote externe, en plus des espaces de travail, des couches d’images et des caches de build.

Les sessions Kubernetes utilisent /readyz pour le démarrage et /livez pour la vivacité du daemon. Un daemon Docker interne arrêté volontairement est considéré comme prêt au démarrage ; un daemon Docker en cours d’exécution doit répondre à sa sonde de santé. La sonde de vivacité ne vérifie que le daemon de la sandbox, afin qu’une dépendance défaillante ne fasse pas redémarrer une session occupée. Un daemon bloqué peut redémarrer même si sa session est épinglée. Les diagnostics Docker et egress apparaissent dans /healthz.

Une génération déjà active n’est pas comptée une seconde fois. Un workflow sans Docker interne garde l’identité et les outils de son agent, mais ne démarre aucun daemon Docker et ne maintient pas les conteneurs auxiliaires du cache de build en activité. Sans valeur explicite pour SANDBOX_AGENT_MEMORY, chaque session a une limite par défaut de 4g sans Docker interne ou de 8g avec Docker, même si d’autres sessions du déploiement utilisent Docker. Une valeur explicite s’applique aux deux modes. Ces limites sont des plafonds, pas de la mémoire réservée.

À pleine capacité, le spawner peut arrêter une session inactive, libérée et non épinglée avant le délai d’inactivité pour accepter un nouveau travail, en commençant par celle qui est inactive depuis le plus longtemps. Le daemon doit confirmer qu’aucun travail n’est en cours ; les sessions occupées ou dont l’état est inconnu restent protégées. L’arrêt conserve le répertoire ou le volume persistant de l’espace de travail. Sans session à récupérer en toute sécurité, la capacité du déploiement continue de bloquer les nouveaux démarrages. Il en va de même lorsque la mémoire libre de l’hôte passerait sous SANDBOX_MIN_FREE_MEMORY. Tant que le disque qui contient les espaces de travail des sessions reste sous SANDBOX_MIN_FREE_DISK, le nouveau travail attend sans que des sessions inactives soient arrêtées : une session arrêtée garde son espace de travail. Ce n’est que sous SANDBOX_CRITICAL_FREE_DISK que le spawner arrête aussitôt les sessions libérées et inactives avec Docker dans la sandbox, car leur arrêt supprime leur stockage d’images interne.

Les enregistrements du protocole des environnements d’agent, y compris les lignes inachevées, sont limités à 8 Mio. Une sortie trop volumineuse ou incomplète provoque un échec explicite ; l’aperçu de progression borné n’est jamais considéré comme un résultat structuré complet. Les réponses finales complètes sont conservées séparément de cet aperçu.

La reprise d’une session libérée encore en mémoire vérifie la même réserve et comptabilise son besoin mémoire prévu avant de reprendre le travail. Les reprises simultanées partagent ce calcul. Une réponse « occupé » permet une nouvelle tentative : elle ne supprime pas l’espace de travail et n’interrompt pas une session déjà occupée. Ces réservations ne limitent pas la croissance ultérieure des outils actifs ou des builders de l’organisation.

Lorsque Docker est activé dans les sandboxes d’agent, le daemon démarre automatiquement à la première commande Docker. Les agents n’ont aucun mode à choisir. Après cinq minutes sans client connecté, il s’arrête uniquement si aucun conteneur n’est en cours d’exécution, de redémarrage ou en pause et si toutes les règles de redémarrage automatique sont désactivées ; un état inconnu le maintient actif. La commande suivante le relance avec les mêmes images, volumes et espace de travail. Si des métadonnées de conteneurs existent déjà au démarrage du conteneur de session, le daemon démarre immédiatement pour respecter leurs règles de redémarrage. L’isolation, les privilèges et les limites mémoire du déploiement restent inchangés.

Dimensionner la capacité des sessions

Sans SANDBOX_MAX_SESSIONS sur un hôte Docker, le spawner dimensionne la capacité selon la mémoire et les CPU de l’hôte (une session par tranche de 768 MiB au-delà de la réserve, au plus deux par CPU : un hôte de 16 GiB avec 8 CPU obtient 16 sessions, un hôte de 64 GiB avec 16 CPU en obtient 32 ; un hôte de 16 GiB en obtient 9 quand les sessions d’agent font tourner leur propre daemon Docker) et n’admet une nouvelle session que si l’hôte garde SANDBOX_MIN_FREE_MEMORY de libre, en comptant ce que les sessions encore au démarrage ou tout juste démarrées vont bientôt occuper. Un pic de nouvelles sessions qui surchargerait l’hôte attend donc au lieu de démarrer ; ce contrôle n’empêche pas les sessions déjà lancées de continuer à grandir. Quand le CPU de l’hôte est sous pression (SANDBOX_CPU_PRESSURE_PERCENT), les nouvelles sessions démarrent de même une à une au lieu d’alourdir la charge. Chaque exécution d’agent de projet qui travaille en même temps qu’une autre prend sa propre session, un worker d’agent : un agent qui travaille sur trois tâches à la fois fait tourner trois sessions, chacune avec sa propre limite SANDBOX_AGENT_MEMORY. Ces deux réglages bornent donc la quantité de travail d’agent menée en parallèle. Fixe toi-même la capacité sous Kubernetes, avec un daemon Docker distant ou si l’hôte fait aussi tourner d’autres charges gourmandes : teste alors les tâches que ton déploiement exécutera en même temps. Le rendu dans le navigateur et les builds Docker n’ont pas les mêmes pics de charge ; inclus les agents, les workflows et l’exploration de toutes les organisations. Une place libre ne garantit pas des ressources suffisantes.

Sous Docker, relève la consommation pendant que des tâches représentatives s’exécutent en parallèle. Répète cette commande pendant l’exécution ; une mesure au repos ne montre pas les pics des tâches :

docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'

Retire de la mémoire de l’hôte la part nécessaire au système, aux services de la plateforme, aux bases de données, aux conteneurs auxiliaires de build et à une marge de sécurité. Divise le reste par le pic mesuré par session active, puis arrondis à l’entier inférieur. Par exemple, un hôte de 32 GiB avec 8 GiB mis de côté et un pic mesuré de 3 GiB par session donne (32 - 8) / 3 = 8 sessions. C’est un exemple de calcul, pas un benchmark. Pour des tâches différentes, additionne leurs pics simultanés et vérifie la saturation du CPU ainsi que la durée des tâches avant d’augmenter la limite.

Les 4 GiB ou 8 GiB d’un agent sont un plafond de mémoire ; cette mémoire n’est pas réservée au démarrage. Huit agents qui exécutent des builds Docker peuvent donc consommer bien plus que huit sessions surtout inactives. Mesure avec une charge représentative et garde une marge. Passe à 16 ou plus seulement si l’hôte tient cette charge dans la durée. Avant de réduire la capacité, abaisse les totaux d’organisation qui dépassent la nouvelle valeur. Les limites par défaut d’une organisation totalisent 6 ; une capacité inférieure demande aussi des limites d’organisation plus basses.

Appliquer un changement de capacité

Ajoute ou modifie cette ligne dans le .env du déploiement, en conservant les autres entrées. Les valeurs explicites restent en vigueur après une mise à niveau ; sans valeur, un hôte Docker dimensionne la capacité selon sa mémoire comme décrit plus haut, et Kubernetes utilise 8.

SANDBOX_MAX_SESSIONS=8

Pour une stack Compose que tu gères toi-même, recrée uniquement le service sandbox avec son image locale existante :

docker compose up -d --no-deps --no-build --pull never sandbox

Utilise le même projet, les mêmes fichiers -f et les mêmes options de fichiers d’environnement que la stack active. Un redémarrage seul ne charge pas un .env modifié. Pour une installation gérée par la CLI, suis la procédure de déploiement dans Mises à niveau. Sous Kubernetes, définis la variable dans le Deployment du spawner sandbox, puis déploie cette nouvelle configuration.

Vérifie la nouvelle capacité du déploiement dans Sandboxes. Avec des limites d’organisation de 2/2/2 et une capacité de 8, le total affiche 6 / 8. Les réglages existants des organisations sont conservés ; leur total doit toujours respecter la capacité actuelle pour être enregistré. Ce changement n’augmente pas les limites de CPU ou de mémoire des conteneurs.

Après une mise à niveau

La capacité par défaut était de 16, et les organisations créées avant cette version ont reçu les limites 2/4/4, soit un total de 10. Un déploiement qui n’a jamais défini SANDBOX_MAX_SESSIONS démarre donc la nouvelle version avec une capacité de 8 et des organisations dont le total enregistré la dépasse. Le travail en cours n’est pas touché, et chaque organisation continue d’admettre du travail selon ses limites enregistrées ; seul l’enregistrement de la page Sandboxes reste bloqué tant que le total ne rentre pas, et abaisser une limite s’enregistre toujours. Définis SANDBOX_MAX_SESSIONS=16 explicitement pour conserver la capacité précédente, ou demande à chaque organisation concernée d’abaisser une limite.

À partir de cette version, un déploiement Docker qui n’a jamais défini SANDBOX_MAX_SESSIONS obtient une capacité dimensionnée selon la mémoire de son hôte au lieu de 8, jamais moins de 8. Il peut admettre plus de sessions à la fois qu’avant, et seulement tant que l’hôte a de la mémoire disponible. Une valeur explicite fixe la capacité et désactive le contrôle adaptatif de la mémoire ; choisis-la selon les pics de mémoire mesurés. Le seuil d’espace disque reste actif.

Cette capacité dimensionnée compte désormais aussi au plus deux sessions par CPU : un hôte avec beaucoup de mémoire et peu de CPU obtient donc moins de sessions qu’avant (un hôte de 16 GiB avec 4 CPU : 8 au lieu de 19). Quand le CPU de l’hôte est sous pression, les nouvelles sessions démarrent en outre une à une (SANDBOX_CPU_PRESSURE_PERCENT, 0 désactive ce comportement). Une valeur explicite de SANDBOX_MAX_SESSIONS reste inchangée.

Caches de build Docker

La préparation du cache de build partagé utilise SANDBOX_BUILDKITD_PROVISION_TIMEOUT_MS (5 secondes par défaut). Chaque session attend au plus cette durée ou un quart de son budget total de démarrage si ce délai est plus court, puis utilise son builder local. La préparation partagée a son propre budget borné : annuler l’attente d’une session n’annule pas la préparation destinée aux autres sessions, et un résultat tardif ne se rattache pas à une session déjà passée au builder local. Les miroirs de registry sont préparés en parallèle. Le nombre d’étapes simultanées du builder partagé correspond à sa limite CPU arrondie à l’entier inférieur, avec un minimum de un ; sa limite de mémoire reste applicable. Le temps de préparation est déduit du budget de démarrage restant de la session.

Les caches de build Docker sont isolés par organisation. Chaque organisation utilise un builder privilégié et trois miroirs de registre sans privilèges élevés. Dès qu’aucune session ne peut encore les utiliser, les conteneurs auxiliaires s’arrêtent après SANDBOX_BUILDKITD_IDLE_MS (10 minutes), et les miroirs de registre sont supprimés avec leurs caches, car le cache du builder garde les couches de base que ses builds ont utilisées. Le prochain build redémarre le builder avec son volume de cache conservé et recrée les miroirs. Juste avant l’arrêt du builder, le spawner réduit son cache à SANDBOX_BUILDKITD_IDLE_CACHE, car son nettoyage ne tourne que tant qu’il tourne. Le cache d’une organisation arrêtée n’est plus réduit ensuite ; après SANDBOX_BUILDKITD_CACHE_RETENTION (14 jours) sans build, ses conteneurs auxiliaires et ses caches sont supprimés, et sinon ils partent avec l’organisation. Tant que le disque des sessions reste sous SANDBOX_MIN_FREE_DISK, les caches des organisations arrêtées partent plus tôt, en commençant par celles arrêtées depuis le plus longtemps. Le réseau et le volume de cache du builder restent disponibles pour être réutilisés. Les sessions Kubernetes utilisent leur propre builder Docker interne ; la réconciliation Kubernetes n’appelle pas la CLI Docker pour ces conteneurs auxiliaires.

Le spawner remplit le premier pool d’adresses Docker disponible avec les réseaux d’organisation avant de passer au suivant. Par défaut, chaque réseau reçoit un /23 de 512 adresses ; un /16 entièrement libre peut donc accueillir 128 réseaux d’organisation. Les sous-réseaux plus petits configurés dans Docker gardent leur taille. Le spawner exclut les réseaux Docker existants, les routes et les adresses des serveurs DNS de l’hôte du daemon Docker, ainsi que 172.31.0.0/16 pour les anciennes images de runtime, puis vérifie le réseau créé.

Pour observer l’hôte du daemon même avec Docker à distance, le spawner lance brièvement l’image BuildKit configurée dans le namespace réseau de l’hôte. Ce conteneur utilise un système de fichiers en lecture seule, sans capacités Linux ni montages. Si cette observation échoue ou qu’aucun sous-réseau sûr ne reste disponible, les sessions construisent localement sans cache partagé. Le spawner recrée un réseau inutilisé qui lui appartient si son sous-réseau est invalide ; il conserve les réseaux utilisés ou appartenant à un autre propriétaire.

Une mise à niveau crée des caches d’organisation vides et conserve pour l’instant les anciennes données globales. Les anciens conteneurs auxiliaires s’arrêtent automatiquement dès qu’aucune session active n’en dépend. Une fois qu’ils sont arrêtés depuis plus de SANDBOX_BUILDKITD_CACHE_RETENTION (14 jours) et qu’aucune session n’en dépend toujours, le spawner supprime ces conteneurs auxiliaires et les quatre anciens volumes de cache (tale-buildkitd-cache ainsi que tale-buildkitd-mirror-cache-docker-io, -ghcr-io, -quay-io), chacun seulement tant qu’il porte l’ancienne étiquette du cache de build sans organisation, et journalise chaque suppression ; off les garde. Laisse se terminer les anciennes sessions épinglées ou arrête-les pour achever la transition ; jusque-là, l’ancien service de cache partagé reste accessible. L’automatisation du navigateur utilise Chromium sans interface graphique. La vue en direct et la prise de contrôle manuelle ont été retirées.

Images du moteur Docker interne

Quand le cache de build partagé est actif, le moteur Docker interne d’une session télécharge les images Docker Hub via le miroir de registre docker.io de son organisation, le même cache que ses builds, et revient à Docker Hub quand ce miroir ne tourne pas. Les images des autres registres sont téléchargées directement. Un moteur interne qui devient inactif avec plus de 10 GiB d’images et de cache de build supprime d’abord ses images orphelines et réduit son cache de build aux 5 GiB utilisés le plus récemment ; les images nommées, les conteneurs et les volumes restent. Sur Kubernetes, c’est la limite de taille du volume du stockage interne qui le borne quand elle est inférieure à 10 GiB.

Réseaux Docker internes

Sur Docker et Kubernetes, le choix automatique vérifie les routes IPv4 et leurs passerelles dans toutes les tables de routage, les adresses et préfixes des interfaces, les serveurs DNS et les adresses résolues des hôtes de proxy et de passerelle configurés dans l’environnement au démarrage du conteneur. Les hôtes transmis plus tard pendant un tour d’agent échappent à cette observation initiale. Il tient aussi compte du réseau d’organisation Docker raccordé ensuite. Le runtime privilégie 172.31.0.0/16 s’il est libre, puis essaie d’autres plages privées /16. Le premier /24 sert à docker0 ; les réseaux Compose internes utilisent des blocs /24 du même pool. En mode automatique, une observation indisponible ou l’absence de plage libre empêche le démarrage de la session.

Un Pod ne peut pas déduire tous les CIDR des Pods, des Services et du VPC du cluster depuis son propre namespace réseau. Pour DinD sur Kubernetes, définis SANDBOX_DIND_INNER_POOL avec un /16 privé que tu as vérifié contre l’ensemble de ces réseaux. Un pool explicite reste refusé si le runtime détecte un chevauchement ou une valeur invalide. Si certaines observations manquent, il les indique dans un avertissement et peut continuer avec ce pool ; c’est à toi de tenir compte des plages invisibles depuis le Pod.

Après avoir modifié ce pool, redémarre le spawner et recrée les sessions existantes pour leur appliquer la valeur. Redémarrer le conteneur runner dans le même Pod Kubernetes conserve l’environnement du Pod et le stockage Docker interne.

Le proxy egress autorise les requêtes DNS vers les adresses IP de serveurs de noms validées dans son /etc/resolv.conf, y compris le DNS privé du cluster. Chaque exception se limite à cette IP exacte et au port de destination 53 en UDP/TCP. Les autres destinations privées et le transfert entre réseaux raccordés restent bloqués.

Protection du transfert IPv6

Garde sandbox, sandbox-egress et SANDBOX_RUNTIME_IMAGE sur la même version lors d’une mise à niveau. Avant de raccorder le réseau de build Docker d’une organisation, le spawner vérifie la protection de la session contre le transfert de paquets. Compose et les conteneurs de session Docker générés désactivent IPv6 avec net.ipv6.conf.all.disable_ipv6=1 et net.ipv6.conf.default.disable_ipv6=1. Conserve les deux valeurs dans tes propres définitions Docker.

Les Pods Kubernetes ne reçoivent pas automatiquement de sysctls non sûrs. Le proxy egress a besoin d’un pare-feu IPv6 fonctionnel ou d’IPv6 désactivé dans son namespace réseau. Si le pare-feu IPv6 est indisponible, l’entrypoint tente cette désactivation locale, puis vérifie la valeur par défaut et chaque interface. Un /proc/sys en lecture seule ou des droits insuffisants peuvent l’en empêcher ; IPv6 encore actif sans protection bloque le démarrage. Configure le Pod egress avant le déploiement avec les paramètres réseau autorisés par ton cluster.

Accès SSH aux repositories

La sandbox native contient OpenSSH et netcat-openbsd. Accorde une clé remplaçable limitée au repository comme secret nommé de l'agent, puis charge-la dans ssh-agent via stdin pendant le tour autorisé. Garde ses octets privés dans l'environnement ; ne crée jamais de fichier de clé et ne les affiche pas. Un tour lancé par un Membre ne reçoit aucun secret d'agent. Les commits Git utilisent le nom et l'e-mail du propriétaire du workspace même sans autorisation de connector GitHub.

Les sessions internes utilisent leur HTTP_PROXY existant pour les connexions sortantes. Le SSH direct ne peut pas compter sur le DNS externe dans ce réseau. Utilise le tunnel HTTP CONNECT du proxy et un port autorisé. GitHub prend en charge SSH sur ssh.github.com:443 ; vérifie l'hôte avec les empreintes publiées par GitHub, comme décrit dans SSH sur le port 443. Prépare un fichier known-hosts public contenant la clé vérifiée indépendamment, puis configure la commande après le chargement de la clé privée par l'agent :

import os
import shlex
import subprocess
from urllib.parse import urlsplit

proxy = urlsplit(os.environ["HTTP_PROXY"])
if proxy.scheme != "http" or not proxy.hostname or not proxy.port or proxy.username or proxy.password:
    raise ValueError("Expected the existing unauthenticated HTTP egress proxy")
connect = shlex.join(["nc", "-X", "connect", "-x", f"{proxy.hostname}:{proxy.port}", "%h", "%p"])
environment = os.environ.copy()
environment["GIT_SSH_COMMAND"] = shlex.join([
    "ssh", "-o", f"ProxyCommand={connect}", "-o", "StrictHostKeyChecking=yes",
    "-o", "UserKnownHostsFile=/tmp/repository-known-hosts",
    "-o", "GlobalKnownHostsFile=/dev/null", "-o", "BatchMode=yes",
    "-o", "ConnectTimeout=20",
])
subprocess.run(["git", "ls-remote", "--exit-code", "ssh://git@ssh.github.com:443/org/repository.git", "HEAD"], env=environment, check=True, timeout=30)

Le fichier known-hosts contient uniquement la clé publique de l'hôte du fournisseur ; la clé privée du repository reste dans ssh-agent. La politique egress existante et la portée d'accès de la clé du repository continuent de s'appliquer. Aucune autorisation de connector GitHub plus large n'est nécessaire.

Appareils de sandbox

Les organisations peuvent exécuter leurs sandboxes sur leurs propres machines, qu’elles connectent dans Paramètres > Sandboxes. Un appareil se connecte en HTTPS à <SITE_URL><BASE_PATH>/sandbox/tunnel et garde un WebSocket ouvert. Le proxy fourni transmet ce chemin, et uniquement celui-ci, au hub d’appareils du spawner ; l’API signée du spawner reste sur le réseau interne. Les appareils ont besoin du backend Docker : avec Kubernetes, le hub reste désactivé.

Un appareil exécute toujours la version du serveur. Il apprend la version à chaque renouvellement de sa connexion et remplace ses propres conteneurs dès que le serveur change de version, sauf s’il a été connecté avec --no-auto-update. Il ne conserve aucune donnée sur le serveur : ses espaces de travail restent sur la machine. Les sandboxes d’un appareil joignent les points d’accès sandbox du backend et la passerelle de modèles par la connexion de l’appareil, sur les mêmes chemins que les sessions sur le serveur ; l’API d’administration de la passerelle n’est jamais accessible par cette voie. Un appareil conserve les adresses du backend et de la passerelle reçues lors de sa connexion : après avoir modifié SANDBOX_HTTP_API_BASE_URL ou EXTERNAL_AGENT_GATEWAY_URL, lance tale sandbox update sur chaque appareil.

Un appareil doit faire confiance au certificat TLS du site. Un déploiement avec TLS_MODE=selfsigned ne peut pas accueillir d’appareils.

Si tu utilises ton propre proxy au lieu du proxy fourni, transmets /sandbox/tunnel au port SANDBOX_HUB_PORT du spawner, conserve les mises à niveau WebSocket et l’en-tête Authorization, et autorise des connexions qui restent ouvertes pendant des heures.

Tours d'agent en sandbox

Cherche pourquoi la sortie n’est plus lue avant d’augmenter ce délai. Il limite les flux de sortie abandonnés, pas la durée totale d’une tâche. Recrée les rôles backend concernés après avoir changé l’environnement.

Un nombre de workers modifié atteint chaque fournisseur la prochaine fois qu’une organisation qui l’utilise démarre une session sandbox ou appelle les endpoints de modèles. Un nombre plus bas atteint aussi tous les autres fournisseurs que la passerelle garde : après un redémarrage, le backend les redimensionne deux à cinq minutes après sa première session sandbox ou sa première requête aux endpoints de modèles.

Un fournisseur dont l’hôte en amont ne se résout plus, comme celui d’un connecteur supprimé ou d’un hôte que tu as retiré de ton réseau, fait exception : la passerelle refuse de le réécrire, il garde donc ses workers, et le backend journalise après chaque redémarrage un avertissement qui le nomme. Supprime un tel fournisseur de la passerelle. Un fournisseur encore utilisé est recréé à sa prochaine session sandbox ou à sa prochaine requête aux endpoints de modèles. Envoie la requête depuis un conteneur backend, qui joint la passerelle et connaît son mot de passe administrateur ; sur un hôte tale deploy, son nom contient -backend-api :

docker exec <backend-api-container> sh -c 'curl -fsS -X DELETE -u "${SANDBOX_LLM_GATEWAY_ADMIN_USERNAME:-admin}:$SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD" "${SANDBOX_LLM_GATEWAY_URL:-http://sandbox-llm-gateway:8080}/api/providers/<name>"'

Sur Kubernetes, utilise kubectl exec -n tale deploy/backend-api -- à la place de docker exec <backend-api-container>.

La passerelle démarre les workers de tous ses fournisseurs pendant son démarrage, avant que le backend puisse la joindre. Des fournisseurs enregistrés avec plus de workers que ces valeurs (la valeur par défaut de la passerelle elle-même est de 1 000) peuvent demander plus de mémoire que sa limite, 512 Mio avec tale deploy et dans le manifeste Kubernetes, et la passerelle est alors arrêtée à chaque démarrage. Ne supprime pas son volume, qui contient son compte administrateur et les clés qu’elle a émises. Augmente plutôt la limite jusqu’à ce que la passerelle démarre : sur un hôte tale deploy, lance docker update --memory 2g --memory-swap 2g <container> pour le conteneur dont le nom se termine par -sandbox-llm-gateway ; sur Kubernetes, augmente resources.limits.memory de son Deployment. Démarre ensuite une session sandbox ou appelle les endpoints de modèles, puis attends la ligne [llm-gateway] provider worker resize finished dans le journal du backend, qui arrive deux à cinq minutes plus tard. Elle compte les fournisseurs que le backend a redimensionnés, ceux que la passerelle a refusés et ceux que le backend n’a pas pu confirmer. Un fournisseur refusé ou non confirmé garde ses workers, et un avertissement avant cette ligne le nomme ; un backend redémarré réessaie un fournisseur non confirmé. Avant de rétablir la limite, supprime comme décrit plus haut un fournisseur refusé dont l’hôte en amont ne se résout plus. Rétablis ensuite la limite avec docker update --memory 512m --memory-swap 1g <container> puis docker restart <container>, ou, sur Kubernetes, la valeur d’origine du Deployment.

Ingestion de liens vidéo (yt-dlp)

Le worker utilise ces valeurs pour récupérer les transcriptions vidéo. Son image comprend yt-dlp et un plugin de jetons PO. Importation vidéo distingue les restrictions de source, les problèmes de sortie réseau et les sessions autorisées. Recrée le worker après une modification de son environnement ; relire une variable dans un processus ne recharge pas .env.