Quickstart
Five steps, from nothing to a running app you call from the terminal. The app is the KV Store, the apps repository’s reference app: a string key-value store.
Before you start
Section titled “Before you start”-
Linux (x86_64 or aarch64) with glibc 2.35 or newer (Ubuntu 22.04, Debian 12 and later), or macOS on Apple silicon.
-
Docker, installed and running: the local cluster runs in the release’s Docker image. On Linux, your user must be able to run
docker(in thedockergroup); on a Mac, start Docker Desktop. -
curlandgit. -
Rust, from rustup, with the WebAssembly target the build uses:
Terminal window rustup target add wasm32-wasip2 -
Node.js 20 or newer, and pnpm, for the app’s frontend: the five steps below do not need them, but the example’s development loop (
pnpm install,meroctl local dev) and packaging (pnpm -F kv-store build) do. The project pins its pnpm version (packageManagerin itspackage.json);corepack enable(Node.js 20 to 24) uses that one, or install pnpm withnpm install -g pnpm.
Then install meroctl, the command line. The installer checks it against the release’s SHA256SUMS and puts it in
~/.local/bin:
curl -fsSL https://raw.githubusercontent.com/calimero-network/core/master/scripts/install.sh | shPut ~/.local/bin on your PATH, now and for every new terminal:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrcexport PATH="$HOME/.local/bin:$PATH"echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrcexport PATH="$HOME/.local/bin:$PATH"fish_add_path ~/.local/binOr with Homebrew, on Linux or macOS, which puts it on your PATH itself:
brew install calimero-network/tap/meroctlIf a step fails, Troubleshooting has the errors you may meet and what to do about each.
Working with a coding agent such as Claude Code? Build with an AI agent sets it up to take these steps for you.
Five steps
Section titled “Five steps”-
Run a node.
Terminal window meroctl local upThis starts
merod local, the node, in the release’s Docker image, in the background: a development cluster of one node onhttp://127.0.0.1:2501, ready in a few seconds (the first time, after Docker pulls the image). One node is all you need to build an app;--nodes 3runs three, as Calimero Cloud replicates every instance (see below). It keeps its state in~/.calimero/meroctl/local/, saves the cluster as themeroctlnodelocal, and prints the node URLs and an operator token.meroctl local down, from any directory, stops it; the state stays for the nextup. -
Clone an app.
Terminal window meroctl app new my-app && cd my-appapp newstarts a project from the apps repository’skv-storeapp: the app, the sharedpackages/andscripts/it builds with, and the root files that pin their versions, in a new git repository with one commit:my-app/├── Cargo.toml README.md package.json pnpm-* tsconfig.base.json├── apps/kv-store/│ ├── logic/ the app: a Rust crate│ └── app/ its frontend├── packages/ shared frontend packages└── scripts/ component-build.sh: build the app and write its ABI -
Build it.
Terminal window meroctl app build apps/kv-store/logicThis compiles the crate for
wasm32-wasip2into acalimero:appcomponent, with the app’s ABI (its methods, events and types) embedded, and writesapps/kv-store/logic/app.component.wasm. The first build fetches and compiles the SDK and takes a few minutes; after that, about 30 seconds. -
Deploy it. Sign up first:
Terminal window meroctl login --dev-passkey ~/.calimero/me.json --name me{ "accountId": "…", "passkey": "/home/you/.calimero/me.json" }People sign in to Calimero with passkeys. A development cluster also takes a passkey kept in a file, so you can sign in from a terminal: when
me.jsondoes not exist,meroctlcreates a new passkey (a software one, made the way a phone or security key makes one), signs up an account namedmewith it, and saves it in the file, readable only by you. Next time, the same command signs in with it. The file is your development account: keep it out of your project (here it lives in~/.calimero), and delete it to start over with a new account. A real cluster refuses a file passkey; there you sign in with a real one, or use an API key from the console.Then create an instance of the app from the component:
Terminal window meroctl instance create --name kv --path apps/kv-store/logic/app.component.wasm --alias kv{ "appId": "…", "contextId": "…", "group": 2, "replicas": [1], "compute": false }The instance runs on the cluster’s node (
replicas), with its own log. Itsinitran once, as you, and it lives in your personal organization, which the sign-up made.--alias kvnames it for your account. -
Call it. A call writes; the cluster’s leader for the instance runs it and appends it to the log:
Terminal window meroctl call --instance kv set --args '{"key":"a","value":"1"}'{"index": 3,"result": null,"events": [{ "kind": "Inserted", "data": { "key": "a", "value": "1" } }],…}indexis the log index the call committed at, andeventswhat it emitted. A view reads without writing:Terminal window meroctl call --instance kv get --args '{"key":"a"}' --view{ "index": 3, "result": "1", "receipt": { … } }The receipt is the answering node’s signature over the result, under a key its attestation binds.
That is the whole loop: a node, an app, a build, an instance, a call.
Three nodes
Section titled “Three nodes”On Calimero Cloud every instance runs on several nodes: a leader runs each write and the others follow its log. A
local cluster of three nodes (in one process) shows that on your machine: each instance is placed on all three, and a
view with --min-index N may be answered by whichever node has applied index N, not only the leader.
A cluster keeps the node count it was made with, so going to three starts over: stop the one you have, start three
nodes with --fresh, then sign up and create the instance again, as in step 4:
meroctl local downmeroctl local up --nodes 3 --freshrm ~/.calimero/me.jsonmeroctl login --dev-passkey ~/.calimero/me.json --name memeroctl instance create --name kv --path apps/kv-store/logic/app.component.wasm --alias kv--fresh starts with empty state: no account and no instances. The passkey in me.json belonged to an account on
the old cluster, so the new one refuses it (PASSKEY_UNKNOWN_HERE, as for a passkey removed from an account): delete
the file and login signs up a new account. instance create now answers "replicas": [1, 2, 3]. Your app’s code
is the same either way.
Without Docker
Section titled “Without Docker”meroctl local up --local runs the merod binary from your PATH instead of the image. Install it with
... | sh -s -- merod meroctl (Linux, and macOS from core 1.0.0-rc.25) or brew install calimero-network/tap/merod.
With an older release
Section titled “With an older release”The quickstart follows the newest release. Before it:
- 1.0.0-rc.27 and earlier start three nodes in
meroctl local up(2501-2503,"replicas": [1, 2, 3]). A cluster an earlier meroctl made keeps its three nodes and its data after you update. - 1.0.0-rc.24 also runs the
merodonPATHinmeroctl local upunless you pass--docker(macOS has nomerodthere: usemeroctl local up --docker), keeps its state in.merod-local/in the directory you ran it from (runmeroctl local downfrom there), and leaves an emptyapps/kv-store/logic/apps/directory behind after step 3’s build; delete it.
Next → The example, line by line: what you just built. Stuck? See Troubleshooting.