Quickstart
From nothing to a running app: a local cluster, an account (which comes with its own organization), an app instance in it, and calls from the terminal and from code.
1. A local cluster
Section titled “1. A local cluster”# in corecargo install --locked --path crates/meroctlcargo install --locked --path crates/merodmeroctl app build apps/kv-store --out kv_store.wasmmeroctl local upmeroctl local up starts merod local in the background, in the release’s
Docker image (Docker must be running;
--local runs the merod on PATH): one node on http://127.0.0.1:2501/,
with mock attestation and a development storage key, keeping state in
~/.calimero/meroctl/local/ (--fresh starts over). One node is enough to
build an app. --nodes 3 runs three in one process (2501-2503), as a Cloud
cluster replicates every instance, to see a leader change or a read behind it;
a cluster keeps the count it was made with (another needs --fresh). It saves the cluster as the node local, trusting its mock attestation
for this node only, so it cannot carry over to a real cluster; meroctl local status shows it and meroctl local down stops it. Browser apps
on http://localhost:3000 and http://localhost:5173 may call it (--origins).
The same command works on macOS (Install).
2. Sign up, deploy and call from the terminal
Section titled “2. Sign up, deploy and call from the terminal”# A new passkey file signs up: an account, in no organization yet.meroctl login --dev-passkey ./dev-passkey.json --name adameroctl whoami # orgs: []
# Install the bundle and create an instance; naming no organization, your first# comes with a new organization of your own, and later ones go there.meroctl instance create --path kv_store.wasm --name kv --alias kvmeroctl call --instance kv set --args '{"key":"a","value":"1"}'meroctl call --instance kv get --args '{"key":"a"}' --viewmeroctl instance watch kv --limit 1 # the committed events, as JSON lines
# A read-only API key for a script, approved with your passkey.meroctl account api-key create --instance kv --read-only --dev-passkey ./dev-passkey.jsonTo share an app, create it in an organization of its own and invite people:
meroctl org create Acme # answers { "orgId": ... }meroctl instance create --path kv_store.wasm --name team-kv --org <org-id>meroctl org invite <org-id> --role member --uses 1 --dev-passkey ./dev-passkey.json# the invitee, signed in on their own: meroctl org join <token>In meroctl, an app is a signed package, an instance an app instance (v1’s context), a
namespace an organization, a group one of its teams, account you (each
passkey is one of your devices) and ops the operator
(glossary). Every app instance is in an organization:
one made with an instance, or one it created or joined.
--dev-passkey keeps a passkey in a file, which only a development cluster
accepts. Against a real cluster, use an API key made in the console
(CALIMERO_API_KEY) and name the images you trust:
--tee-profiles <profile> [--min-release <version>]. The release floor defaults
to the client’s DEFAULT_MIN_RELEASE, and debug profiles are refused unless you
pass --allow-debug-profiles. Install apps there as signed packages
(meroctl app install PACKAGE@VERSION, then meroctl instance create --package PACKAGE --name NAME); raw bundles are for development clusters.
3. From code
Section titled “3. From code”JavaScript (mero-js)
Section titled “JavaScript (mero-js)”In a page served from http://localhost:3000 or http://localhost:5173 (the
origins merod local allows for passkeys), with the bundle’s bytes in wasm:
import { CalimeroClient, browserPasskey } from '@calimero-network/mero-js';
// merod local sends mock quotes: allow them explicitly, for this client only.const client = new CalimeroClient({ baseUrl: 'http://127.0.0.1:2501', policy: { allowMock: true } });
await client.signUp(browserPasskey(), 'ada'); // or client.signIn(browserPasskey())const { hash: bundle } = await client.packages.bundlePut({ body: wasm, contentType: 'application/wasm' });const { appId: app } = await client.apps.create({ name: 'kv', bundle }); // your only organization, or a new one
await client.apps.call({ app, method: 'set', args: { key: 'a', value: '1' } });const { result } = await client.apps.view({ app, method: 'get', args: { key: 'a' } });for await (const ev of client.events(app)) console.log(ev);On Calimero Cloud, reach a cluster by name and install a signed release from its registry instead of uploading a bundle; every node the directory names is attested under your policy first:
const cloud = await CalimeroClient.connect({ cluster: 'eu-shared-1', policy: { release: { minReleaseVersion: '2.3.109' } },});await cloud.signIn(browserPasskey());await cloud.packages.install({ package: 'com.example.kv', version: '1.0.0' });const { appId } = await cloud.apps.create({ name: 'kv', package: 'com.example.kv', version: '1.0.0' });A script uses an API key (client.useApiKey('cal_...')) instead of a passkey.
The mero-js docs cover the rest.
Python (calimero-client-py)
Section titled “Python (calimero-client-py)”from calimero_client_py import Client
client = Client("http://127.0.0.1:2501", allow_mock=True)client.use_api_key("cal_...") # the key `meroctl account api-key create` printedprint(client.apps.view(app=app_id, method="get", args={"key": "a"}).to_dict()["result"])For a complete browser frontend (passkey sign-in, live events), see the
apps repository’s apps/kv-store/app, built on mero-js.
4. Scenario tests and the process suite
Section titled “4. Scenario tests and the process suite”An app’s scenarios (apps/<app>/scenarios/*.json) and core’s
(workflows/**/scenarios/) run on an in-process 3-node cluster: deploy, call
and read as several accounts, in orgs and teams, with packages and upgrades.
The process suite starts one merod run --dev process per node and crashes,
freezes, restarts or upgrades them, checking the app keeps its data and answers
within a time budget.
cargo test -p calimero-node --test scenarios -- apps/kv-store/ # kv-store's scenarioscargo build --release -p merod -p meroctlmeroctl app build apps/fixture-kv --out target/app-components/kv.wasmpython3 -I crates/node/tests/fault/suite.py --only frozen-leaderSee Testing strategy for the file format and every step.
5. Next
Section titled “5. Next”- Writing apps for what an app sees on a cluster, and Build for the SDK.
- Deploy from CI to upgrade an app from a pipeline.
- Install & first run and Deployment to run real nodes.
- Testing strategy for the in-process cluster tests, the scenarios and the process suite.