App

Crea, distribuisci e controlla le app Beeuni dall'SDK e da React.

Le App sono distribuzioni limitate al progetto, ciascuna con un URL stabile, release immutabili, macchine per gruppo di processi e volumi persistenti. Usa app.capabilities per scegliere il ramo. Questa pagina descrive l’interfaccia dell’SDK: la facade apps su un handle di progetto, le chiamate per artefatti, release, macchine e volumi, i token di accesso, i tipi esportati e gli hook React.

Per il modello, la configurazione delle release, i tipi di sorgente, la CLI, l’URL stabile e il comportamento di riattivazione a freddo, leggi Apps.

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

La facade apps

Gli artefatti sono l’input immutabile di una distribuzione:

Le release (distribuzioni) sono immutabili e numerate:

Macchine, scalabilità ed exec (un’App server; un’App senza macchine risponde 409 app_no_machines):

Volumi (dischi persistenti):

Token di accesso (funzionalità member_tokens; 409 app_capability_unsupported quando l’App non la possiede):

L’accesso è la policy di autorizzazione propria dell’App:

Distribuire un sito statico

uploadArchive esegue l’intero handshake dell’artefatto: registra l’artefatto, lo verifica rispetto a max_bytes, invia i byte con PUT, calcola lo SHA-256 e finalizza.

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 accetta anche i campi della macchina: cpu, memory_gb, disk_gb, idle_timeout_seconds e always_on. Omettili per usare i valori predefiniti. Le App non hanno un budget mensile: i crediti dell’account pagano il calcolo. Un’App server sempre attiva viene fatturata 24/7; una on-demand solo mentre è attiva. always_on: true esegue un’App server 24/7 (websocket, loop in background); false la arresta dopo idle_timeout_seconds e la riattiva alla richiesta successiva. Un’App statica non ha un runtime: always_on è false.

L’API ignora monthly_budget_usd se un client meno recente lo invia (200, nessun errore). Nessuna risposta dell’App lo include.

uses elenca, per slug, le App per cui questa App può ottenere token di accesso e che può raggiungere tramite il suo mount dei binding; per impostazione predefinita non ce ne sono e update(appId, { uses }) sostituisce l’elenco (vedi App usate da un’App).

create e update restituiscono warnings, che è sempre [].

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)

Attendi la distribuzione interrogandone periodicamente lo stato:

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));
  }
}

I valori di stato sono queued, validating, building, provisioning, checking, ready, failed e cancelled.

Distribuire un’immagine OCI

Registra il riferimento immutabile dell’immagine, poi dichiara il comando del processo e la porta di destinazione pubblica:

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 restituisce upload: null per un oci_image. Solo un archive ottiene un URL di caricamento.

CreateAppDeploymentInput accetta anche environment (valori del runtime non segreti), secrets (chiave del runtime associata al nome del segreto del progetto) e config (AppReleaseConfigInput, la configurazione della release). Un config non valido risponde 400 app_config_invalid con issues: [{ path, message }]; un mount su un runtime senza volumi risponde 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' },
  },
});

Leggere i log del runtime

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;
}

Ogni voce contiene cursor, time, source (app, appd, caddy) e line. Una riga caddy è il log degli accessi: metodo, URI, stato, durata e header della risposta. Non contiene mai gli header della richiesta, perché contengono le credenziali del gateway (il token e l’identità del visitatore, il token di ingresso del provider).

Macchine, scalabilità e volumi

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' });

Una macchina mantiene il proprio machine_id tra una release e l’altra; ogni release sostituisce il suo box (instance_id). Una macchina monta un volume alla volta. Un ripristino crea una nuova versione del volume: i contenuti sostituiti restano nella sua cronologia. Uno snapshot di un volume montato può non includere l’ultimo secondo circa di scritture.

Un backend Convex

Un backend Convex è una normale App server con un volume, creata dal template convex (beeuni apps launch --template convex --name db; vedi Template convex). L’SDK non ha chiamate specifiche per Convex. Leggi la chiave amministratore dalla macchina con exec e concedi a un’App UI l’accesso al backend con 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 contiene gli URL del backend: http (l’URL del client Convex) e site (azioni HTTP).

La tua App sa già chi la sta guardando

Un’App ospitata da Beeuni viene aperta da qualcuno che Beeuni ha già autenticato. Il gateway delle App lo autentica prima che venga servito il primo byte, quindi la tua App non ha bisogno di un proprio login: nessuna seconda password, nessuna schermata di consenso, nessun reindirizzamento.

Nel browser:

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>;
}

Il browser chiama /_beeuni/api/v1/* sull’origine della tua App, mai https://api.beeuni.ai/v1 direttamente: l’API non risponde alle richieste preliminari CORS provenienti dall’origine di un’App, quindi una chiamata diretta fallisce nel browser. Il gateway inoltra ogni chiamata all’API Beeuni come visitatore autenticato, con il token del visitatore limitato all’App. Regole:

• Richiede viewer_token_scope: 'api'. Altrimenti risponde 403 viewer_api_disabled.
• Agisce solo per un visitatore autenticato dal gateway (login Beeuni o un link di accesso). In assenza di un visitatore, risponde 401 no_viewer_identity.
• Risponde solo a richieste provenienti dall’origine dell’App. A una richiesta cross-site risponde 403 cross_site_request.
• Inoltra /v1/* tranne /v1/oauth/* e gli endpoint MCP, che rispondono 404. Il cookie della tua App e il suo header Authorization non raggiungono mai l’API, e l’API non può impostare un cookie sulla tua App.

Sul server della tua App, il gateway inserisce l’identità firmata in ogni richiesta:

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 verifica un HMAC sull’header con BEEUNI_APP_VIEWER_SECRET, che Beeuni inserisce nella tua App al momento del deploy. Un header contraffatto non supera mai la verifica: il gateway elimina qualsiasi copia fornita dal client prima dell’inoltro, e la firma viene creata con un segreto derivato per ogni App.

Quali informazioni riceve la tua App

Un’impostazione nella policy di accesso dell’App: Settings → Access in Beeuni, beeuni apps access <app> --viewer off|identity|api, oppure viewer_token_scope su PATCH /projects/:id/apps/:appId/access:

Il token non è mai la sessione Beeuni dell’utente: dura un’ora, include solo quegli ambiti e ogni token emesso da un’App viene invalidato quando l’App viene eliminata o la sua policy di accesso cambia.

Uso del token del visitatore

• Sul tuo server, leggilo a ogni richiesta. Il gateway inserisce un token valido in x-beeuni-app-viewer-token in ogni richiesta inoltrata tramite proxy. Invialo come Authorization: Bearer all’API Beeuni: createAppViewerBeeuni(request) fa esattamente questo. Crea un client per ogni richiesta; non memorizzare il token.
• Dopo una modifica alla policy di accesso, i vecchi token smettono di funzionare. La richiesta successiva attraverso il gateway ne contiene uno nuovo. Nel browser, beeuniAppViewerToken() si ripristina automaticamente: quando l’API rifiuta il suo token, l’SDK rilegge /_beeuni/viewer e ripete la chiamata una volta.
• Il ruolo del visitatore è il limite massimo. Il token può fare esattamente ciò che il visitatore può fare in Beeuni, mai di più. In un progetto con autorizzazioni per gli agenti, un member necessita di un’autorizzazione per l’agente avviato dalla tua App: senza, POST /projects/:id/sessions risponde 403 no_agent_access. Concedi ai tuoi visitatori l’accesso all’agente, non un ruolo più ampio.
• Quando è presente un visitatore. È presente quando una persona apre l’App con il proprio login Beeuni, oppure con un link di accesso, che la autentica come quella persona. Un’App password non ne ha: la password dimostra la conoscenza di un segreto condiviso, non l’identità di una persona. Un’App public ne ha uno solo se il visitatore arriva tramite un link di accesso; il semplice URL resta anonimo.
• È una credenziale. Beeuni esclude gli header delle richieste dal log degli accessi dell’App (beeuni apps logs). Non registrare l’header nei log del tuo codice.

Un’App servita sul proprio dominio (non *.apps.beeuni.ai) non ha un gateway davanti: usa invece Accedi con Beeuni.

Un solo membro, in ogni runtime

Beeuni garantisce l’identità della stessa persona in tre contesti: il browser interroga il gateway (/_beeuni/viewer), il server dell’App legge l’header firmato e un’App che verifica i token di autenticazione (un backend Convex o il tuo server) riceve un token firmato da Beeuni. readBeeuniMember converte ciascuna di queste forme in un unico BeeuniMember, e requireBeeuniMember decide chi può procedere. Nessun framework e nessuna dipendenza: lo stesso codice funziona in un browser, Node, Bun, un Worker e una funzione 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 });

In React, non chiamare useConvexAuth(): genera un’eccezione con un semplice ConvexProvider (richiede ConvexProviderWithAuth e beeuniBinding non viene verificato con quel provider). Leggi il membro autenticato con una query:

// 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 restituisce null per un chiamante anonimo. Usa requireBeeuniMember solo dove la funzione deve generare un’eccezione.

requireBeeuniMember(claims, { groups, roles }) restituisce il membro oppure genera BeeuniMemberError con code unauthenticated (nessuno, oppure un token che non ha superato una verifica) o forbidden (al di fuori dei gruppi o dei ruoli). Ogni elenco significa “uno qualsiasi di questi”; un gruppo corrisponde per nome o id; un elenco vuoto non ammette nessuno.

Token di autenticazione

Un unico emittente per progetto firma i token di ogni App: iss = <API origin>/v1/projects/<projectId>, aud = l’id dell’App a cui il token è destinato, 15 minuti. Il suo set di chiavi è pubblico su <issuer>/jwks.json, identificato da <issuer>/.well-known/openid-configuration. Ogni App contiene i valori che verificano i suoi token: app.auth.issuer, app.auth.audience, app.auth.jwks_uri. Un token contiene sub, email, name, picture, groups, group_ids, role, account_id e project_id; il token di un agente contiene kind: 'agent' e nessun gruppo o ruolo.

Un membro rimosso dal progetto o da un gruppo perde l’accesso entro la durata di un token; il controllo di accesso dell’App lo respinge al successivo caricamento della pagina. I gruppi Beeuni richiedono il piano Enterprise; i ruoli funzionano con tutti i piani.

Gestire l’accesso

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 riporta password_configured, mai la password o il suo hash. Imposta una password con { mode: 'password', password }. Ogni aggiornamento incrementa revision, revocando i cookie dell’App esistenti.

Tipi

Ogni tipo qui sotto viene esportato da @beeuni/sdk.

apps.list() e useProjectApps restituiscono solo le App che il chiamante può aprire in base alla policy di accesso di ciascuna App (privata: il creatore; limitata: i membri e i gruppi elencati; progetto, password e pubblica: il team del progetto). Un responsabile del progetto vede tutte le App, quindi un’App privata resta gestibile quando il suo creatore lascia il progetto. viewer_can_access è quindi true per ogni App elencata. Un get di un’App che il chiamante non può aprire risponde 404, non 403. Considera undefined come sconosciuto, non come negato.

AppAccessMode è un’impostazione di visibilità per risorsa che si aggiunge al modello dei ruoli, non un ruolo. restricted identifica utenti e gruppi, gli stessi tipi di entità usati dal modello dei ruoli. Vedi Account e accesso.

DockerfileAppSource e OciImageAppSource richiedono command. port è la porta del servizio principale: omettila solo per una release con soli worker (un config con processes e nessun servizio). StaticAppSource e BundleAppSource non accettano nessuno dei due.

Hook React

@beeuni/sdk/react esporta sette hook per le App.

useProjectApps(projectId)

Le App che il chiamante può aprire, più le relative mutazioni del ciclo di vita. Ogni mutazione invalida l’inventario in caso di successo.

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>
  );
}

Restituisce i campi della query più create, update, start, stop e remove.

useAppDeployments(projectId, appId)

La cronologia immutabile dei deployment, recuperata di nuovo ogni 5 s affinché una build in esecuzione avanzi autonomamente.

const deployments = useAppDeployments(projectId, appId);

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

Entrambe le mutazioni invalidano l’elenco dei deployment e l’inventario delle App.

useAppDeployment(projectId, appId, deploymentId)

Un deployment e i suoi eventi, incluso il log di build (AppDeploymentDetail). Esegue il polling ogni 2 s finché il deployment non è ready, failed o cancelled. Passa null come deploymentId per mantenerlo inattivo.

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');

Una build conserva le prime 2.500 e le ultime 2.500 righe. Le righe vengono scritte in batch, al massimo 1 s dopo essere state stampate. Un deployment non riuscito o annullato conserva il log della build per 14 giorni.

useAppAccess(projectId, appId, options?)

La policy di accesso e una sessione di accesso di breve durata. Le due parti sono query separate e ciascuna è facoltativa.

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' });

Una griglia di App che lascia entrambe le opzioni su true esegue una lettura della policy e una creazione di sessione per ogni App, e ciascuna restituisce 403 per un membro che non può aprire quell’App.

useAppMachines(projectId, appId)

Le macchine di un’App, interrogate ogni 5 s, più start, stop, restart, destroy (ciascuna accetta un machineId) e scale (accetta { [group]: count }). Ogni mutazione aggiorna le macchine e l’inventario delle App. appMachinesKey(projectId, appId) è la chiave della query.

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

useAppVolumes(projectId, appId)

I volumi di un’App, più snapshot (volumeId), restore ({ volumeId, snapshotId }), fork ({ volumeId, name, snapshotId? }), extend ({ volumeId, sizeGb }) e destroy ({ volumeId, name }). Ogni mutazione aggiorna i volumi. appVolumesKey(projectId, appId) è la chiave della query.

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

useAppVolumeSnapshots(projectId, appId, volumeId)

Gli snapshot di un volume. Passa null come volumeId per mantenerla inattiva.

Errori

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`);
  }
}

Altre risposte da gestire:

• 409 per uno slug duplicato, 402 con app_quota_exceeded quando l’account ha raggiunto il limite di App e 400 con app_machine_out_of_range per una specifica fuori dai limiti consentiti.
• 400 app_not_found (slugs) per uno slug sconosciuto in uses.
• 409 app_capability_unsupported (capability) per una chiamata che l’App non offre.
• Un deployment: 400 app_config_invalid (issues), 400 app_volumes_unsupported. Un rollback: 409 release_not_ready.
• Macchine ed 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.
• Volumi: 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() risponde con Cache-Control: no-store.