Merobox CLI

A Python CLI for managing Calimero nodes (Docker or native) and orchestrating YAML workflows.

Full documentation: Architecture Reference

Quick Start

Installation

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 merobox

PyPI:

pipx install merobox

Homebrew:

brew 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 — 35+ 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() and workflow() context managers for test harnesses

Requirements

Python: 3.9 – 3.11 (3.12+ not supported due to py-near / ed25519 dependency)
Docker: 20.10+ (for Docker mode)
OS: Linux, macOS (Windows via WSL only)

Documentation

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

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.43.tar.gz (304.0 kB view details)

Uploaded Jul 17, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

merobox-0.6.43-py3-none-any.whl (360.0 kB view details)

Uploaded Jul 17, 2026 Python 3

File details

Details for the file merobox-0.6.43.tar.gz.

File metadata

Download URL: merobox-0.6.43.tar.gz
Upload date: Jul 17, 2026
Size: 304.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for merobox-0.6.43.tar.gz
Algorithm	Hash digest
SHA256	`ded23c036aec27afc03b406cf678a947b78fb5463b3911521e92c10aeb2244e4`
MD5	`689e12d3128903b5982cd9d637d3037b`
BLAKE2b-256	`60f05bc3b932e89073365df8103c7128a8e5da25957842d0df5d89075079636b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for merobox-0.6.43.tar.gz:

Publisher: release.yml on calimero-network/merobox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: merobox-0.6.43.tar.gz
- Subject digest: ded23c036aec27afc03b406cf678a947b78fb5463b3911521e92c10aeb2244e4
- Sigstore transparency entry: 2190409266
- Sigstore integration time: Jul 17, 2026
Source repository:
- Permalink: calimero-network/merobox@22bb8e73fda90de3bcdf1962912dfb52b1c39aa0
- Branch / Tag: refs/heads/master
- Owner: https://github.com/calimero-network
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@22bb8e73fda90de3bcdf1962912dfb52b1c39aa0
- Trigger Event: push