Remote Nodes — merobox Architecture

Quick Start

Get up and running with remote nodes in four steps.

1

Register a remote node

merobox remote register my-server --url https://node.example.com:2428 \
--auth-method user_password --username admin --description "Production node"

2

Login to the remote node

merobox remote login my-server --username admin --password secret

3

Test the connection

merobox remote test my-server

Verifies connectivity, authentication, and node health.

4

Run a workflow against the remote

merobox run workflow.yaml
# Workflow references "my-server" in remote_nodes

CLI Commands

Full reference for all remote node management commands.

merobox remote register

Register a new remote merod node for use in workflows.

merobox remote register <NAME> --url <URL> [OPTIONS]

Arguments:
  NAME             Unique name for the remote node  required

Options:
  --url            Node endpoint URL (e.g. https://node.example.com:2428)  required
  --auth-method    Authentication method: user_password, api_key, none
  --username       Username for user_password auth
  --description    Human-readable description of the node

merobox remote login

Authenticate with a registered remote node and cache the token.

merobox remote login <NAME> [OPTIONS]

Options:
  --username       Username (overrides registered default)
  --password       Password (or use MEROBOX_PASSWORD env var)
  --api-key        API key for api_key auth method
  --method         Override auth method for this login

merobox remote logout

Clear cached authentication tokens.

merobox remote logout <NAME> [OPTIONS]

Options:
--all Clear tokens for all registered remotes

merobox remote status

Display registration details and auth state for a remote node.

merobox remote status <NAME>

merobox remote test

Verify connectivity and authentication against a remote node.

merobox remote test <NAME> [OPTIONS]

Options:
  --username       Username for inline auth test
  --password       Password for inline auth test
  --api-key        API key for inline auth test

merobox remote list

List all registered remote nodes with their URLs and auth status.

merobox remote list

merobox remote unregister

Remove a registered remote node.

merobox remote unregister <NAME> [OPTIONS]

Options:
--remove-token Also delete cached auth tokens for this node

Remote Nodes in Workflows

Reference remote merod instances directly in workflow YAML files using the remote_nodes key.

YAML Schema

remote_nodes:
  production-node:
    url: https://node.example.com:2428
    auth:
      method: user_password  # user_password | api_key | none
      username: admin

  staging-node:
    url: https://staging.example.com:2428
    auth:
      method: api_key
      key: ${STAGING_API_KEY}

  open-node:
    url: https://open.example.com:2428
    auth:
      method: none

Environment Variable Expansion

All YAML values support environment variable substitution at parse time.

Standard expansion

${ENV_VAR} — replaced with the value of ENV_VAR. Fails if the variable is not set.

Default values

${VAR:-default} — uses the default value if VAR is unset or empty.

remote_nodes:
  my-node:
    url: ${REMOTE_URL:-https://localhost:2428}
    auth:
      method: api_key
      key: ${MY_API_KEY}

Mixed Local + Remote Workflows

Combine locally managed Docker/binary nodes with pre-existing remote nodes in a single workflow.

nodes:
  local-node-1:
    image: ghcr.io/calimero-network/merod:latest
  local-node-2:
    image: ghcr.io/calimero-network/merod:latest

remote_nodes:
  prod-server:
    url: https://prod.example.com:2428
    auth:
      method: user_password
      username: ${PROD_USER}

steps:
  - type: install_application
    node: local-node-1      # local Docker node
  - type: call
    node: prod-server       # remote node

Bootstrap CLI Options

Configure remote nodes during project initialization with merobox bootstrap.

merobox bootstrap [OPTIONS]

Remote-specific options:
  --remote-node NAME=URL      Register a remote node (repeatable)
  --remote-auth NAME=AUTH     Set auth method: user_password, api_key, none
  --api-key KEY              API key for api_key auth method

Example: bootstrap with two remote nodes.

merobox bootstrap \
  --remote-node staging=https://staging.example.com:2428 \
  --remote-auth staging=api_key \
  --api-key ${STAGING_KEY} \
  --remote-node prod=https://prod.example.com:2428 \
  --remote-auth prod=user_password

Authentication Methods

Three authentication methods are supported, each suited for different deployment scenarios.

User / Password

Traditional username and password authentication. Credentials are exchanged for a JWT token which is cached locally.

Best for: interactive use, development environments.

API Key

Static API key passed in request headers. No token exchange required — the key is sent directly with each request.

Best for: CI/CD pipelines, automated workflows.

None

No authentication. The remote node accepts unauthenticated requests. Only suitable for local or trusted network deployments.

Best for: local development, internal networks.

Credential Resolution Order (User/Password)

When using user_password auth, credentials are resolved in the following order:

1

CLI flags

Explicit --username and --password flags on the command line take highest priority.

2

Environment variables

MEROBOX_USERNAME and MEROBOX_PASSWORD environment variables are checked next.

3

Interactive prompt

If neither CLI flags nor environment variables provide credentials, the user is prompted interactively.

Token Caching

JWT tokens obtained via user_password authentication are cached to disk for reuse across commands.

Cache Location

Tokens are stored in ~/.merobox/auth_cache/, with one file per registered remote node named <node-name>.json.

~/.merobox/auth_cache/
my-server.json # JWT + refresh token
staging.json # JWT + refresh token

Token Lifecycle

Acquisition — obtained on merobox remote login or first workflow run requiring auth
Caching — written to ~/.merobox/auth_cache/<name>.json with both access and refresh tokens
Automatic refresh — when the access token expires, the refresh token is used to obtain a new pair transparently
Expiry — if both tokens expire, the user must re-authenticate via login or credentials
Clearing — merobox remote logout deletes the cached token file

Environment Variables

Environment variables for remote node authentication and configuration.

MEROBOX_USERNAME

Default username for user_password authentication. Used when --username is not provided on the CLI. Applies to all remote commands that require a username.

MEROBOX_PASSWORD

Default password for user_password authentication. Used when --password is not provided. Avoids interactive prompts in CI/CD environments.

MEROBOX_API_KEY

Default API key for api_key authentication. Used when --api-key is not provided on the CLI or in YAML configuration.

Troubleshooting

Connection refused or timeout

Verify the URL is correct and the port is accessible: curl -v https://node.example.com:2428/health
Check firewall rules allow inbound connections on the node port
Ensure the remote merod instance is running and healthy
Try merobox remote test <name> for a structured diagnostic

Authentication failed (401 / 403)

Confirm the auth method matches what the remote node expects
For user_password: verify username and password are correct
For api_key: ensure the key is valid and not expired
Clear cached tokens with merobox remote logout <name> and re-authenticate
Check that environment variables (MEROBOX_USERNAME, MEROBOX_PASSWORD, MEROBOX_API_KEY) are set correctly

Token expired — automatic refresh failed

The refresh token has also expired — re-authenticate: merobox remote login <name>
Check that the remote node’s auth service is running and responding
Inspect the cached token file at ~/.merobox/auth_cache/<name>.json for expiry timestamps
Delete stale tokens: merobox remote logout <name>

Environment variable not expanding

Ensure the variable is exported in the shell: export MY_VAR=value
Check for typos in the ${VAR_NAME} placeholder
Variables without a default (${VAR}) will cause a parse error if unset — use ${VAR:-default} for optional values
Environment variables are expanded at YAML parse time, not at step execution time