Node Environments

Named Environment Model

kaleido node manages named Docker Compose environments stored under a base directory, which defaults to:

~/.kaleido

Each environment gets its own compose file and volumes, which makes it practical to keep separate local stacks for development, testing, or demos. Example layout:

~/.kaleido/
├── default/
│   ├── docker-compose.yml
│   └── volumes/
└── staging/
    ├── docker-compose.yml
    └── volumes/

Create An Environment

kaleido node create
kaleido node create staging

The wizard prompts for:

Base directory
Environment name
Node count
Bitcoin network
Base daemon and peer ports
Whether to start the environment immediately

Lifecycle Commands

Command	Purpose
`kaleido node list`	Show all environments and their node URLs
`kaleido node use <name> [--node N]`	Point the active `node-url` at one node in an environment
`kaleido node up <name>`	Start containers
`kaleido node stop <name>`	Stop containers without deleting data
`kaleido node down <name>`	Stop and remove containers and networks
`kaleido node ps <name>`	Show container status
`kaleido node logs <name>`	Stream logs
`kaleido node clean <name>`	Delete environment data volumes

When exactly one environment exists, commands like up, stop, logs, and clean can auto-detect it.

Switch The Active Node

Use kaleido node use to update the configured node URL:

kaleido node use default
kaleido node use staging --node 2

This is the bridge between Docker-managed environments and all node-dependent commands such as wallet, asset, channel, and payment.

Initialize And Unlock

After a fresh environment starts, initialize the wallet once:

kaleido node init

Key options:

--password to pass the wallet password directly
--mnemonic to restore from an existing mnemonic during initialization

After every restart, unlock the wallet:

kaleido node unlock

Notable unlock options:

--password
--bitcoind-user
--bitcoind-pass
--bitcoind-host
--bitcoind-port
--indexer-url
--proxy-endpoint
--announce-alias
--announce-address

By default, the command uses the KaleidoSwap signet services exposed by the CLI.

Inspect And Lock

kaleido node info
kaleido node lock

Use info to confirm the node is reachable and correctly configured before running wallet, channel, or swap flows.

Node Swap Operations

The nested swap group supports atomic and low-level swap operations on the node side:

kaleido node swap pubkey
kaleido node swap whitelist --swapstring '30/rgb:abc.../10/rgb:def.../...'

Recommended Local Flow

kaleido node create devnet
kaleido node up devnet
kaleido node use devnet
kaleido node init
kaleido node unlock
kaleido node info

Operational Notes

clean is irreversible because it removes the underlying data volumes.
down removes containers and networks, but preserves volumes.
logs accepts --service to limit output to one container.

Continue to Wallet, Assets, And Payments for the commands you run against an unlocked node.

Introduction

Local Node Operations

Trading & Channels

Reference

Named Environment Model

Create An Environment

Lifecycle Commands

Switch The Active Node

Initialize And Unlock

Inspect And Lock

Node Swap Operations

Recommended Local Flow

Operational Notes

​Named Environment Model

​Create An Environment

​Lifecycle Commands

​Switch The Active Node

​Initialize And Unlock

​Inspect And Lock

​Node Swap Operations

​Recommended Local Flow

​Operational Notes

Named Environment Model

Create An Environment

Lifecycle Commands

Switch The Active Node

Initialize And Unlock

Inspect And Lock

Node Swap Operations

Recommended Local Flow

Operational Notes