Secrets
Comment Beeuni stocke les identifiants du projet et contrôle si le code de l’agent peut lire chaque valeur.
Un secret est un identifiant propre à un projet — une clé API, un jeton ou une chaîne de connexion — dont une session a besoin, mais qui ne doit pas se trouver dans le dépôt. Beeuni stocke les secrets dans le projet, jamais dans le compte, et chiffre chaque valeur avec AES-256-GCM à l’aide d’une clé dérivée pour chaque projet.
Identifiant et nom
Chaque secret a deux noms. Le identifier est l’identifiant que vous utilisez dans la CLI et dans l’octroi secrets d’un agent. Le name est la clé de variable d’environnement en majuscules dans le bac à sable, par exemple STRIPE_API_KEY. Dans la plupart des projets, l’identifiant et le nom sont identiques. Ils ne diffèrent que lorsqu’un projet contient plusieurs valeurs possibles pour un même nom — par exemple, une clé Google Maps principale et une clé de secours peuvent toutes deux correspondre à GOOGLE_MAPS_API_KEY.
Toutes les règles d’accès utilisent l’identifiant. Aucune n’utilise le nom.
Exposition et utilisation
Un secret comporte deux paramètres indépendants. Examinez-les séparément : ils répondent à des questions différentes.
| Paramètre | Question à laquelle il répond | Valeurs |
|---|---|---|
| Exposition | Le code de l’agent peut-il lire la valeur réelle ? | environment, egress-enforced, none |
| Utilisation | Qui la dépense ? | Code de l’agent, passerelle LLM, connecteur, Git |
L’ancienne documentation Beeuni présentait une liste unique mêlant les deux. Elle n’existe plus. Il n’y a pas de choix entre une « frontière réseau » et un « mandataire HTTPS » : un seul mécanisme s’applique à tous les secrets soumis à l’application des règles de sortie, quel que soit le fournisseur de bac à sable.
Les trois expositions
| Exposition | Contenu du bac à sable | À utiliser pour |
|---|---|---|
| Environnement | La valeur réelle, sous forme de variable d’environnement en clair | Le choix par défaut. Les valeurs avec lesquelles l’agent doit effectuer des calculs, et les protocoles autres que HTTPS |
| Sortie contrôlée | Un handle — un espace réservé auto-descriptif, sans valeur en soi | Expérimental. Les appels HTTPS, une fois le flag secrets_egress activé |
| Aucune | Rien du tout | Un identifiant utilisé uniquement par un service Beeuni, ou une valeur conservée dans le dossier et désactivée |
Utilisations
La plupart des utilisations sont attribuées par Beeuni, et non par vous :
- Code de l’agent — implicite dès que l’exposition n’est pas
none. - Passerelle LLM — attribuée lorsque la valeur est une clé reconnue d’un fournisseur de modèles. La passerelle authentifie les requêtes au fournisseur côté serveur.
- Connector:<slug> — attribuée par le processus de liaison du connecteur.
- Git — attribuée par Beeuni pour son propre accès à Git. Lecture seule ; vous ne pouvez ni la définir ni la supprimer.
Un secret dont l’exposition est none et qui n’a aucune utilisation apparaît comme Désactivé : il est stocké, chiffré et n’est utilisé par rien.
Secrets transmis et secrets calculés
L’exposition qu’un secret peut utiliser dépend de la source en amont, et non de Beeuni.
- Secrets transmis — la valeur est transmise sur le réseau. Clés API, jetons Bearer, mots de passe. C’est le cas le plus courant. À un moment donné, la valeur se trouve dans une requête sortante sous forme d’octets ; Beeuni peut donc l’y insérer lui-même, hors du bac à sable. Un secret transmis peut passer en sortie contrôlée une fois le flag
secrets_egressactivé ; par défaut, il est chargé dans l’environnement du bac à sable. - Secrets calculés — la valeur entre dans un calcul et n’est jamais transmise. Clés de signature AWS SigV4, secrets de signature HMAC de webhook, assertions de client JWT, clés privées SSH. Celui qui effectue le calcul doit détenir la valeur. Une frontière réseau n’y change rien, puisque les identifiants ne figurent pas dans les données transmises. Les secrets calculés doivent rester dans l’environnement.
L’environnement est l’exposition par défaut et la seule qui puisse servir un identifiant sur lequel le bac à sable doit effectuer des calculs. Les protocoles autres que HTTPS — chaîne de connexion Postgres, identifiants SMTP — sont dans le même cas : ils doivent rester dans l’environnement.
Lorsque vous enregistrez une valeur qui ressemble à du matériel de signature, comme une paire de clés d’accès AKIA… ou du matériel PEM/SSH, Beeuni choisit Environnement par défaut et en explique la raison : cette clé signe les requêtes localement, donc l’application des règles de sortie ne peut pas s’appliquer.
Exposition à sortie contrôlée
Le bac à sable reçoit une variable d’environnement dont la valeur est un handle, et non l’identifiant. L’agent utilise cette variable comme il utiliserait la vraie clé — dans un en-tête, une chaîne de requête ou un corps. Authorization: Bearer $VAR, Cookie: …=$VAR, un en-tête X-Api-Key, un paramètre de requête et un champ de corps JSON ou de formulaire fonctionnent tous : Beeuni repère le handle où qu’il apparaisse (brut, encodé dans une URL, en base64 seul ou échappé dans du JSON) et le remplace par la valeur réelle. À la sortie, Beeuni remplace le handle par la valeur réelle, mais uniquement pour les requêtes vers les hôtes que vous avez approuvés.
Conséquences de ce fonctionnement :
- La valeur réelle ne se trouve jamais dans le bac à sable : ni comme variable d’environnement, ni dans un fichier, ni sous forme d’alias.
- Un handle envoyé à un hôte que vous n’avez pas approuvé lui parvient sous forme de chaîne littérale. Le serveur en amont le rejette. Il ne vaut rien.
- Un handle dont la signature est invalide n’est jamais accepté et Beeuni le consigne comme handle falsifié. Un handle valide associé à un secret que cette session n’est pas autorisée à utiliser est consigné comme volé.
- Chaque requête relayée génère une entrée d’audit par requête.
- Les requêtes vers les hôtes qui ne figurent pas dans la liste sont acheminées par le tunnel sans être lues. Les clients avec TLS épinglé et mTLS vers ces hôtes ne sont pas affectés.
Correspondance exacte des hôtes
Indiquez chaque hôte appelé, avec un nom d’hôte exact par ligne.
| Rejeté | Motif |
|---|---|
Un hôte générique, *.example.com |
L’agent ne doit jamais choisir la destination |
| Un schéma d’URL autre que HTTPS | Beeuni termine la connexion TLS pour effectuer la substitution |
api.example.com ne couvre pas uploads.api.example.com. Ajoutez le second hôte au même secret. Beeuni rejette les règles inapplicables avec 400 lorsque vous les enregistrez : il ne stocke jamais une règle qu’il ne peut pas appliquer.
Deux secrets soumis à l’application des règles de sortie peuvent partager un hôte. Chaque identifiant correspond à sa propre valeur, qui est donc correctement substituée dans la même requête.
Vérifiez avec deux sondes
Exécutez les deux sondes depuis le bac à sable, vers un hôte figurant sur la liste.
L’exemple utilise postman-echo.com, qui propose un point de terminaison de chaque type.
Ajoutez-le à la liste des hôtes autorisés pour la durée du test.
# 1. Reachability — an endpoint that does NOT echo request headers.
curl -s -o /dev/null -w '%{http_code}\n' https://postman-echo.com/status/200
# expected: 200
# 2. Substitution — an endpoint that DOES echo request headers.
curl -sS -H "authorization: Bearer $STRIPE_API_KEY" https://postman-echo.com/get
# expected: 200, with "Bearer [REDACTED]" in the echoed headers
Examinez les deux résultats ensemble, en commençant par la sonde 1 : c’est la seule qui indique si l’hôte est joignable, et la sonde 2 ne prouve rien tant qu’elle n’a pas réussi.
| Résultat de la sonde 2 | Signification |
|---|---|
200, l’en-tête renvoyé affiche [REDACTED] |
Fonctionne. La vraie valeur a été transmise en amont et la réponse renvoyée a été expurgée. |
200, l’en-tête renvoyé affiche l’identifiant lui-même |
La substitution n’a pas eu lieu. Vérifiez la liste des hôtes et l’autorisation accordée à l’agent. |
401 depuis un véritable hôte d’API |
La substitution n’a pas eu lieu. Même vérification. |
| Réponse vide ou erreur de connexion | Il s’agit d’un véritable échec, pas d’un signe de réussite. |
Vérifiez que la vraie valeur n’est présente nulle part dans l’environnement invité :
env | grep '^STRIPE_API_KEY='
# expected: the handle, not the credential
L’identifiant figure également dans BEEUNI_SECRET_CAPABILITIES, le catalogue sans valeurs qui indique à l’agent quels secrets existent, quelle variable contient chaque identifiant et quels hôtes sont couverts par chacun. Il ne contient jamais de valeur.
Un hôte figurant sur la liste présente un certificat délivré par Beeuni pour ce bac à sable, auquel celui-ci fait déjà confiance, plutôt que le certificat de l’origine :
curl -sv https://postman-echo.com/status/200 2>&1 | grep 'issuer:'
# issuer: CN=Beeuni Egress CA (<project prefix>); O=Beeuni
Ce que change le relais
Un hôte approuvé est joint via Beeuni ; son comportement diffère donc légèrement d’un appel direct :
- Les réponses ne sont pas diffusées en flux. Les événements envoyés par le serveur et les websockets ne fonctionnent pas via un hôte approuvé.
- Le corps d’une requête est limité à 1 Mio, une réponse à 5 Mio et la durée totale de l’appel à 30 secondes. Beeuni suit au maximum 3 redirections.
- Seul un ensemble fixe d’en-têtes de réponse est renvoyé : le type et la langue du contenu, les validateurs de cache, les en-têtes de limitation du débit,
retry-after,x-request-id. - Seuls les clients qui respectent
https_proxysont interceptés. Beeuni définit cette variable et la confiance correspondante dans l’autorité de certification dans l’environnement de l’agent. Un processus lancé avec un environnement nettoyé appelle directement l’hôte, et sa requête part avec l’identifiant.
Pour les requêtes que Beeuni ne peut pas intercepter, l’agent dispose d’un accès explicite aux mêmes hôtes, selon la même politique :
beeuni secrets call STRIPE_API_KEY https://api.stripe.com/v1/customers
Exposition via l’environnement
Le bac à sable reçoit la vraie valeur sous forme de variable d’environnement ordinaire. Le code de l’agent peut la lire, l’afficher et la transmettre n’importe où. Beeuni ne peut ni l’expurger, ni auditer son utilisation, ni empêcher qu’elle soit divulguée.
L’exposition via l’environnement est celle par défaut. Chaque nouveau secret l’utilise, sauf si vous le déplacez vers le mode soumis à l’application des règles de sortie, qui est expérimental et nécessite le drapeau secrets_egress. Un identifiant calculé et tout protocole autre que HTTPS doivent rester dans l’environnement.
Qui peut utiliser un secret
Chaque valeur secrète a un public — le même choix Qui peut l’utiliser que pour un compte de connecteur :
| Choix | Qui peut utiliser la valeur |
|---|---|
| Tout le monde dans le projet (par défaut) | Chaque session du projet, y compris les déclencheurs, les tâches planifiées et les sessions partagées. |
| Vous uniquement | Vous, directement, et vos propres sessions privées. |
| Personnes, groupes ou agents spécifiques | Les personnes et groupes que vous choisissez (directement et dans leurs propres sessions privées), ainsi que les agents sélectionnés (dans toutes leurs sessions). |
Une session correspond à deux entités à la fois : son agent, toujours, et sa personne, uniquement tant que la session est privée.
- Une personne accède à une valeur dans une session privée démarrée par cette personne. Un message de quelqu’un d’autre efface la personne associée à la session : la valeur cesse alors d’y être accessible. Les sessions partagées, les déclencheurs, les tâches planifiées, les webhooks et les sessions par e-mail ou Telegram n’ont pas de personne.
- Un agent accède à une valeur dans chacune de ses sessions, y compris les déclencheurs, les tâches planifiées et les sessions partagées. Partagez une valeur avec l’agent si une exécution sans surveillance en a besoin. Toute personne pouvant exécuter cet agent peut alors utiliser la valeur par son intermédiaire : l’accès dépend donc de l’autorisation d’exécuter l’agent (les personnes autorisées sont définies dans les paramètres de l’agent).
- Les consommateurs côté serveur suivent la même règle. Un connecteur associé au secret ne l’utilise que pour les appelants qui font partie du public autorisé. Les autres obtiennent
credential_not_shared, et aucune requête ne quitte Beeuni. - Les services Beeuni qui n’agissent pour personne — le proxy Git, la vérification des signatures de webhook, les installations de canaux et les applications Beeuni — utilisent uniquement les valeurs partagées avec tout le monde.
Plusieurs valeurs peuvent porter le même nom. Une valeur partagée avec la personne de la session prévaut sur celle partagée avec son agent, qui prévaut à son tour sur celle partagée avec tout le monde. Exemple : DEEL_API_TOKEN contient une valeur d’équipe, et une seconde valeur portant l’identifiant DEEL_API_TOKEN-finance est partagée uniquement avec le groupe Finance. Les membres de Finance obtiennent la valeur Finance dans leurs sessions privées ; tous les autres, ainsi que chaque déclencheur, obtiennent la valeur de l’équipe.
Une personne définit le public. Une session d’agent ne peut pas le modifier (403) : un agent ne peut donc ni élargir l’accès à une valeur dont il a été exclu, ni s’y ajouter. Les personnes qui gèrent les secrets du projet voient tout de même les valeurs qui ne leur sont pas partagées, avec la mention Non partagé avec vous, afin de pouvoir en élargir l’accès.
Partager une session contenant une valeur personnelle
Une valeur partagée uniquement avec vous, qui a été transmise à votre session privée sous forme de variable d’environnement, est en clair dans ce bac à sable. Partager la session permettrait à chaque nouveau participant de la lire, et une variable d’environnement ne peut pas être retirée d’un bac à sable en cours d’exécution. Beeuni refuse donc de partager cette session ou de créer un lien public vers celle-ci si elle contient 409 PERSONAL_SECRET_REQUIRES_PRIVATE_SESSION et les noms associés. Démarrez une nouvelle session pour la partager ou partagez d’abord la valeur avec tout le monde. Les valeurs accessibles via l’agent, ainsi que celles soumises à l’application des règles de sortie ou utilisées côté serveur (vérifiées à chaque requête), n’empêchent pas le partage.
Lorsque vous restreignez le public, Beeuni transmet de nouveau les paramètres à chaque bac à sable en cours d’exécution. Une valeur déjà transmise comme variable d’environnement reste dans le bac à sable jusqu’à son redémarrage. Si elle a pu être lue, faites-la tourner.
Saisir une valeur via un lien
Un agent qui a besoin d’une valeur que vous ne lui avez pas fournie vous envoie un lien. La page du lien propose le choix Qui peut l’utiliser : tout le monde dans le projet (par défaut) ou uniquement la personne qui l’a demandé. Choisissez la seconde option pour toute information personnelle, comme un jeton de paie ou des identifiants de connexion personnels. La page indique le nom d’affichage de la personne qui en a fait la demande, jamais son adresse e-mail, car toute personne disposant du lien peut l’ouvrir.
Remplacement personnel
Un remplacement personnel est votre propre valeur pour un nom donné. Elle est utilisée à la place de la valeur partagée dans les sessions que vous démarrez. Pour l’instant, Beeuni l’utilise uniquement pour un identifiant de connexion OAuth. Beeuni ne permet jamais, par exemple, d’utiliser une clé de fournisseur LLM comme ANTHROPIC_API_KEY en tant que remplacement personnel.
Ajouter un secret
Définir la valeur depuis la CLI
beeuni secrets set STRIPE_API_KEY=sk_live_...Beeuni l’enregistre pour tout le monde dans le projet. Ajoutez --only-me pour qu’elle ne soit utilisable que par vous. Pour stocker plusieurs valeurs sous le même nom, ajoutez --identifier <id>. Les noms ne peuvent pas commencer par BEEUNI_ : Beeuni réserve ce préfixe aux valeurs de la plateforme.
Modifier les personnes autorisées à l’utiliser ultérieurement :
beeuni secrets share DEEL_API_TOKEN --user me
beeuni secrets share DEEL_API_TOKEN --user finance@example.com --group <group-id>
beeuni secrets share NIGHTLY_REPORT_TOKEN --agent reporter
beeuni secrets share DEEL_API_TOKEN --everyoneOu utilisez le tableau de bord
Ouvrez la page Secrets du projet, saisissez la clé et la valeur, choisissez Qui peut l’utiliser et enregistrez. Beeuni chiffre immédiatement la valeur et définit par défaut chaque nouveau secret sur Tout le monde dans le projet et une exposition environnement — la vraie valeur est chargée dans le bac à sable. La colonne Qui peut l’utiliser indique le public de chaque valeur.
Pour passer un secret à une exposition avec contrôle de sortie réseau, activez d’abord l’indicateur de fonctionnalité secrets_egress (Settings → Feature flags) ; cette fonctionnalité est expérimentale. Une fois l’indicateur activé, la page Secrets affiche le contrôle « Votre code peut-il lire cette valeur ? » : répondre non fait passer le secret au contrôle de sortie réseau et affiche la liste des hôtes ; répondre oui conserve l’exposition environnement. Lorsque l’indicateur est désactivé, le secret reste en exposition environnement.
Accorder l’accès à un agent
Choisissez un agent sur la page Secrets ou ajoutez vous-même l’identifiant à la liste secrets de cet agent dans beeuni.yaml. Une session ne reçoit que les secrets accordés à son agent. Voir Accorder un secret à un
agent.
Accorder un secret à un agent
Une session ne reçoit un secret que si l’agent qui l’exécute indique l’identifiant dans sa liste secrets. La correspondance se fait avec l’identifiant, pas le nom, sans tenir compte de la casse.
Depuis le tableau de bord
La page Secrets signale les secrets qu’aucun agent ne peut recevoir : Aucun agent ne peut recevoir ce secret. Choisissez un agent et confirmez. Beeuni modifie beeuni.yaml et l’enregistre sous la forme chore(agents): grant <IDENTIFIER> to <agent>.
L’autorisation fonctionne que le manifeste déclare déjà l’agent ou non. Si l’agent n’est pas déclaré dans le manifeste, une nouvelle entrée contenant cette seule liste secrets est créée. Si l’agent est déjà déclaré, tous ses autres champs — modèle, outils, connecteurs — sont conservés, et l’identifiant est ajouté à sa liste existante. Si l’agent autorise déjà l’identifiant, aucun enregistrement n’est nécessaire et Beeuni n’en effectue pas.
Un agent sur secrets: all constitue un cas particulier. all ne peut pas contenir de secret avec contrôle de sortie réseau ; Beeuni crée donc une liste explicite comprenant tous les identifiants actuellement présents dans le projet, plus celui-ci. Rien ne change à ce que l’agent reçoit aujourd’hui. Tout secret ajouté ultérieurement devra faire l’objet de sa propre autorisation.
Deux cas empêchent l’autorisation :
- Un projet sur
beeuni_version: 1(beeuni.toml) n’a aucune map d’agents à modifier. La requête échoue avec400etmanifest_v1_unsupported. Modifiez le manifeste manuellement ou passez le projet àbeeuni_version: 2. - Un secret Désactivé ne peut rien fournir. La requête échoue avec
409etsecret_not_grantable. Définissez d’abord son exposition.
Si le projet ne contient pas encore de bloc agents:, lisez Le premier bloc agents: change tout le projet avant de confirmer.
Cette modification change l’accès aux secrets de tous les autres agents.
Manuellement
Voici la même autorisation, écrite directement :
beeuni_version: 2
agents:
my-agent:
secrets: [STRIPE_API_KEY]
Lorsqu’une session demande un secret non autorisé pour son agent
Un agent qui a besoin d’un identifiant crée un lien de secret (beeuni secrets request).
La valeur que vous saisissez est enregistrée même si l’agent de la session n’y est pas autorisé. Cette session ne la reçoit jamais ; Beeuni l’indique donc partout :
- Le formulaire du lien affiche Enregistré, mais
<agent>ne peut pas encore le lire et indique le secret. - La réponse de création et le message de suivi envoyé à la session énumèrent les noms
withheldainsi que la marche à suivre. - Dans la session,
beeuni secrets lsaffiche une clé déclarée mais non autorisée sous la formenot granted, et nonmissing.
L’agent ne peut pas étendre lui-même ses autorisations. Ouvrez Customize → Agents → <agent> → Secrets et activez le secret. Beeuni transmet la modification aux sessions en cours de l’agent lorsque vous l’enregistrez. L’agent peut aussi la récupérer immédiatement avec beeuni secrets sync, et chaque prompt resynchronise les secrets d’une session. Aucun redémarrage n’est nécessaire.
Le premier bloc agents: change tout le projet
Listez donc tous les agents qui ont besoin de secrets, pas seulement celui que vous corrigez. C’est pourquoi le tableau de bord vous demande de confirmer la première fois : après cet enregistrement, agents: constitue la liste d’autorisation du projet, et tout agent qui en est absent s’exécute sans aucun secret du projet.
Exposer des fonctionnalités à des utilisateurs tiers
Si vous créez un produit où des utilisateurs tiers non fiables peuvent accéder à une fonctionnalité — une interface de chat publique, une application partagée, un agent que n’importe qui sur Internet peut solliciter — ne leur donnez pas accès aux politiques de secrets. Tous les utilisateurs de cette interface partagent un seul agent de projet, une seule autorisation et une seule liste d’hôtes. Beeuni ne peut pas distinguer vos clients les uns des autres : un secret avec contrôle de sortie réseau accessible à partir du prompt de n’importe quel utilisateur est donc un identifiant que chaque utilisateur peut utiliser, dans toute la mesure permise par la clé en amont.
Mettez en place de votre côté la séparation dont vous avez réellement besoin :
- Déployez votre propre service d’autorisation et de proxy. Il détient l’identifiant en amont.
- Dirigez l’agent vers votre service, pas vers le service en amont. Donnez à l’agent uniquement un identifiant pour votre service — celui-ci peut être soumis au contrôle de sortie réseau vers votre propre hôte.
- Votre service identifie l’utilisateur final, applique vos propres règles d’autorisation et quotas par utilisateur, puis effectue l’appel en amont à l’aide de l’identifiant qu’il détient.
C’est dans ce service que doivent s’appliquer les règles par utilisateur : qui peut appeler quoi, à quelle fréquence et pour quels enregistrements. L’exposition des secrets Beeuni se situe une couche en dessous et ne la remplace pas.
Lister vos secrets
Exécutez beeuni secrets ls pour voir les secrets déclarés par un projet et ceux dont la valeur est définie.
La liste contient des métadonnées de configuration. Elle ne renvoie jamais les valeurs des secrets. Un jeton d’agent limité à un périmètre donné ne voit que les identifiants figurant dans les autorisations de cet agent. Un secrets_allowlist propre à une session contrôle la transmission des secrets à cette session, mais ne masque pas les métadonnées de configuration autorisées par les droits de l’agent.
Renouveler un secret
Définir une nouvelle valeur
Exécutez la même commande avec la nouvelle valeur ou définissez-la à nouveau sur la page Secrets du projet :
beeuni secrets set STRIPE_API_KEY=sk_live_new...Beeuni le transmet aux sessions en cours
Beeuni transmet la modification, dans la mesure du possible, à chaque sandbox qui a une session active pour le projet. Pour les identifiants du modèle ou de la passerelle, Beeuni redémarre le processus de compatibilité harness standard.
La rotation d’un secret soumis à un contrôle de sortie ne nécessite aucun transfert de sa valeur : la sandbox détient un identifiant, et Beeuni lit la valeur actuelle à la prochaine requête.
Supprimer un secret
Exécutez beeuni secrets unset STRIPE_API_KEY (ou unset <identifier>), ou
supprimez-le depuis la page Secrets du projet.
Partager une valeur sans la voir
Exécutez beeuni secrets request STRIPE_API_KEY pour créer un lien. Toute personne disposant du
lien peut saisir la valeur. Vous ne la voyez jamais. Par défaut, les liens restent valides pendant 7 jours ;
ajustez cette durée avec --expires <minutes> (30 jours maximum). Un lien expiré affiche
une page indiquant clairement qu’il a expiré : créez-en un nouveau avec la même commande.
Fournir directement une valeur à un agent
Si vous collez une clé dans une session, l’agent l’enregistre immédiatement avec
beeuni secrets set. Il ne vous envoie pas de lien. L’agent doit disposer de l’autorisation d’écriture des secrets du projet. Sans cette autorisation, l’agent reçoit
403 et crée plutôt un lien secret. Un agent peut enregistrer un secret d’environnement
ou un secret de connecteur (--scope connector). La livraison soumise à contrôle et les listes d’hôtes
restent réservées aux humains.
Exemple de bout en bout
beeuni.yaml :
beeuni_version: 2
default_agent: my-agent
agents:
my-agent:
secrets: [STRIPE_API_KEY]
Configuration des secrets. La première commande enregistre la valeur avec l’exposition par défaut
dans l’environnement. La deuxième la fait passer à une exposition soumise à un contrôle de sortie, fonctionnalité
expérimentale qui nécessite l’option secrets_egress (Settings → Feature flags) ; elle
renvoie 403 feature_disabled lorsque l’option est désactivée.
beeuni secrets set STRIPE_API_KEY=sk_live_...
beeuni secrets delivery STRIPE_API_KEY egress --allow-host api.stripe.com
L’agent appelle ensuite Stripe avec la variable qui lui a été fournie :
curl -s -o /dev/null -w '%{http_code}\n' \
-H "authorization: Bearer $STRIPE_API_KEY" \
https://api.stripe.com/v1/customers
# expected: 200
$STRIPE_API_KEY contient un identifiant. Stripe reçoit la vraie clé, car
api.stripe.com figure dans la liste. La même requête envoyée à un hôte qui ne figure pas dans la
liste transmet l’identifiant, que le serveur en amont rejette.
La même requête, effectuée par un agent dont la liste secrets ne contient pas STRIPE_API_KEY,
renvoie 401. La session démarre normalement : un secret non autorisé n’est pas une erreur,
il n’est tout simplement jamais transmis.
Commandes CLI
| Commande | Fonction |
|---|---|
beeuni secrets ls |
Répertorier les secrets déclarés et définis pour le projet |
beeuni secrets set KEY=VALUE [--identifier <id>] [--scope runtime|connector] |
Créer ou mettre à jour un secret. KEY=- lit la valeur depuis stdin. --scope connector la conserve côté serveur |
beeuni secrets unset IDENTIFIER |
Supprimer un secret |
beeuni secrets delivery IDENTIFIER egress --allow-host <host> |
Exposition soumise à un contrôle de sortie pour les hôtes indiqués. Fonctionnalité expérimentale ; nécessite l’option secrets_egress |
beeuni secrets delivery IDENTIFIER runtime |
Exposition dans l’environnement (par défaut) |
beeuni secrets delivery IDENTIFIER denied |
Désactivé |
beeuni secrets call IDENTIFIER URL |
Envoyer une requête HTTPS soumise à une politique via Beeuni. Fonctionnalité expérimentale ; nécessite l’option secrets_egress |
beeuni secrets sync |
Dans une session d’agent : récupérer les secrets de cette session et accorder l’accès maintenant. Pour une personne : renvoyer les secrets à toutes les sandboxes actives du projet |
beeuni secrets request NAME [--scope runtime|connector] [--expires <min>] |
Créer un lien permettant à quelqu’un d’autre de saisir une valeur |
beeuni env push --from <path> |
Importer un fichier .env sous forme de secrets |
beeuni env pull [--out <path>] [--force] |
Exporter les noms des secrets, et non leurs valeurs, dans un fichier .env |
La CLI conserve la terminologie enregistrée : runtime correspond à l’exposition dans l’environnement,
egress à l’exposition soumise à un contrôle de sortie, denied à l’exposition désactivée. Exécutez
beeuni secrets --help pour voir toutes les options.
Par défaut, les liens de configuration utilisent connector. Utilisez --scope runtime uniquement si le shell de l’agent
doit recevoir la valeur. Un secret associé à un connecteur reste côté serveur.
Noms et autorisations
Règles de format pour les deux noms :
| Nom | Format |
|---|---|
identifier |
^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$ |
name |
^[A-Z_][A-Z0-9_]{0,63}$ |
La lecture ou l’écriture d’un secret nécessite l’autorisation project.secret.read ou
project.secret.write. Un responsable de projet détient les deux. Un rôle personnalisé
ne peut qu’ajouter des autorisations — Beeuni ne prévoit aucune règle de refus — ; aucun rôle ne peut donc en retirer une à un responsable.
Pour restreindre un responsable, supprimez son rôle de responsable.
La livraison à une session dépend de la décision concernant le rôle de la personne qui l’a démarrée, combinée aux autorisations accordées dans le manifeste de l’agent lancé. Les deux doivent autoriser l’accès au secret. Voir Un vocabulaire, deux associations.
Routes REST
Toutes les routes se trouvent sous /v1/projects/{projectId}.
| Méthode | Chemin | Description |
|---|---|---|
| GET | /secrets |
Lister les secrets. Si l’appelant utilise un jeton d’agent à portée limitée, la liste est limitée aux secrets auxquels il a droit. |
| POST | /secrets |
Créer ou mettre à jour la valeur partagée. Corps : {name, identifier?, value}, avec une politique de livraison facultative. |
| PUT | /secrets/{identifier}/strategy |
Modifier l’exposition et la liste d’hôtes associée. |
| POST | /secrets/{identifier}/grant |
Ajouter l’identifiant à la liste secrets d’un agent dans beeuni.yaml. Corps : {agent}. |
| DELETE | /secrets/{name} |
Supprimer la valeur partagée. Les dérogations personnelles sont conservées. |
| PUT | /secrets/{name}/personal |
Définir ou activer la dérogation personnelle de l’appelant. |
| DELETE | /secrets/{name}/personal |
Supprimer la dérogation personnelle de l’appelant. |
POST /secrets rejette les noms commençant par BEEUNI_. Il renvoie 409
si le identifier existe déjà avec un name différent. Il rejette le nom exact CODEX_AUTH_JSON avec 400 — Beeuni gère ce secret
lors de la configuration de l’abonnement ChatGPT.
Les deux routes d’écriture renvoient un objet delivery_sync lorsque la modification devait être transmise
aux sandboxes en cours d’exécution. ok: false signifie que la valeur est enregistrée, mais qu’au moins une session active
utilise encore la précédente ; les sessions répertoriées la récupéreront au redémarrage.
Un secret dans la liste contient delivery_blocked_reason. La valeur
no_agent_grant signifie qu’aucun agent ne peut recevoir ce secret. null signifie qu’il est autorisé, que son exposition ne nécessite aucune autorisation ou que Beeuni n’a pas pu lire le manifeste.
POST /secrets/{identifier}/grant supprime cette raison. Il renvoie
already_granted: true si la liste de l’agent autorise déjà l’identifiant ; dans ce cas, Beeuni n’effectue aucune modification. Il renvoie adopted_governance: true lorsque
la modification ajoute le premier bloc agents: du projet — la modification décrite
ci-dessus. Pour un projet beeuni.toml, il renvoie 400 manifest_v1_unsupported,
et pour un secret désactivé, 409 secret_not_grantable.
Rotation et propagation
L’écriture d’un secret n’attend pas le redémarrage d’une session. Beeuni transmet la modification à chaque sandbox active du projet :
- Beeuni crée un nouvel instantané de l’environnement, en utilisant les autorisations
secretsde l’agent en cours d’exécution. - La sandbox écrit l’instantané dans l’environnement de l’agent actif. Les nouveaux appels d’outils prennent immédiatement en compte la modification.
- Si le secret modifié est un identifiant de fournisseur LLM, Beeuni redémarre harness standard.
Ce transfert est effectué dans la mesure du possible. L’appel API qui modifie le secret renvoie sa réponse avant la fin du transfert. Les échecs de transfert sont uniquement consignés et ne sont pas réessayés. Une sandbox dont le transfert a échoué conserve l’ancienne valeur jusqu’au prochain transfert réussi ou jusqu’au redémarrage de la session.
Identifiants de modèle
Un projet qui utilise l’accès aux modèles géré par Beeuni n’a pas besoin de sa propre clé. Pour utiliser vos propres clés, définissez les variables de fournisseur référencées par la configuration de fournisseur harness standard. Une clé de modèle reconnue se voit attribuer l’usage passerelle LLM, qui la consomme côté serveur ; elle n’a pas besoin d’être présente dans la sandbox.
N’utilisez pas le résultat générique d’une vérification du fournisseur comme preuve du fonctionnement à l’exécution. Il ne peut pas confirmer le modèle, la région, les droits d’accès et le dialecte API sélectionnés. Envoyez une véritable requête au modèle exact.