Applications

Créez, déployez et contrôlez les applications Beeuni depuis le SDK et depuis React.

Les Apps sont des déploiements rattachés à un projet, chacun doté d’une URL stable, avec des versions immuables, machines par groupe de processus et volumes persistants. Adaptez le comportement selon app.capabilities. Cette page couvre l’interface du SDK : la façade apps sur un handle de projet, les appels relatifs aux artefacts, versions, machines et volumes, les jetons de connexion, les types exportés et les hooks React.

Pour le modèle, la configuration des versions, les types de sources, la CLI, l’URL stable et le comportement de réveil à froid, consultez Apps.

const apps = beeuni.project(projectId).apps;

La façade apps

Les artefacts sont les entrées immuables d’un déploiement :

Les versions (déploiements) sont immuables et numérotées :

Machines, mise à l’échelle et exec (une App serveur ; une App sans machines répond 409 app_no_machines) :

Volumes (disques persistants) :

Jetons de connexion (capacité member_tokens ; 409 app_capability_unsupported si l’App ne l’a pas) :

L’accès est régi par la politique d’autorisation propre à l’App :

Déployer un site statique

uploadArchive effectue tout le protocole d’échange de l’artefact : il enregistre l’artefact, le vérifie par rapport à max_bytes, transfère les octets via PUT, calcule le SHA-256 et finalise.

const apps = beeuni.project(projectId).apps;

const app = await apps.create({ slug: 'docs', name: 'Docs' });
const artifact = await apps.artifacts.uploadArchive(tarGzBytes, {
  onProgress: (uploaded, total) => console.log(`${uploaded}/${total}`),
});

const deployment = await apps.deployments.create(app.app_id, {
  artifact_id: artifact.artifact_id,
  source: { kind: 'static', spa: true },
});

console.log(app.url, deployment.status); // https://…apps.beeuni.ai  queued

create accepte aussi les champs de machine : cpu, memory_gb, disk_gb, idle_timeout_seconds et always_on. Omettez-les pour utiliser les valeurs par défaut. Les Apps n’ont pas de budget mensuel : les crédits du compte paient le calcul. Une App serveur toujours active est facturée 24 h/24, 7 j/7 ; une App à la demande, uniquement lorsqu’elle est éveillée. always_on: true fait fonctionner une App serveur 24 h/24, 7 j/7 (websockets, boucles en arrière-plan) ; false l’arrête après idle_timeout_seconds et la réveille à la requête suivante. Une App statique n’a pas d’environnement d’exécution : always_on est false.

L’API ignore monthly_budget_usd si un ancien client l’envoie (200, aucune erreur). Aucune réponse d’App ne le contient.

uses liste, par slug, les Apps pour lesquelles cette App peut obtenir des jetons de connexion et qu’elle peut atteindre via son montage de liaisons ; par défaut, aucune, et update(appId, { uses }) remplace la liste (voir Apps utilisées par une App).

create et update renvoient warnings, qui vaut toujours [].

const app = await beeuni.project(projectId).apps.create({ slug: 'worker', name: 'Worker', always_on: true });
console.log(app.always_on, app.hosting_type); // true null (until the first deploy)

Attendez le déploiement en interrogeant régulièrement son état :

async function waitForReady(appId: string, deploymentId: string) {
  for (;;) {
    const { deployment } = await apps.deployments.get(appId, deploymentId);
    if (deployment.status === 'ready') return deployment;
    if (deployment.status === 'failed' || deployment.status === 'cancelled') {
      throw new Error(deployment.error ?? deployment.error_code ?? deployment.status);
    }
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
}

Les valeurs d’état sont queued, validating, building, provisioning, checking, ready, failed et cancelled.

Déployer une image OCI

Enregistrez la référence immuable de l’image, puis déclarez la commande du processus et le port cible public :

const registered = await apps.artifacts.register({
  kind: 'oci_image',
  image: 'ghcr.io/hekmat/service:2026-08-07',
});

await apps.deployments.create(app.app_id, {
  artifact_id: registered.artifact.artifact_id,
  source: {
    kind: 'oci_image',
    image: 'ghcr.io/hekmat/service:2026-08-07',
    command: ['node', 'server.js'],
    port: 3000,
    readiness_path: '/health',
  },
});

register renvoie upload: null pour un oci_image. Seul un archive reçoit une URL de téléversement.

CreateAppDeploymentInput accepte aussi environment (valeurs d’exécution non secrètes), secrets (clé d’exécution vers le nom du secret du projet) et config (AppReleaseConfigInput, la configuration de la version). Un config invalide répond 400 app_config_invalid avec issues: [{ path, message }] ; un montage sur un environnement d’exécution sans volumes répond 400 app_volumes_unsupported.

await apps.deployments.create(app.app_id, {
  artifact_id: registered.artifact.artifact_id,
  source: { kind: 'oci_image', image, command: ['node', 'server.js'] },
  config: {
    processes: { app: '', worker: 'node worker.js' },
    http_service: { internal_port: 3000, access: 'app', processes: ['app'] },
    mounts: [{ source: 'data', destination: '/data', initial_size_gb: 10, processes: ['app'] }],
    deploy: { release_command: 'node migrate.js' },
  },
});

Lire les journaux d’exécution

let cursor = 0;
for (;;) {
  const page = await apps.deployments.logs(app.app_id, deployment.deployment_id, {
    after: cursor,
    limit: 200,
  });
  for (const entry of page.entries) console.log(entry.source, entry.line);
  cursor = page.next_cursor;
  if (page.entries.length === 0) break;
}

Chaque entrée contient cursor, time, source (app, appd, caddy) et line. Une ligne caddy constitue le journal d’accès : méthode, URI, statut, durée et en-têtes de réponse. Elle ne contient jamais les en-têtes de requête, car ceux-ci contiennent les identifiants de la passerelle (le jeton et l’identité du visiteur, le jeton d’entrée du fournisseur).

Machines, mise à l’échelle et volumes

const apps = beeuni.project(projectId).apps;

const machines = await apps.machines.list(app.app_id);
await apps.scale(app.app_id, { worker: 3 });                     // 202: applied in the background

const { exit_code, stdout } = await apps.exec(app.app_id, { command: ['ls', '/data'] });

const [data] = await apps.volumes.list(app.app_id);
const snapshot = await apps.volumes.snapshot(app.app_id, data.volume_id);
await apps.volumes.restore(app.app_id, data.volume_id, snapshot.snapshot_id);   // project.app.admin
const copy = await apps.volumes.fork(app.app_id, data.volume_id, { name: 'data_copy' });

Une machine conserve son machine_id d’une version à l’autre ; chaque version remplace son box (instance_id). Une machine monte un seul volume à la fois. Une restauration crée une nouvelle version du volume : le contenu remplacé reste dans son historique. Un instantané d’un volume monté peut omettre sa dernière seconde d’écritures environ.

Un backend Convex

Un backend Convex est une App serveur ordinaire avec un volume, créée à partir du modèle convex (beeuni apps launch --template convex --name db ; voir Modèle convex). Le SDK ne propose aucun appel spécifique à Convex. Lisez la clé d’administration sur la machine avec exec, et donnez à une App d’interface accès au backend avec uses :

const db = (await apps.list()).find((a) => a.slug === 'db')!;
const { stdout } = await apps.exec(db.app_id, { command: ['sh', '-c', 'cd /convex && ./generate_admin_key.sh'] });
// The admin key controls all code and data: never log it or ship it to a browser.

await apps.update(site.app_id, { uses: ['db'] }); // the site may mint db tokens and bind to it

db.services contient les URL du backend : http (l’URL du client Convex) et site (actions HTTP).

Votre App sait déjà qui la consulte

Une App hébergée par Beeuni est ouverte par une personne déjà connectée à Beeuni. La passerelle des Apps l’authentifie avant que votre premier octet soit servi ; votre App n’a donc pas besoin de sa propre connexion — ni second mot de passe, ni écran de consentement, ni redirection.

Dans le navigateur :

import { createBeeuni, beeuniAppViewerToken } from '@beeuni/sdk';
import { useBeeuniAppViewer } from '@beeuni/sdk/react';

const beeuni = createBeeuni({
  backendUrl: '/_beeuni/api/v1',             // the gate, on your App's own origin
  getToken: beeuniAppViewerToken(),          // the viewer's own App-scoped token
});

function Header() {
  const { status, viewer } = useBeeuniAppViewer();
  return <span>{status === 'viewer' ? viewer.email : 'Signed out'}</span>;
}

Le navigateur appelle /_beeuni/api/v1/* sur l’origine de votre App, jamais https://api.beeuni.ai/v1 directement : l’API ne répond à aucune requête préliminaire CORS provenant d’une origine d’App, donc un appel direct échoue dans le navigateur. La passerelle transmet chaque appel à l’API Beeuni au nom du visiteur connecté, avec le jeton du visiteur limité à l’App. Règles :

• viewer_token_scope: 'api' est nécessaire. Sinon, elle répond 403 viewer_api_disabled.
• Elle agit uniquement pour un visiteur connecté par la passerelle (connexion Beeuni ou lien d’accès). En l’absence de visiteur, elle répond 401 no_viewer_identity.
• Elle répond uniquement aux requêtes provenant de l’origine de l’App. Une requête intersite reçoit 403 cross_site_request.
• Elle transmet /v1/* sauf /v1/oauth/* et les points de terminaison MCP, qui répondent 404. Le cookie de votre App et son propre en-tête Authorization n’atteignent jamais l’API, et l’API ne peut pas définir de cookie sur votre App.

Sur le serveur de votre App, la passerelle inclut l’identité signée dans chaque requête :

import { readAppViewer, createAppViewerBeeuni } from '@beeuni/sdk/server';

const viewer = await readAppViewer(request);
// { userId, email, name, picture, groupIds, groups, role, projectId, accountId, appId, accessMode, token }
if (!viewer) return new Response('Not found', { status: 404 });

// and, for an `api`-scoped App, act as them:
const beeuni = await createAppViewerBeeuni(request, { backendUrl });
await beeuni.projects.list();               // their projects, their role

readAppViewer vérifie un HMAC de l’en-tête avec BEEUNI_APP_VIEWER_SECRET, que Beeuni injecte dans votre App au déploiement. Un en-tête falsifié ne passe jamais : la passerelle supprime toute copie fournie par le client avant de transmettre la requête, et la signature est créée avec un secret dérivé pour chaque App.

Les informations communiquées à votre App

Un paramètre de la politique d’accès de l’App — Settings → Access dans Beeuni, beeuni apps access <app> --viewer off|identity|api, ou viewer_token_scope sur PATCH /projects/:id/apps/:appId/access :

Le jeton n’est jamais la session Beeuni de l’utilisateur : il dure une heure, ne possède que ces portées, et chaque jeton créé par une App expire lorsque l’App est supprimée ou que sa politique d’accès change.

Utiliser le jeton du visiteur

• Sur votre serveur, lisez-le à chaque requête. La passerelle place un jeton valide dans x-beeuni-app-viewer-token sur chaque requête transmise par proxy. Envoyez-le sous la forme Authorization: Bearer à l’API Beeuni — createAppViewerBeeuni(request) fait exactement cela. Créez un client par requête ; ne stockez pas le jeton.
• Après une modification de la politique d’accès, les anciens jetons cessent de fonctionner. La requête suivante passant par la passerelle en contient un nouveau. Dans le navigateur, beeuniAppViewerToken() se rétablit automatiquement : lorsque l’API refuse son jeton, le SDK relit /_beeuni/viewer et rejoue l’appel une fois.
• Le rôle du visiteur constitue la limite maximale. Le jeton peut faire exactement ce que le visiteur peut faire dans Beeuni, jamais plus. Sur un projet avec des autorisations d’agent, un member a besoin d’une autorisation sur l’agent que votre App démarre : sans celle-ci, POST /projects/:id/sessions répond 403 no_agent_access. Accordez à vos visiteurs l’accès à l’agent, pas un rôle plus étendu.
• Qui dispose d’une identité de visiteur. Une personne qui ouvre l’App avec sa connexion Beeuni — ou avec un lien d’accès, qui la connecte sous cette identité — en dispose. Une App password n’en a pas : le mot de passe prouve la connaissance d’un secret partagé, pas une identité. Une App public n’en a une que pour un visiteur arrivé par un lien d’accès ; l’URL seule reste anonyme.
• C’est un identifiant d’authentification. Beeuni exclut les en-têtes de requête du journal d’accès de l’App (beeuni apps logs). Ne consignez pas cet en-tête dans votre propre code.

Une App servie sur son propre domaine (et non *.apps.beeuni.ai) n’a pas de passerelle devant elle — utilisez plutôt Se connecter avec Beeuni.

Un même membre, dans tous les environnements d’exécution

Beeuni atteste l’identité de la même personne à trois endroits : le navigateur interroge la passerelle (/_beeuni/viewer), le serveur de l’App lit l’en-tête signé, et une App qui vérifie les jetons de connexion (un backend Convex ou votre propre serveur) reçoit un jeton signé par Beeuni. readBeeuniMember convertit chacun de ces formats en un BeeuniMember, et requireBeeuniMember décide qui peut continuer. Aucun framework ni dépendance : le même code s’exécute dans un navigateur, Node, Bun, un Worker et une fonction Convex.

import {
  readBeeuniMember, requireBeeuniMember, verifyBeeuniToken,
  beeuniToken, beeuniBinding, fetchBeeuniAppViewer, BeeuniMemberError,
} from '@beeuni/sdk';

// Browser: who is looking (null when nobody).
const me = readBeeuniMember(await fetchBeeuniAppViewer());

// Browser → an App this App uses, on the same origin: its URL and a token fetcher.
const db = beeuniBinding('db');
const convex = new ConvexReactClient(db.url);
convex.setAuth(db.token);
// React: read the member with useQuery(api.members.me), never useConvexAuth() (see below).

// Browser: a token for this App itself, or for an App it uses.
const token = await beeuniToken()();
const dbToken = beeuniToken({ audience: 'db' });

// A Convex function: the runtime verified the token; enforce the rules.
const member = requireBeeuniMember(await ctx.auth.getUserIdentity(), { groups: ['Finance'] });

// A server App: verify the bearer. No options = the BEEUNI_AUTH_* env Beeuni injects.
// Any other server: pass the App's `auth` values.
const caller = await verifyBeeuniToken(bearer, { issuer: app.auth.issuer, audience: app.auth.audience, jwks: app.auth.jwks_uri });

Dans React, n’appelez pas useConvexAuth() : il lève une exception avec un simple ConvexProvider (il nécessite ConvexProviderWithAuth, et beeuniBinding n’est pas vérifié avec ce fournisseur). Récupérez le membre connecté avec une requête :

// convex/members.ts
export const me = query({ args: {}, handler: async (ctx) => readBeeuniMember(await ctx.auth.getUserIdentity()) });

const me = useQuery(api.members.me);   // undefined: loading. null: signed out. Otherwise the member.

readBeeuniMember renvoie null pour un appelant anonyme. Utilisez requireBeeuniMember uniquement lorsque la fonction doit lever une exception.

requireBeeuniMember(claims, { groups, roles }) renvoie le membre ou lève BeeuniMemberError avec code unauthenticated (personne, ou un jeton qui n’a pas passé une vérification) ou forbidden (hors des groupes ou des rôles). Chaque liste signifie « au moins un de ces éléments » ; un groupe correspond par son nom ou son identifiant ; une liste vide n’admet personne.

Jetons de connexion

Un émetteur par projet signe les jetons de chaque App : iss = <API origin>/v1/projects/<projectId>, aud = l’identifiant de l’App à laquelle le jeton est destiné, 15 minutes. Son jeu de clés est public à l’adresse <issuer>/jwks.json, identifié par <issuer>/.well-known/openid-configuration. Chaque App contient les valeurs qui vérifient ses jetons : app.auth.issuer, app.auth.audience, app.auth.jwks_uri. Un jeton contient sub, email, name, picture, groups, group_ids, role, account_id et project_id ; le jeton d’un agent contient kind: 'agent' et aucun groupe ni rôle.

Un membre que vous retirez du projet ou d’un groupe perd son accès au plus tard à l’expiration d’un jeton ; le contrôle d’accès de l’App le refuse au prochain chargement de page. Les groupes Beeuni nécessitent l’offre Enterprise ; les rôles fonctionnent avec toutes les offres.

Gérer l’accès

await apps.access.update(app.app_id, {
  mode: 'restricted',
  member_ids: [memberId],
  group_ids: [groupId],
});

const preview = await apps.access.session(app.app_id);
window.open(preview.url); // valid for five minutes

AppAccessConfig indique password_configured, jamais le mot de passe ni son hachage. Définissez un mot de passe avec { mode: 'password', password }. Chaque mise à jour incrémente revision, ce qui révoque les cookies d’App existants.

Types

Tous les types ci-dessous sont exportés depuis @beeuni/sdk.

apps.list() et useProjectApps renvoient uniquement les Apps que l’appelant peut ouvrir selon la politique d’accès de chaque App (privée : le créateur ; restreinte : les membres et groupes répertoriés ; projet, mot de passe et publique : l’équipe du projet). Un gestionnaire de projet voit toutes les Apps, ce qui permet de continuer à gérer une App privée après le départ de son créateur. viewer_can_access vaut donc true pour chaque App répertoriée. Un get d’une App que l’appelant ne peut pas ouvrir renvoie 404, et non 403. Traitez undefined comme inconnu, et non comme refusé.

AppAccessMode est un paramètre de visibilité par ressource qui s’ajoute au modèle de rôles, pas un rôle. restricted désigne des utilisateurs et des groupes — les mêmes types de principaux que ceux utilisés par le modèle de rôles. Voir Comptes et accès.

DockerfileAppSource et OciImageAppSource nécessitent command. port est le port du service principal : ne l’omettez que pour une version composée uniquement de workers (un config avec processes et sans service). StaticAppSource et BundleAppSource n’acceptent ni l’un ni l’autre.

Hooks React

@beeuni/sdk/react exporte sept hooks pour les Apps.

useProjectApps(projectId)

Les Apps que l’appelant peut ouvrir, ainsi que leurs mutations de cycle de vie. Chaque mutation invalide l’inventaire en cas de succès.

import { useProjectApps } from '@beeuni/sdk/react';

function AppList({ projectId }: { projectId: string }) {
  const apps = useProjectApps(projectId);
  if (!apps.data) return null;

  return (
    <ul>
      {apps.data.map((app) => (
        <li key={app.app_id}>
          <a href={app.url}>{app.slug}</a>
          <button onClick={() => apps.stop.mutate(app.app_id)}>Stop</button>
        </li>
      ))}
    </ul>
  );
}

Il renvoie les champs de la requête ainsi que create, update, start, stop et remove.

useAppDeployments(projectId, appId)

L’historique immuable des déploiements, récupéré à nouveau toutes les 5 s pour qu’un build en cours progresse automatiquement.

const deployments = useAppDeployments(projectId, appId);

await deployments.deploy.mutateAsync({
  artifact_id: artifact.artifact_id,
  source: { kind: 'static', spa: true },
});
await deployments.rollback.mutateAsync(previousDeploymentId);

Les deux mutations invalident la liste des déploiements et l’inventaire des Apps.

useAppDeployment(projectId, appId, deploymentId)

Un déploiement et ses événements, journal de build inclus (AppDeploymentDetail). Il effectue une interrogation toutes les 2 s jusqu’à ce que le déploiement soit ready, failed ou cancelled. Passez null comme deploymentId pour le laisser inactif.

const detail = useAppDeployment(projectId, appId, deploymentId);
const log = (detail.data?.events ?? [])
  .map((event) => (event.type === 'build_log' ? event.message : `[${event.type}] ${event.message}`))
  .join('\n');

Un build conserve ses 2 500 premières et ses 2 500 dernières lignes. Les lignes sont écrites par lots, au plus tard 1 s après leur affichage. Un déploiement échoué ou annulé conserve son journal de build pendant 14 jours.

useAppAccess(projectId, appId, options?)

La politique d’accès et une session d’accès de courte durée. Les deux parties sont des requêtes distinctes, chacune étant facultative.

const access = useAppAccess(projectId, appId, {
  policy: canEditAccess,
  session: app.viewer_can_access,
});

access.policy.data;  // AppAccessConfig
access.session.data; // { url, expires_at }
await access.update.mutateAsync({ mode: 'project' });

Une grille d’Apps qui laisse les deux options à true déclenche une lecture de politique et une création de session par App, chacune renvoyant 403 pour un membre qui n’est pas autorisé à ouvrir cette App.

useAppMachines(projectId, appId)

Les machines d’une App, interrogées toutes les 5 s, ainsi que start, stop, restart, destroy (chacun prend un machineId) et scale (prend { [group]: count }). Chaque mutation actualise les machines et l’inventaire des Apps. appMachinesKey(projectId, appId) est la clé de requête.

const machines = useAppMachines(projectId, app.app_id);
await machines.scale.mutateAsync({ worker: 2 });
await machines.restart.mutateAsync(machineId);

useAppVolumes(projectId, appId)

Les volumes d’une App, ainsi que snapshot (volumeId), restore ({ volumeId, snapshotId }), fork ({ volumeId, name, snapshotId? }), extend ({ volumeId, sizeGb }) et destroy ({ volumeId, name }). Chaque mutation actualise les volumes. appVolumesKey(projectId, appId) est la clé de requête.

const volumes = useAppVolumes(projectId, app.app_id);
await volumes.snapshot.mutateAsync(volumeId);
await volumes.restore.mutateAsync({ volumeId, snapshotId });

useAppVolumeSnapshots(projectId, appId, volumeId)

Les instantanés d’un volume. Passez null comme volumeId pour laisser la requête inactive.

Erreurs

import { featureDisabledKey, isFeatureDisabledError } from '@beeuni/sdk';

try {
  await beeuni.project(projectId).apps.list();
} catch (error) {
  if (isFeatureDisabledError(error)) {
    console.log(`${featureDisabledKey(error)} is off for this project`);
  }
}

Autres réponses à gérer :

• 409 pour un slug en double, 402 avec app_quota_exceeded lorsque le compte a atteint sa limite d’Apps, et 400 avec app_machine_out_of_range pour une spécification hors limites.
• 400 app_not_found (slugs) pour un slug inconnu dans uses.
• 409 app_capability_unsupported (capability) pour un appel que l’App ne propose pas.
• Un déploiement : 400 app_config_invalid (issues), 400 app_volumes_unsupported. Un retour à une version précédente : 409 release_not_ready.
• Machines et exec : 409 app_no_machines, 404 machine_not_found, 409 machine_not_running, 400 process_group_unknown, 400 scale_out_of_range, 400 command_required.
• Volumes : 400 volume_name_invalid, volume_size_invalid, volume_shrink_refused, volume_retention_invalid, snapshot_invalid, confirmation_required ; 404 volume_not_found ; 409 volume_attached.

token() répond avec Cache-Control: no-store.