A Python CLI for managing Calimero nodes (Docker or native) and orchestrating YAML workflows.
Full documentation: Architecture Reference
APT (Ubuntu/Debian):
curl -fsSL https://calimero-network.github.io/merobox/gpg.key \
| sudo tee /usr/share/keyrings/merobox.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/merobox.gpg] https://calimero-network.github.io/merobox stable main" \
| sudo tee /etc/apt/sources.list.d/merobox.list
sudo apt update
sudo apt install meroboxPyPI:
pipx install meroboxHomebrew:
brew install meroboxFrom source:
git clone https://github.com/calimero-network/merobox.git
cd merobox
pipx install -e .# 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
# Check node status
merobox health
# Execute a workflow
merobox bootstrap run workflow.yml
# Stop all nodes
merobox stop --allname: "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"- Node Management — Start, stop, and monitor nodes in Docker or as native processes
- Workflow Orchestration — 15+ 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
- 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)
All detailed documentation lives in the Architecture Reference:
| 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 16 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 |
# 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- 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.
MIT — see LICENSE for details.