Node Operators Guide

Run a node on the aleph-onchain network. Both coordinator and compute roles are compiled into the same binary — your role is determined by on-chain registration and config flags.

Node Roles

Coordinator Node (CCN)

Message routing, chain watching, scheduling, API serving, storage indexing. Requires high availability and reliable network connectivity.

Compute Node (CRN)

VM execution (Firecracker/QEMU), local storage, networking, proof generation. Requires significant CPU, RAM, and optionally GPU resources.

Hardware Requirements

Resource	Coordinator (CCN)	Compute (CRN)
CPU	4+ cores	16+ cores (with VT-x/AMD-V)
RAM	8 GB	64+ GB
Storage	500 GB SSD	1+ TB NVMe SSD
Network	100 Mbps+	1 Gbps+
GPU (optional)	N/A	NVIDIA with IOMMU support
OS	Linux (kernel 5.10+)	Linux (kernel 5.10+)

KVM Required

Compute nodes must have KVM enabled. Verify with ls /dev/kvm. For Firecracker, you also need /dev/net/tun for VM networking.

Installation

Build from Source

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/aleph-onchain/aleph-onchain.git
cd aleph-onchain
cargo build --release --features compute

# Install Firecracker (for compute nodes)
ARCH=$(uname -m)
curl -L https://github.com/firecracker-microvm/firecracker/releases/download/v1.6.0/firecracker-v1.6.0-${ARCH}.tgz | tar xz
sudo mv release-v1.6.0-${ARCH}/firecracker-v1.6.0-${ARCH} /usr/local/bin/firecracker

Configuration

# /etc/aleph/config.toml

[node]
role = "compute"
data_dir = "/var/lib/aleph"
node_id = "auto"  # derived from keypair

[chain]
rpc_url = "https://arb1.arbitrum.io/rpc"
ws_url = "wss://arb1.arbitrum.io/ws"
private_key_path = "/etc/aleph/keys/node.key"
chain_id = 42161

[chain.contracts]
node_registry = "0x..."
staking_manager = "0x..."
job_manager = "0x..."
payment_manager = "0x..."

[storage]
engine = "rocksdb"
path = "/var/lib/aleph/storage"
max_size_gb = 500
cache_size_mb = 512

[network]
listen_addr = "/ip4/0.0.0.0/tcp/4001"
external_addr = "/ip4/YOUR_IP/tcp/4001"
bootstrap_peers = [
    "/ip4/boot1.aleph.cloud/tcp/4001/p2p/QmBoot1..."
]

[api]
bind = "0.0.0.0:8080"
tls_cert = "/etc/aleph/tls/cert.pem"
tls_key = "/etc/aleph/tls/key.pem"
rate_limit_rps = 100

[executor]
hypervisor = "firecracker"
firecracker_bin = "/usr/local/bin/firecracker"
max_vms = 50
kernel_path = "/var/lib/aleph/kernels/vmlinux"

[metrics]
enabled = true
bind = "0.0.0.0:9090"

On-Chain Registration

# Register your node on-chain
aleph-node register \
    --type crn \
    --metadata-cid QmYourMetadataHash \
    --region us-east \
    --reward-share 500  # 5% to delegators (in basis points)

# Stake ALEPH tokens
aleph-node stake \
    --amount 50000 \
    --token-address 0x27702a26126e0B3702af63Ee09aC4d1A084EF628

Heartbeats & Monitoring

Nodes must submit heartbeats within the configured interval (default: 5 minutes). Missing heartbeats triggers a grace period, after which the node is marked inactive and stops receiving job assignments.

# Check node status
aleph-node status

# View metrics
curl http://localhost:9090/metrics

# Key metrics to monitor:
# aleph_heartbeat_last_sent_timestamp
# aleph_active_vms_count
# aleph_storage_used_bytes
# aleph_p2p_connected_peers

Running as a Service

# /etc/systemd/system/aleph-node.service
[Unit]
Description=Aleph Onchain Node
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=aleph
ExecStart=/usr/local/bin/aleph-node --config /etc/aleph/config.toml
Restart=on-failure
RestartSec=10
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

sudo systemctl enable aleph-node
sudo systemctl start aleph-node
journalctl -u aleph-node -f

Previous ← Smart Contracts Next Compute →