Setting Up Your First Calimero Node - Installing and running merod

Tutorial

2026-09-01 Fran Domovic

Setting Up Your First Calimero Node - Installing and running merod

Running and installing a Calimero Node: A Practical Guide

One of the best ways to understand how peer-to-peer systems work is to break them down into individual components and experiment with them hands-on.

In this tutorial, we'll walk through the core concepts of Calimero Network and cover all supported ways to run a Calimero node locally, with a strong focus on practical setup. If this is your first Calimero tutorial, we highly recommend reading the previous blog posts first, as they go deeper into the architecture and theory behind the system. Here, we assume that foundational knowledge and focus primarily on running the node.

Note: This tutorial was completed on macOS. If you encounter issues on Linux or Windows, please contact us at support@calimero.network.

Quick Reminder: What Is a Calimero Node?
The Calimero node (merod) is the core building block of the Calimero Network.
A node: runs applications, handles local storage, synchronizes data with selected peers, executes WASM applications, maintains privacy and consistency across contexts
Key properties: written in Rust, supports explicit, opt-in participation, can run locally or on a server, no global network you must join — every connection is intentional
Each node owner decides: which peers to connect to, which contexts to join, which applications to run

Ways to Run a Calimero Node

To run a Calimero node locally, you need to install merod CLI which is a Rust-based CLI for running Calimero nodes or use python based tool called Merobox. There are three supported ways of running a Calimero node locally:

Build and run merod locally from source
Install merod using Homebrew
Use Merobox (recommended) - Using Docker

Note: Calimero also offers a hosted solution for running a Calimero node on AWS which will be covered in a later blog post.
If you are interested in hosting your own Calimero node on AWS, please contact support@calimero.network.

Prerequisites

Not every tool is required for every setup, but depending on the option you choose, you may need:

Core Tools:

- Git
- Rust toolchain (rustup, rustc, cargo)

For Docker-based setups:

- Docker 20.10+

For Merobox:

- Python 3.8+
- Pipx 1.7.1+

1. Running a Node Locally with merod

This option is ideal if you want full control and prefer running everything natively.

Step 1: Verify Prerequisites

$: git --version
git version 2.39.3 (Apple Git-146)
$: cargo --version
cargo 1.92.0 (344c4567c 2025-10-21)
$: rustup --version
rustup 1.28.2 (e4f3ad6f8 2025-04-28)
$: rustc --version
rustc 1.92.0 (ded5c06cf 2025-12-08)

Step 2: Clone the Calimero Core Repository

$: git clone https://github.com/calimero-network/core.git
Cloning into 'core'...
Resolving deltas: 100% (15780/15780), done.
$: cd core

Step 3: Build and Install merod

Builds your crate and copies the binary into ~/.cargo/bin, so you can run it from anywhere.
$: cargo install --path ./crates/merod
Installed package merod v0.1.0 (/Users/X/Desktop/core/crates/merod) (executable merod)
$: which merod
/Users/frandomovic/.cargo/bin/merod

Builds the binary inside the project only; it's not globally available unless you reference it explicitly.
$: cd crates/merod
$: cargo build --release
Compiling merod v0.1.0 (/Users/X/Desktop/core/crates/merod)
    Finished release [optimized + debuginfo] target(s) in 10.35s
Installing merod v0.1.0 (/Users/X/Desktop/core/crates/merod)
Installing /Users/X/Desktop/core/crates/merod/target/release/merod (executable)
Installed package merod v0.1.0 (/Users/X/Desktop/core/crates/merod) (executable merod)

Step 4: Initialize Node generating configuration file (config.toml)

$: merod --node-name node1 init
2025-12-16T11:47:34.861762Z  INFO merod::cli::init: Generated identity: PeerId("12D3KooW9xPd2gxAouQ29vMfG1B3fpYPPS87VEZyrqzhuVQWc2VL")
2025-12-16T11:47:34.870745Z  INFO merod::cli::init: Initialized a node in "/Users/X/.calimero/node1"

Or from binary
$: cargo run --bin merod -- --node-name node1 init
2025-12-16T11:47:34.861762Z  INFO merod::cli::init: Generated identity: PeerId("12D3KooW9xPd2gxAouQ29vMfG1B3fpYPPS87VEZyrqzhuVQWc2VL")
2025-12-16T11:47:34.870745Z  INFO merod::cli::init: Initialized a node in "/Users/X/.calimero/node1"

With custom ports:

$: merod --node-name node1 init --server-port 2428 --swarm-port 2528
2025-12-16T11:52:13.841762Z  INFO merod::cli::init: Generated identity: PeerId("12D3KooW9xPd2gxAouQ29vMfG1B3fpYPPS87VEZyrqzhuVQWc2VL")
2025-12-16T11:52:13.840725Z  INFO merod::cli::init: Initialized a node in "/Users/X/.calimero/node1"

Or from binary
$: cargo run --bin merod -- --node-name node1 init --server-port 2428 --swarm-port 2528
2025-12-16T11:52:13.841762Z  INFO merod::cli::init: Generated identity: PeerId("12D3KooW9xPd2gxAouQ29vMfG1B3fpYPPS87VEZyrqzhuVQWc2VL")
2025-12-16T11:52:13.840725Z  INFO merod::cli::init: Initialized a node in "/Users/X/.calimero/node1"

Note: You can check the node configuration file in ~/.calimero/node1/config.toml.

$: cat ~/.calimero/node1/config.toml
mode = "standard"

[identity]
peer_id = "12D..."
keypair = "23j..."
...

Step 5: Run the Node

$: merod --node-name node1 run
...
2025-12-16T11:49:59.648695Z  INFO calimero_node::handlers::network_event: Listening on: /ip4/10.100.0.2/udp/2428/quic-v1/p2p/12D3KooWSZ62zZ9HDSWKamuQChFQUUe1ZW3dCffymJXZ7C9S68sz
2025-12-16T11:49:59.649394Z  INFO calimero_server::jsonrpc: JSON RPC server listening on /ip4/127.0.0.1/tcp/2528/http{/jsonrpc}
2025-12-16T11:49:59.649399Z  INFO calimero_server::jsonrpc: JSON RPC server listening on /ip6/::1/tcp/2528/http{/jsonrpc}
2025-12-16T11:49:59.649564Z  INFO calimero_server::ws: WebSocket server listening on /ip4/127.0.0.1/tcp/2528/ws{/ws}
2025-12-16T11:49:59.649576Z  INFO calimero_server::ws: WebSocket server listening on /ip6/::1/tcp/2528/ws{/ws}
2025-12-16T11:49:59.649582Z  INFO calimero_server::admin::service: Admin API server listening on /ip4/127.0.0.1/tcp/2528/http{/admin-api}
2025-12-16T11:49:59.649584Z  INFO calimero_server::admin::service: Admin API server listening on /ip6/::1/tcp/2528/http{/admin-api}
2025-12-16T11:49:59.649881Z  INFO calimero_server::admin::service: Admin Dashboard UI available on /ip4/127.0.0.1/tcp/2528/http{/admin-dashboard}
2025-12-16T11:49:59.649884Z  INFO calimero_server::admin::service: Admin Dashboard UI available on /ip6/::1/tcp/2528/http{/admin-dashboard}

Or from binary
$: cargo run --bin merod -- --node-name node1 run
...
...

Once running, the following services will be available:

- Admin Dashboard: http://localhost:2528/admin-dashboard
- JSON-RPC: http://localhost:2528/jsonrpc
- WebSocket: ws://localhost:2528/ws

2. Running a Node Using Homebrew

Prerequisites

Step 1: Verify Homebrew is installed

$: brew --version
Homebrew 5.0.9

Step 2: Install merod using Homebrew

$: brew install merod
✔︎ JSON API cask.jws.json                             Downloaded   15.3MB/ 15.3MB
✔︎ JSON API formula.jws.json                          Downloaded   32.0MB/ 32.0MB
==> Fetching downloads for: merod
✔︎ Formula merod (0.10.0-rc.29)                       Verified     11.2MB/ 11.2MB
==> Installing merod from calimero-network/tap
🍺  /opt/homebrew/Cellar/merod/0.10.0-rc.29: 4 files, 22.5MB, built in 1 second
==> Running brew cleanup merod...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP=1.
Hide these hints with HOMEBREW_NO_ENV_HINTS=1 (see man brew).

Step 3: Verify installation

$: merod --version
merod (release 0.10.0-rc.29) (build 0.10.0-rc.29) (commit cae25919) (rustc 1.88.0)

Step 4: Initialize and run the node

Use the same commands as for the local build from source for initializing and running the node.

$: merod --node-name node1 init
2025-12-16T11:47:34.861762Z  INFO merod::cli::init: Generated identity: PeerId("12D3KooW9xPd2gxAouQ29vMfG1B3fpYPPS87VEZyrqzhuVQWc2VL")
2025-12-16T11:47:34.870745Z  INFO merod::cli::init: Initialized a node in "/Users/X/.calimero/node1"
...
$: merod --node-name node1 run
2025-12-16T11:49:59.648695Z  INFO calimero_node::handlers::network_event: Listening on: /ip4/10.100.0.2/udp/2428/quic-v1/p2p/12D3KooWSZ62zZ9HDSWKamuQChFQUUe1ZW3dCffymJXZ7C9S68sz
...

3. Running a Node Using Merobox (Recommended)

Merobox is the simplest way to run Calimero nodes locally. It manages nodes inside Docker containers and supports multi-node setups.

Step 1: Verify Pipx is installed

$: pipx --version
1.7.1

Step 2: Install Merobox

$: pipx install merobox
Installing to existing venv 'merobox'
  installed package merobox 0.2.13, installed using Python 3.13.3
  These apps are now globally available:  merobox
done! ✨ 🌟 ✨

Step 3: Verify installation

$: merobox --version
merobox, version 0.2.16

Step 4: Ensure Docker Is Running

If Docker is not running, you may see an error similar to:

Failed to connect to Docker: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
Make sure Docker is running and you have permission to access it.

Make sure Docker Desktop or the Docker daemon is running.

Step 5: Start Nodes with Merobox

$: merobox run --count 1
...
✓ Started Calimero node calimero-node-1 (ID: 467af3bd3ed4)
P2P Port: 2428
RPC/Admin Port: 2528
Chain ID: testnet-1
Data Directory: ./data/calimero-node-1
Non Auth Node URL: http://localhost:2528
Deployment Summary: 2/2 nodes started successfully

Merobox will:

Pull the required images
Initialize node data
Start one or more Calimero nodes

All node services (Admin Dashboard, JSON-RPC, WebSocket) will be available locally.

Conclusion

In this tutorial, we covered all supported ways to install merod and run a Calimero node locally:

- Local build from source
- Install using Homebrew
- Docker-based setup using Merobox

To continue learning about Calimero:

- Explore the documentation
- Review the open-source repositories
- Build and deploy applications
- Contribute to the ecosystem

If you have questions, you can always reach out via Discord or email (support@calimero.network).

Calimero is built to be open, private, and owned by the people who use it.