Deploy & install

A published package runs wherever a cluster installs it from the registry: on Calimero Cloud, from the console, or on a node you reach with meroctl.

On Calimero Cloud

Calimero Cloud runs the clusters your apps run on, and the console at cloud.calimero.network is where you publish packages, deploy them, create instances and invite your team.

Shared and dedicated clusters

	Shared cluster	Dedicated cluster
Who runs on it	Many developers’ apps side by side, each account within its quotas	One customer
Billing	Per use, with a free allowance every month	A flat monthly fee
Nodes	Calimero’s attested TDX nodes, replicas spread across zones	Your own attested TDX nodes

Every cluster is self-contained: its own accounts, passkeys, organizations and storage key. An organization and its instances live on one cluster, and every shared app of a Cloud organization runs on the same shared cluster. See Calimero Cloud pricing.

Two kinds of sign-in

• The console signs you in with your work account. It knows your Cloud organization, its members, its packages and its billing.
• The cluster signs you in with a passkey. An app instance belongs to your account on the cluster, and only your passkey can create one, approve an upgrade or mint an invite. So the console prepares those steps and your browser runs them against the cluster: Calimero, which operates the cluster, holds no credential to your apps. Who decides what on a cluster is on the security model page.

Deploy and create instances

Two steps, kept apart on purpose:

• Deploy makes a version of your package available on a cluster. Nothing of your app runs yet.
• Create an instance starts one running copy in one organization. Its init runs once, with that instance’s init arguments, so every organization that uses your app starts from its own state.

1. 01 · Registrynotes 1.2.0Your signed package, com.acme.notes.
2. 02 · DeployInstalled on the clusterEvery node fetches it and checks the signature.
3. 03 · Instancenotes · your orginit {"title": "Team notes"}
4. 04 · Instancenotes-globex · globexinit {"title": "Globex notes"}

One deployed version, any number of instances. Each instance has its own state, members and access rule.

Deploy a version

1. In the console, open Deploy an app and pick the package: one of your organization’s private packages, or a public one from the registry.
2. Name the app and pick the version.
3. Choose where it runs: your organization’s shared cluster, or one of your dedicated clusters. The console shows the estimated cost.
4. Press Deploy, then confirm with your passkey. Your browser installs the version on the cluster.

Deploying again with the same name is an upgrade, from the app’s page.

Create an instance for an organization

On the app’s page, the Instances box lists the instances you created and creates new ones. For each one you pick:

Field	What it decides
Organization	Where the instance lives and who reaches it. The app’s own organization (created with its first instance), a new organization (for example a customer’s), or one an earlier instance created.
Instance name	Its name on the cluster.
Init arguments	JSON your #[app::init] receives: this instance’s starting state. For an init(title: String), {"title": "Globex notes"}.

Then confirm with your passkey: your browser creates the organization if it is new, and the instance in it. If the browser tab closes before the console hears back, running the same step again finds the instance it made rather than creating a second one.

Your app’s own frontend can create instances the same way with mero-js (client.orgs.create, then client.apps.create with package, version, initArgs and org), for example when a new customer signs up. See Call it from code.

Upgrades

An upgrade installs the new version and upgrades every instance in the app’s own organization, after one passkey confirmation. An instance in another organization is upgraded by that organization’s owner, so a customer decides when their instance moves. An app with no instance yet only installs the new version.

Note

An upgrade keeps the instance’s state as it is, and the new code reads it: there are no state migrations in this version. meroctl app pack --previous warns about changes that break callers and refuses a state change made without a state version bump. See What an app sees.

On a node, from the registry

A node installs a published release from its registry by package and version, and every node that runs it checks the publisher’s signature and each file’s digest. With meroctl, signed in to the cluster:

meroctl app install com.calimero.kv-store@1.0.0
meroctl instance create --name kv-release --package com.calimero.kv-store --version 1.0.0 --alias kv-release

app install takes the version as @VERSION or --version, and requires it. instance create --package creates an instance of an installed package: --version picks the release (default the newest installed), --params JSON gives init its arguments, and --namespace ORG creates it in an organization (--group TEAM for one team’s members). Then call it as in the Quickstart: meroctl call --instance kv-release .... (A new alias: kv is the Quickstart’s instance, and giving it to another one moves it there.)

A node installs from the registry it was started with. meroctl local up starts the local cluster with the public registry from core 1.0.0-rc.26 (--registry-url names another); with 1.0.0-rc.25 it has none, and app install answers 400 NO_REGISTRY. On a development cluster, meroctl app install --path FILE.mpk uploads a signed package from a file instead, the one you packed:

meroctl app install --path apps/kv-store/logic/dist/com.calimero.kv-store-1.0.0.mpk

A real cluster installs only from the registry. Every command and flag is in the meroctl reference.

Next → the background: how Calimero works, then what an app sees.