Merobox CLI
A Python CLI for managing Calimero nodes (Docker or native) and orchestrating YAML workflows.
Full documentation: https://calimero-network.github.io/merobox/
Quick Start
Installation
PyPI (recommended):
pipx install merobox
From source:
git clone https://github.com/calimero-network/merobox.git
cd merobox
pipx install -e .
Basic Usage
# Start Calimero nodes
merobox run --count 2
# Start with auth service (Docker mode)
merobox run --auth-service
# Start with embedded auth (binary mode)
merobox run --no-docker --binary-path /path/to/merod --auth-mode embedded
# Pass extra arguments straight to `merod run` (binary mode only)
merobox bootstrap run workflow.yml --no-docker --binary-path ./merod \
--merod-args="--sync-strategy delta --state-sync-strategy hash"
# Check node status
merobox health
# Execute a workflow
merobox bootstrap run workflow.yml
# Stop all nodes
merobox stop --all
Example Workflow
name: "Hello World"
nodes:
count: 2
prefix: "node"
steps:
- name: "Install App"
type: "install_application"
node: "node-1"
path: "./app.wasm"
outputs:
app_id: applicationId
- name: "Create Context"
type: "create_context"
node: "node-1"
application_id: "{{app_id}}"
outputs:
ctx_id: contextId
- name: "Call Method"
type: "call"
node: "node-1"
context_id: "{{ctx_id}}"
method: "hello"
Features
- Node Management — Start, stop, and monitor nodes in Docker or as native processes
- Workflow Orchestration — ~100 step types for complex multi-step YAML workflows
- Remote Nodes — Connect to remote Calimero nodes with user/password or API key auth
- Auth Integration — Traefik proxy (Docker) or embedded JWT auth (binary mode)
- Fuzzy Testing — Long-duration randomized load tests with weighted operations
- pytest Integration —
cluster()andworkflow()context managers for test harnesses
Requirements
- Python: 3.9 – 3.11 (3.12+ not supported due to
py-near/ed25519dependency) - Docker: 20.10+ (for Docker mode)
- OS: Linux, macOS (Windows via WSL only)
Documentation
All detailed documentation lives in the Documentation:
| Topic | Page |
|---|---|
| System architecture & data flow | System Overview |
| WorkflowExecutor, BaseStep, step factory | Workflow Engine |
| DockerManager, BinaryManager, Traefik | Node Management |
| Remote node CLI & auth methods | Remote Nodes |
| Complete YAML schema & all step types | Workflow YAML |
| All CLI commands with flags & options | CLI Reference |
| MeroboxError hierarchy, retry patterns | Error Handling |
| cluster(), workflow(), pytest fixtures | Testing Guide |
| Common issues & debugging tips | Troubleshooting |
| Terms & definitions | Glossary |
Release Process
# Update version in ONE place
vim merobox/__init__.py # Change __version__ = "X.Y.Z"
# Commit and push — automation handles tagging, builds, GitHub release, and PyPI
git add merobox/__init__.py
git commit -m "chore: bump version to X.Y.Z"
git push origin master
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
See the Testing Guide for development setup and adding new commands/step types.
License
MIT — see LICENSE for details.
Links
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
merobox-0.6.56.tar.gz
(334.9 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
merobox-0.6.56-py3-none-any.whl
(393.7 kB
view details)
File details
Details for the file merobox-0.6.56.tar.gz.
File metadata
- Download URL: merobox-0.6.56.tar.gz
- Upload date:
- Size: 334.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
aaaca687abdda337f48e767156d173533becec88c877b1a10097d36095053363
|
|
| MD5 |
e795f6a5a2b26aab80b2d4a6c78c3652
|
|
| BLAKE2b-256 |
b443b682cc821b121cee9916cac9e1a33e9d99f6a635d6526a813ef03f3b2005
|
Provenance
The following attestation bundles were made for merobox-0.6.56.tar.gz:
Publisher:
release.yml on calimero-network/merobox
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
merobox-0.6.56.tar.gz -
Subject digest:
aaaca687abdda337f48e767156d173533becec88c877b1a10097d36095053363 - Sigstore transparency entry: 2501961502
- Sigstore integration time:
-
Permalink:
calimero-network/merobox@9f6ff7f53faa2a2cb8512bdef7350cb323ced10b -
Branch / Tag:
refs/heads/master - Owner: https://github.com/calimero-network
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@9f6ff7f53faa2a2cb8512bdef7350cb323ced10b -
Trigger Event:
push
-
Statement type:
File details
Details for the file merobox-0.6.56-py3-none-any.whl.
File metadata
- Download URL: merobox-0.6.56-py3-none-any.whl
- Upload date:
- Size: 393.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ac4c3f620a175f22ba033a01542e0eefdf9ab07b85c498ab568442620ef68f8e
|
|
| MD5 |
4a4bef3c4b897336da352316c4eeba3c
|
|
| BLAKE2b-256 |
564fe3494be8d6c5ed8ecbec4f3f68c97102c528f713042d163609f6e8a3dabb
|
Provenance
The following attestation bundles were made for merobox-0.6.56-py3-none-any.whl:
Publisher:
release.yml on calimero-network/merobox
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
merobox-0.6.56-py3-none-any.whl -
Subject digest:
ac4c3f620a175f22ba033a01542e0eefdf9ab07b85c498ab568442620ef68f8e - Sigstore transparency entry: 2501961595
- Sigstore integration time:
-
Permalink:
calimero-network/merobox@9f6ff7f53faa2a2cb8512bdef7350cb323ced10b -
Branch / Tag:
refs/heads/master - Owner: https://github.com/calimero-network
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@9f6ff7f53faa2a2cb8512bdef7350cb323ced10b -
Trigger Event:
push
-
Statement type:
