Calimero merobox
Architecture reference for the Python CLI toolbox. Workflow orchestration, Docker & binary node management, NEAR Sandbox integration, and end-to-end testing — all from a single command.
Start Here
New to merobox? Follow this path to understand the system from top to bottom.
System Overview
Understand the high-level architecture: CLI, workflow engine, node managers, and how they connect.
Workflow Engine
Dive into WorkflowExecutor: step lifecycle, placeholder resolution, dynamic values, and result accumulation.
Write a Workflow
Learn the YAML schema for defining nodes, steps, and orchestration sequences.
System Map
Click any box to jump to its deep-dive page.
Component Index
System Overview
High-level architecture, data flow, and component relationships.
Workflow Engine
WorkflowExecutor lifecycle, BaseStep pattern, step factory, dynamic values.
Node Management
DockerManager vs BinaryManager, container lifecycle, Traefik, config TOML.
NEAR Integration
SandboxManager, NearDevnetClient, contract deployment, relayer mode.
Workflow YAML
YAML schema reference: nodes, steps, placeholders, environment variables.
CLI Reference
All 7 commands: run, stop, health, logs, nuke, remote, bootstrap.
Error Handling
MeroboxError hierarchy, ok()/fail() pattern, RetryConfig, @with_retry.
Glossary
Terms and definitions for the merobox ecosystem.
Key Concepts
Workflow
A YAML file that declares a set of nodes and a sequence of steps. The WorkflowExecutor reads this file, resolves all placeholders (environment variables, dynamic values from prior steps), and orchestrates the full lifecycle: environment cleanup, node startup, step execution, and teardown.
Node Resolution
The NodeResolver determines how each declared node maps to a running merod instance. Resolution order: registered remote → URL → Docker container → native binary. Each backend has its own manager class handling lifecycle and health checks.
Step Execution
Steps are the atomic units of a workflow. Each step type extends BaseStep and implements validation and execution. Step types include: install_application, create_context, call, wait_for_sync, repeat, parallel, script, assert, and fuzzy_test.
NEAR Sandbox
For E2E testing, merobox downloads and runs a local near-sandbox instance. The NearDevnetClient handles account creation, key management, and contract deployment. Nodes are configured to point at the local sandbox RPC endpoint for devnet operations.