Writing apps for a cluster
An app is a calimero:app component, built with the Rust SDK
(calimero-sdk) and run on wasmtime. Build covers writing one;
this page covers what it sees once it runs on a cluster. A WASM core module (an
SDK 0.12 app, which ran on wasmer) is refused: 400 UNSUPPORTED_BUNDLE at upload,
create and install, and 410 UNSUPPORTED_ENGINE for every call, view and upgrade
of one a node’s data still holds; such an app can still be listed and deleted.
On a cluster
Section titled “On a cluster”- Packages. Install a signed
.mpkbypackage@versionfrom the operator’s registry (POST /packages/install,meroctl app install PACKAGE@VERSION); a file (POST /packages) only on a development cluster. Every node that runs a release fetches it and checks the publisher’s signature, the artifact digests and the hash the fleet recorded; a package keeps the publisher key of its first release. Create an instance withPOST /apps { package, version }, upgrade with{ version }, and delete withDELETE /apps/{app}. Raw WASM uploads (POST /bundles) are for development clusters only too. - Instances. An app instance (
meroctl instance) is created withPOST /apps { name, bundle, initArgs, org?, access? }(or{ name, package, version }). Every instance is in an organization, as its release’sinstanceOrgsays: naming none puts it in the creator’s only organization, or a new one made with it (Where an instance goes;meroctl instance createwithout--org).initArgs(JSON) is what#[app::init]receives; a failed init answers422 INIT_FAILEDinstead of leaving a dead instance. - Identity.
env::caller()is the caller: an account, an API key (with its account), another app, or the system. There are no per-app identities or keys: each passkey on an account is one of the person’s devices (POST /auth/passkeys/add/*, and/auth/menames the session’spasskeyId). - Organizations.
env::org_role(account)is that account’s role in the app’s organization (Guest < Member < Admin < Owner) andenv::in_team(account, team)whether they are in a team. The node already keeps non-members out of an organization’s apps; these are for rules inside the app.apps/team-spacein core is a complete example. - Teams. A team is open (whoever reaches its parent, or
the organization at the top, is a member) or restricted (its members only),
nests and moves, keeps the app’s metadata (a folder’s name and colour), and
each member’s row has a role — lead, member or read-only — and
capability bits. Deploy an app to a team with
grants: [{ kind: "team", team }]: its members reach it, and a read-only member reaches its views only, other calls being refused (403). A team they neither reach nor manage is invisible to them. Deleting a team deletes the teams and apps below it. - Blobs and files. A blob belongs to the app that holds it (
POST /apps/{app}/blobs,GET /apps/{app}/blobs/{id}); the app holds it through aBlobRefin its state and can hand out a time-limited grant. Files are sealed and replicated on the app’s replicas. - Search. A table names its text fields (
#[table(search = [..])]); views query the app’s own index, kept up to date from the log before the view runs. - Xcalls. A call can send a call into another app of the same organization delivered in order after its entry commits, or call or view one synchronously; the target’s ABI says which apps may reach which method (Xcalls).
- Timers and actions.
#[app::every]methods fire once per slot on the leader; an#[app::action]runs outside the log and may write through calls of its own app and send HTTPS. - Upgrades.
POST /apps/{app}/upgrade { version }(or{ bundle }on a development cluster) swaps the bundle; the state carries over as it is, and a named migration is refused (MigrationsNotSupported). Only an owner or admin of the app’s organization upgrades it;GET /apps/{app}/updatetells the app’s frontend whether a release is available and whether the signed-in person may approve it. From CI, use an upgrade key instead of a passkey. - Outbound HTTPS (from an action, or
env::fetchup to 8 recorded requests of a call; never a view, init or a read-only member’s call) goes only under a prefix its signed manifest declares (outbound), to a host the operator allows, once that prefix was approved for the publisher by whoever the cluster’s deployment gave outbound approvals (its governance, whichverify_app_clusterreports). By the owner:POST /orgs/{org}/outbound(your own apps’: their organization’s){ package, prefixes: "manifest" | [...], replace }, with a passkey assertion (client.orgs().outbound_approval(..)in the Rust client,client.orgs.outboundApproval(..)in mero-js). By the operator:POST /ops/outbound. Until then the request is refused withNotApproved(orAwaitingApprovalfor a prefix a later release added), which the app can show. Secrets the operator holds ({{secret:NAME}}) are filled in by the node and redacted from the answer. - Confirmations.
#[app::confirm]methods need a fresh passkey assertion over the exact call (client.apps.call(..., { confirm })in mero-js,client.apps.call(..., confirm=passkey)in calimero-client-py). - Ordering. Calls on one instance are applied in one order, so a write never merges with a concurrent one. There are no offline replicas: a client that cannot reach the cluster cannot write, so there are never concurrent edits to reconcile later.
See Application execution for how a call runs.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Bundle size | 16 MiB |
| One call’s log entry (args + state diff + events) | 1 MiB |
| Apps, bundle bytes, API keys, organizations per account | quotas, set by the operator (429 QUOTA_EXCEEDED) |