Skip to content

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.

  • 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 the docker group); on a Mac, start Docker Desktop.

  • curl and git.

  • 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 (packageManager in its package.json); corepack enable (Node.js 20 to 24) uses that one, or install pnpm with npm install -g pnpm.

Then install meroctl, the command line. The installer checks it against the release’s SHA256SUMS and puts it in ~/.local/bin:

Terminal window
curl -fsSL https://raw.githubusercontent.com/calimero-network/core/master/scripts/install.sh | sh

Put ~/.local/bin on your PATH, now and for every new terminal:

Terminal window
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"

Or with Homebrew, on Linux or macOS, which puts it on your PATH itself:

Terminal window
brew install calimero-network/tap/meroctl

If 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.

  1. Run a node.

    Terminal window
    meroctl local up

    This starts merod local, the node, in the release’s Docker image, in the background: a development cluster of one node on http://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 3 runs three, as Calimero Cloud replicates every instance (see below). It keeps its state in ~/.calimero/meroctl/local/, saves the cluster as the meroctl node local, and prints the node URLs and an operator token. meroctl local down, from any directory, stops it; the state stays for the next up.

  2. Clone an app.

    Terminal window
    meroctl app new my-app && cd my-app

    app new starts a project from the apps repository’s kv-store app: the app, the shared packages/ and scripts/ 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
  3. Build it.

    Terminal window
    meroctl app build apps/kv-store/logic

    This compiles the crate for wasm32-wasip2 into a calimero:app component, with the app’s ABI (its methods, events and types) embedded, and writes apps/kv-store/logic/app.component.wasm. The first build fetches and compiles the SDK and takes a few minutes; after that, about 30 seconds.

  4. 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.json does not exist, meroctl creates a new passkey (a software one, made the way a phone or security key makes one), signs up an account named me with 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. Its init ran once, as you, and it lives in your personal organization, which the sign-up made. --alias kv names it for your account.

  5. 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" } }],
    …
    }

    index is the log index the call committed at, and events what 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.

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:

Terminal window
meroctl local down
meroctl local up --nodes 3 --fresh
rm ~/.calimero/me.json
meroctl login --dev-passkey ~/.calimero/me.json --name me
meroctl 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.

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.

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 merod on PATH in meroctl local up unless you pass --docker (macOS has no merod there: use meroctl local up --docker), keeps its state in .merod-local/ in the directory you ran it from (run meroctl local down from there), and leaves an empty apps/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.