HeroCluster

Secure multi-node cluster management with cryptographic consensus.

Quick Start

# Build
cargo build --release

# Create a cluster
herocluster setup --cluster "MyCluster"

# Run node
herocluster run

# Check status
herocluster status

Features

• One key per node - single ed25519 identity
• Cluster by name - just need the cluster name to derive ClusterId
• KV store - per-node key-value storage, cluster-wide visibility
• Admin control - admins can add/remove nodes and other admins
• Cryptographic - all actions signed with ed25519
• Deterministic - all nodes converge to same state

Commands

# Setup
herocluster setup --cluster NAME     # Initialize node in cluster
herocluster status                   # Show node info
herocluster reset --force            # Clear all data

# Admin operations
herocluster admin list-admins        # List all admins
herocluster admin add-admin KEY      # Add admin by pubkey
herocluster admin list-nodes         # List all nodes
herocluster admin add-node PROOF     # Add node with join proof

# KV Store
herocluster admin kv set KEY VALUE   # Set a value
herocluster admin kv get NODE KEY    # Get a value (NODE = "self" or node_id)
herocluster admin kv list NODE       # List all keys
herocluster admin kv delete KEY      # Delete a key
herocluster admin kv status          # Show all cluster KV data

# Keys
herocluster keys show                # Show your keys

How It Works

1. Cluster Name - derives ClusterId deterministically via BLAKE3
2. Bootstrap - first node creates cluster, others join via bootstrap address
3. Consensus - signed DAG log with topological sort for deterministic ordering
4. Authorization - admins control cluster, nodes own their KV data

Development

# Run tests
bash tests/serious_tests.sh

# 3-node test cluster
make devel
make devel-status
make devel-stop

Architecture

• Identity: ed25519 keypair per node
• Hashing: BLAKE3 for content-addressed storage
• Networking: iroh for P2P QUIC connections
• Consensus: multi-writer signed log (DAG)
• Storage: per-node KV with cluster-wide replication

License

MIT