Skip to content

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.

Terminal window
# in core
cargo install --locked --path crates/meroctl
cargo install --locked --path crates/merod
meroctl app build apps/kv-store --out kv_store.wasm
meroctl local up

meroctl 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”
Terminal window
# A new passkey file signs up: an account, in no organization yet.
meroctl login --dev-passkey ./dev-passkey.json --name ada
meroctl 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 kv
meroctl call --instance kv set --args '{"key":"a","value":"1"}'
meroctl call --instance kv get --args '{"key":"a"}' --view
meroctl 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.json

To share an app, create it in an organization of its own and invite people:

Terminal window
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.

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.

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` printed
print(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.

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.

Terminal window
cargo test -p calimero-node --test scenarios -- apps/kv-store/ # kv-store's scenarios
cargo build --release -p merod -p meroctl
meroctl app build apps/fixture-kv --out target/app-components/kv.wasm
python3 -I crates/node/tests/fault/suite.py --only frozen-leader

See Testing strategy for the file format and every step.