Mono Commander

Mono Commander (monoctl) is a terminal-based operator tool for managing Monolythium nodes. It provides both an interactive TUI (terminal user interface) and CLI commands for automation.

Overview

Mono Commander is designed for node operators who want to:

Join networks quickly using official genesis files and seed nodes
Monitor node health via status and RPC checks
View logs without memorizing journalctl flags
Generate systemd units for production deployments

It is keyboard-first (mouse optional) and works alongside standard systemd/Cosmovisor deployments. Commander is an operator helper tool—it does not change consensus behavior or store secrets.

TUI vs CLI: What Gets Built and Where

Both the interactive TUI (monoctl) and CLI commands (monoctl <subcommand>) use the same underlying logic. The TUI is simply a visual wrapper around CLI functionality.

Deployment Modes

Mono Commander supports both deployment modes:

Host-Native (Default): Direct systemd management
Docker: Container-based deployment via monoctl docker commands

Choosing a Deployment Mode

Not sure which mode to use? See Deployment Modes for a detailed comparison.

Execution Model by Mode

Host-Native Mode (Default)

Aspect	Behavior
Runtime	Host-native (no Docker)
Process Manager	systemd on Linux
Binary Location	`~/.local/bin/monod` or `/usr/local/bin/monod`
Node Data	`~/.monod/` (config, data, keys)
Config Files	TOML (config.toml, app.toml)

Commands:

monoctl monod install - Install binary
monoctl join --network X - Join network
monoctl systemd install - Generate systemd unit
monoctl status - Check node status

Docker Mode

Aspect	Behavior
Runtime	Docker containers
Process Manager	docker-compose
Binary Location	Inside container image
Node Data	Volume-mounted from host
Config Files	docker-compose.yml, .env

Commands:

monoctl docker init --network X - Initialize Docker setup
monoctl docker up - Start node container
monoctl docker down - Stop node container
monoctl docker restart - Restart node container
monoctl docker status - Check container status
monoctl docker logs [--follow] - View logs
monoctl docker upgrade --version X - Upgrade to specific version

Artifacts Created by Each Command

Command	Artifacts	Location
`monoctl monod install`	`monod` binary	`~/.local/bin/monod`
`monoctl join --network X`	genesis.json, config patch	`~/.monod/config/`
`monoctl systemd install`	systemd unit file	`/etc/systemd/system/`
`monoctl mesh enable`	mesh config + systemd unit	`~/.mono-commander/`, `/etc/systemd/system/`
`monoctl wallet generate`	encrypted keystore (JSON)	`~/.mono-commander/wallets/`

Decision Tree

Choose your workflow:

New to Monolythium? → Run monoctl (TUI) for guided setup
Scripting or CI/CD? → Use monoctl <command> --json for automation
Quick status check? → monoctl status --network Sprintnet
Joining a network? → monoctl join --network Sprintnet --dry-run (preview first)
Production deployment? → Use CLI with --dry-run, review, then apply

Dry-Run Support

All write operations support --dry-run to preview changes:

monoctl join --network Sprintnet --home ~/.monod --dry-run
monoctl systemd install --network Sprintnet --user monod --dry-run
monoctl monod install --dry-run

Join Official Networks Only

Mono Commander is designed to join existing Monolythium networks (Localnet, Sprintnet, Testnet, Mainnet). It does not support creating custom genesis chains.

Installation

Download the latest release:

# Download binary
curl -LO https://github.com/monolythium/mono-commander/releases/latest/download/monoctl-linux-amd64
chmod +x monoctl-linux-amd64
sudo mv monoctl-linux-amd64 /usr/local/bin/monoctl

# Verify installation
monoctl --help

Or build from source:

git clone https://github.com/monolythium/mono-commander.git
cd mono-commander
go build -o monoctl ./cmd/monoctl
sudo mv monoctl /usr/local/bin/

Supported Networks

Network	Cosmos Chain ID	EVM Chain ID	Status
Localnet	`mono-local-1`	262145 (0x40001)	Development
Sprintnet	`mono-sprint-1`	262146 (0x40002)	Active
Testnet	`mono-test-1`	262147 (0x40003)	Pending
Mainnet	`mono-1`	262148 (0x40004)	Pending

See Chain IDs for complete details.

Network Operations (M1–M2)

List Networks

View all supported networks and their chain IDs:

monoctl networks list

# JSON output for scripting
monoctl networks list --json

Join a Network

Download official genesis, configure seeds, and prepare your node:

monoctl join --network Sprintnet --home ~/.monod

Options:

Flag	Description
`--network`	Network name (required): Localnet, Sprintnet, Testnet, Mainnet
`--home`	Node home directory (default: `~/.monod`)
`--genesis-url`	Override genesis URL (uses official default if not specified)
`--genesis-sha256`	Expected SHA256 of genesis file for verification
`--peers-url`	Override peers registry URL
`--dry-run`	Show what would be done without making changes

Official Genesis and Seeds

The join command downloads the official genesis file and configures DNS-based seed nodes from the Monolythium networks registry. You should always verify the genesis SHA256 matches published values.

Example with verification:

monoctl join --network Sprintnet --home ~/.monod \
  --genesis-sha256 abc123... \
  --dry-run

Update Peers

Refresh the persistent peers list from the official registry:

monoctl peers update --network Sprintnet --home ~/.monod

Options:

Flag	Description
`--network`	Network name (required)
`--peers-url`	Override peers registry URL
`--expected-genesis-sha`	Verify peers registry matches expected genesis
`--home`	Node home directory
`--dry-run`	Show changes without applying

Restart Required

Seed and peer changes require a node restart to take effect. DNS-based seeds are resolved at startup.

Validate Peers (v0.3.1+)

Validate the format and connectivity of peer entries:

monoctl peers validate --network Sprintnet

This command checks peer format, validates node IDs, and verifies peer connectivity.

Generate systemd Unit

Create a systemd service file for your node:

monoctl systemd install --network Sprintnet --user monod --home ~/.monod

Options:

Flag	Description
`--network`	Network name (required)
`--user`	System user to run the service (required)
`--home`	Node home directory
`--cosmovisor`	Configure for Cosmovisor instead of direct monod
`--dry-run`	Print unit file without writing

After generating:

sudo systemctl daemon-reload
sudo systemctl enable monod-sprintnet
sudo systemctl start monod-sprintnet

Docker Operations

macOS Users

macOS does not support systemd. If you're running a node on macOS, you must use Docker mode for deployment and management.

Initialize Docker Environment

Create Docker configuration files for a specific network:

monoctl docker init --network Sprintnet

This command creates:

docker-compose.yml - Container orchestration configuration
.env - Environment variables and network settings
Volume directories for persistent data

Options:

Flag	Description
`--network`	Network name (required): Localnet, Sprintnet, Testnet, Mainnet
`--moniker`	Custom node moniker (optional)

Start Node Container

Start the node in a Docker container:

monoctl docker up

The node starts in detached mode and runs in the background.

Stop Node Container

Stop the running node container:

monoctl docker down

This preserves all node data in Docker volumes. To remove volumes and delete all data:

monoctl docker down -v

Data Loss

Using docker down -v will permanently delete all blockchain data, configuration, and keys. Only use this if you want to completely reset the node.

Restart Node Container

Restart the node container:

monoctl docker restart

Useful after configuration changes or to recover from errors.

View Container Logs

View node logs:

# View recent logs
monoctl docker logs

# Follow logs in real-time
monoctl docker logs --follow

Options:

Flag	Description
`--follow`	Follow log output in real-time (like `tail -f`)

Press Ctrl+C to stop following logs.

Check Container Status

Check the status of the Docker container:

monoctl docker status

Shows:

Container running state
Resource usage
Network connectivity
Current block height (if syncing)

Upgrade Node Version

Upgrade the node to a new version:

# Upgrade to specific version
monoctl docker upgrade --version v1.2.3

# Upgrade to latest version
monoctl docker upgrade --version latest

Options:

Flag	Description
`--version`	Version to upgrade to (required)

The upgrade process:

Stops the current container
Pulls the new Docker image
Restarts the container with the new version
Preserves all data and configuration

Node Operations (M3)

Check Node Status

View current node status including sync progress and peer count:

monoctl status --network Sprintnet

Options:

Flag	Description
`--network`	Network name (default: Localnet)
`--home`	Node home directory
`--host`	RPC host (default: localhost)
`--remote`	Use remote public endpoints instead of local
`--json`	Output in JSON format

System Health Check (v0.3.1+)

Run comprehensive diagnostics on your node setup:

# Human-readable output
monoctl doctor --network Sprintnet

# Machine-readable JSON output for automation
monoctl doctor --network Sprintnet --json

The doctor command checks:

Binary installation and versions
Configuration file validity
Network connectivity
Disk space and system resources
Service status (if applicable)

Example output:

Node Status
----------------------------------------
Chain ID:      mono-sprint-1
Moniker:       my-validator
Version:       0.38.0
Latest Height: 123456
Catching Up:   false
Peers:         12
Service:       active

Configuration Drift Detection (v0.3.6+)

Detect configuration drift from canonical network values:

# Check for configuration drift
monoctl config doctor --network Sprintnet --home ~/.monod

# JSON output for automation
monoctl config doctor --network Sprintnet --home ~/.monod --json

The config doctor command compares your node's configuration against the canonical values from monolythium/networks and detects:

CRITICAL: chain-id in client.toml (causes consensus failure)
CRITICAL: evm-chain-id in app.toml (causes AppHash mismatch)
WARNING: seeds in config.toml (affects connectivity)
WARNING: persistent_peers in config.toml (affects connectivity)

Example output:

Network: Sprintnet
Home: /home/monod/.monod

DRIFT DETECTED:
  [CRITICAL] app.toml evm-chain-id: expected '262146', got '262145'
  [WARNING] config.toml seeds: expected 2 entries, got 0

Run: monoctl config repair --network Sprintnet --home ~/.monod

!!! danger "Critical Drift" Critical drift in chain-id or evm-chain-id will cause consensus failures and AppHash mismatches. Fix immediately using monoctl config repair.

Configuration Repair (v0.3.6+)

Fix configuration drift by updating TOML files to canonical values:

# Preview repairs (dry run)
monoctl config repair --network Sprintnet --home ~/.monod --dry-run

# Apply repairs
monoctl config repair --network Sprintnet --home ~/.monod

The repair command:

Updates chain-id in client.toml
Updates evm-chain-id in app.toml
Updates seeds in config.toml
Updates persistent_peers in config.toml

Preserved during repair:

node_key.json (node identity)
priv_validator_key.json (validator signing key)
All other configuration settings

Example output:

Repair Results:
  ✓ client.toml chain-id
  ✓ app.toml evm-chain-id: '262145' -> '262146'
  ✓ config.toml p2p

All repairs successful. Run 'monoctl config doctor' to verify.

!!! warning "Restart Required" After repairing configuration, restart your node for changes to take effect:

sudo systemctl restart monod-sprintnet

RPC Health Check

Verify all RPC endpoints are healthy and responding correctly:

monoctl rpc check --network Sprintnet

This command checks:

Comet RPC (port 26657) - CometBFT consensus status
Cosmos REST (port 1317) - Cosmos SDK API
EVM JSON-RPC (port 8545) - Ethereum-compatible RPC

The EVM check validates that the returned chain ID matches the expected network (e.g., 262146 for Sprintnet).

Options:

Flag	Description
`--network`	Network name (default: Localnet)
`--host`	RPC host (default: localhost)
`--remote`	Use remote public endpoints
`--comet-rpc`	Override Comet RPC endpoint
`--cosmos-rest`	Override Cosmos REST endpoint
`--evm-rpc`	Override EVM RPC endpoint
`--json`	Output in JSON format

Example output:

RPC Health Check - Sprintnet
--------------------------------------------------
[PASS] Comet RPC (http://localhost:26657)
       chain=mono-sprint-1 height=123456
[PASS] Cosmos REST (http://localhost:1317)
       network=mono-sprint-1 app=monod
[PASS] EVM JSON-RPC (http://localhost:8545)
       chainId=0x40002 block=123456

All RPC endpoints healthy.

Tail Logs

View node logs with optional follow mode:

# Show last 50 lines
monoctl logs --network Sprintnet

# Follow logs in real-time
monoctl logs --network Sprintnet -f

# Show last 100 lines then follow
monoctl logs --network Sprintnet -f -n 100

Options:

Flag	Description
`--network`	Network name (default: Localnet)
`--home`	Node home directory
`-f, --follow`	Follow log output (like `tail -f`)
`-n, --lines`	Number of lines to show (default: 50)

Log Source Detection

On Linux, logs are read from journalctl if the systemd service is running. On macOS or if journalctl is unavailable, logs are read from the file at ~/.monod/logs/monod.log.

TUI Mode

Launch the interactive terminal interface:

monoctl

First-Run Wizard

On first launch, monoctl presents a deployment mode selection wizard:

Linux users: Choose between Host-Native (systemd) or Docker deployment modes
macOS users: Automatically defaults to Docker mode (macOS does not support systemd)

The wizard helps configure your deployment environment and guides you through initial setup. This only appears on first run or if no previous configuration is detected.

The TUI provides a keyboard-navigable menu:

Menu Item	Description
Status	Check node status
RPC Check	Verify RPC endpoint health
Logs	Tail node logs
Networks	View supported networks
Join Network	Join a network (redirects to CLI)
Update Peers	Update peer list (redirects to CLI)
Systemd Install	Generate systemd unit (redirects to CLI)
Exit	Quit the application

Keyboard shortcuts:

↑/↓ or j/k - Navigate menu
Enter - Select item
q or Ctrl+C - Quit (from main menu) or go back
Esc - Go back to main menu

Current Implementation

Some operations currently redirect to CLI commands for full functionality. The TUI provides the command to run.

Safety Notes

No secrets stored: Mono Commander does not store or transmit private keys, mnemonics, or passwords
No consensus changes: Commander is an operator utility; it does not modify consensus behavior
Emergency procedures: For node issues, follow the standard HALT → PATCH → UPGRADE → RESTART procedure documented in Upgrades

Common Workflows

New Node Setup - Docker Mode (Recommended for macOS)

# 1. Initialize Docker environment
monoctl docker init --network Sprintnet

# 2. Start node
monoctl docker up

# 3. Verify node is running
monoctl docker status

# 4. Check logs
monoctl docker logs --follow

New Node Setup - Host-Native (Linux)

# 1. Initialize node
monod init my-node --chain-id mono-sprint-1

# 2. Join network (downloads genesis, configures seeds)
monoctl join --network Sprintnet --home ~/.monod

# 3. Generate systemd service
monoctl systemd install --network Sprintnet --user $USER

# 4. Start and verify
sudo systemctl start monod-sprintnet
monoctl status --network Sprintnet

Daily Health Check

# Quick status
monoctl status --network Sprintnet --json | jq '{height: .latest_height, syncing: .catching_up, peers: .peers_count}'

# Full RPC check
monoctl rpc check --network Sprintnet

Troubleshooting

# Check logs for errors
monoctl logs --network Sprintnet -n 200 | grep -i error

# Follow logs during restart
monoctl logs --network Sprintnet -f &
sudo systemctl restart monod-sprintnet

Mesh/Rosetta Sidecar

The Mesh sidecar (formerly Rosetta) provides a standardized API for exchange integrations and blockchain analytics tools.

Overview

Setting	Validators	RPC/Indexer Nodes	Exchange Nodes
Mesh sidecar	OFF (default)	Recommended ON	Required

The sidecar adds minimal overhead but is not needed for pure consensus participation.

Installation via Commander

# Install the Mesh sidecar
monoctl mesh install --network Sprintnet

# Enable the sidecar service
monoctl mesh enable --network Sprintnet

# Disable the sidecar
monoctl mesh disable --network Sprintnet

Manual Installation

If not using Commander:

# Download mesh-monolythium binary
curl -LO https://github.com/monolythium/mesh-monolythium/releases/latest/download/mesh-monolythium-linux-amd64
chmod +x mesh-monolythium-linux-amd64
sudo mv mesh-monolythium-linux-amd64 /usr/local/bin/mesh-monolythium

Configuration

The sidecar connects to a local monod node. Default ports:

Service	Port
Mesh API	8080
Online mode	Requires running node
Offline mode	Construction API only

Verifying the Endpoint

Check that the sidecar is responding:

# Health check
curl http://localhost:8080/network/list

# Expected response includes network identifier
{
  "network_identifiers": [
    {
      "blockchain": "Monolythium",
      "network": "mono-sprint-1"
    }
  ]
}

Status Check

monoctl mesh status --network Sprintnet

Output:

Mesh Sidecar Status - Sprintnet
----------------------------------------
Service:    active
Endpoint:   http://localhost:8080
Network:    mono-sprint-1
Synced:     true

TODO

End-to-end acceptance tests for the Mesh sidecar are pending and will be added in a future release.

Development

Track development progress at: github.com/monolythium/mono-commander

Current release includes M1–M3 features. Future milestones will add validator operations and enhanced TUI functionality.

Overview​

TUI vs CLI: What Gets Built and Where​

Deployment Modes​

Execution Model by Mode​

Host-Native Mode (Default)​

Docker Mode​

Artifacts Created by Each Command​

Decision Tree​

Dry-Run Support​

Installation​

Supported Networks​

Network Operations (M1–M2)​

List Networks​

Join a Network​

Update Peers​

Validate Peers (v0.3.1+)​

Generate systemd Unit​

Docker Operations​

Initialize Docker Environment​

Start Node Container​

Stop Node Container​

Restart Node Container​

View Container Logs​

Check Container Status​

Upgrade Node Version​

Node Operations (M3)​

Check Node Status​

System Health Check (v0.3.1+)​

Configuration Drift Detection (v0.3.6+)​

Configuration Repair (v0.3.6+)​

RPC Health Check​

Tail Logs​

TUI Mode​

First-Run Wizard​

Main Menu​

Safety Notes​

Common Workflows​

New Node Setup - Docker Mode (Recommended for macOS)​

New Node Setup - Host-Native (Linux)​

Daily Health Check​

Troubleshooting​

Mesh/Rosetta Sidecar​

Overview​

Installation via Commander​

Manual Installation​

Configuration​

Verifying the Endpoint​

Status Check​

Development​

Overview

TUI vs CLI: What Gets Built and Where

Deployment Modes

Execution Model by Mode

Host-Native Mode (Default)

Docker Mode

Artifacts Created by Each Command

Decision Tree

Dry-Run Support

Installation

Supported Networks

Network Operations (M1–M2)

List Networks

Join a Network

Update Peers

Validate Peers (v0.3.1+)

Generate systemd Unit

Docker Operations

Initialize Docker Environment

Start Node Container

Stop Node Container

Restart Node Container

View Container Logs

Check Container Status

Upgrade Node Version

Node Operations (M3)

Check Node Status

System Health Check (v0.3.1+)

Configuration Drift Detection (v0.3.6+)

Configuration Repair (v0.3.6+)

RPC Health Check

Tail Logs

TUI Mode

First-Run Wizard

Main Menu

Safety Notes

Common Workflows

New Node Setup - Docker Mode (Recommended for macOS)

New Node Setup - Host-Native (Linux)

Daily Health Check

Troubleshooting

Mesh/Rosetta Sidecar

Overview

Installation via Commander

Manual Installation

Configuration

Verifying the Endpoint

Status Check

Development