Node Operations

System Dependencies

• • Rust toolchain. The Subtensor node is written in Rust and compiled from source
• • Build essentials. C compiler, linker, and make (e.g., build-essential on Debian/Ubuntu)
• • Git. To clone the repository
• • clang and libclang-dev. Required by some Substrate dependencies
• • protobuf-compiler. For networking protocol compilation

./target/production/node-subtensor \
  --chain ./chainspecs/raw_spec_finney.json \
  --base-path /var/lib/subtensor \
  --sync=warp \
  --port 30333 \
  --max-runtime-instances 32 \
  --database paritydb \
  --db-cache 4096 \
  --trie-cache-size 2048 \
  --rpc-max-response-size 2048 \
  --rpc-cors all \
  --rpc-port 9944 \
  --bootnodes /dns/bootnode.finney.chain.opentensor.ai/tcp/30333/ws/p2p/12D3KooWRwbMb85RWnT8DSXSYMWQtuDwh4LJzndoRrTDotTR5gDC \
  --no-mdns \
  --rpc-external

./target/production/node-subtensor \
  --chain ./chainspecs/raw_spec_finney.json \
  --base-path /var/lib/subtensor \
  --sync=full \
  --pruning archive \
  --db-cache 16384 \
  --max-runtime-instances 32 \
  --rpc-max-response-size 2048 \
  --rpc-cors all \
  --rpc-port 9944 \
  --rpc-external \
  --port 30333 \
  --bootnodes /dns/bootnode.finney.chain.opentensor.ai/tcp/30333/ws/p2p/12D3KooWRwbMb85RWnT8DSXSYMWQtuDwh4LJzndoRrTDotTR5gDC \
  --no-mdns \
  --no-private-ip \
  --prometheus-external \
  --prometheus-port 9615

./target/production/node-subtensor \
  --chain ./chainspecs/raw_spec_testfinney.json \
  --base-path /var/lib/subtensor \
  --sync=warp \
  --port 30333 \
  --rpc-port 9944 \
  --rpc-cors all \
  --bootnodes /dns/bootnode.test.finney.opentensor.ai/tcp/30333/ws/p2p/12D3KooWPM4mLcKJGtyVtkggqdG84zWrd7Rij6PGQDoijh1X86Vr \
  --no-mdns \
  --rpc-external

The testnet uses testTAO tokens and is useful for development and testing without real TAO .

Check Sync Status

Query the node's health to see if it's syncing, how many peers it has, and whether it should be producing blocks.

# Check sync status via RPC
curl -s -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"system_health","params":[],"id":1}' \
  http://127.0.0.1:9944 | jq

The response includes isSyncing (true while catching up), peers (connected peer count), and shouldHavePeers.

Check Connected Peers

See how many peers your node is connected to. A healthy node should have several peers.

# Check connected peers
curl -s -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"system_peers","params":[],"id":1}' \
  http://127.0.0.1:9944 | jq '.result | length'

Node Logs

The node prints sync progress to stdout. Look for lines showing block import progress and finalization status.

# Example log output during sync
Syncing 142.7 bps, target=#7487601 (12 peers), best: #3245100, finalized #3244928

# Once synced, you'll see:
Idle (25 peers), best: #7487601, finalized #7487598

Node Not Syncing

• • Check peers. If 0 peers, your node can't find the network. Ensure port 30333 is open in your firewall
• • Firewall rules. Both inbound and outbound traffic on the P2P port (default 30333) must be allowed
• • Bootnodes. Try specifying custom bootnodes with --bootnodes if built-in bootnodes are unreachable
• • Clock sync. Ensure your system clock is synchronized via NTP. Drift can cause peer rejection

High Disk Usage

• • Switch to lite node. If you don't need historical data, set --pruning 256 to enable pruning
• • Check pruning setting. Verify your node isn't accidentally running in archive mode
• • Database compaction. Restarting the node can trigger RocksDB compaction and reclaim space

RPC Not Accessible

• • External access. By default, the RPC only listens on localhost. Add --rpc-external to listen on all interfaces
• • CORS. Browser-based clients need --rpc-cors all or a specific origin to connect
• • Port conflicts. Check that no other process is using port 9944 with ss -tlnp | grep 9944

Out of Memory

• • Increase RAM. Archive nodes can peak at ~67 GB memory usage and benefit from 64+ GB RAM. Lite nodes need at least 16 GB
• • Tune db-cache. Reduce --db-cache if the node is consuming too much memory. The cache value is in MB
• • Reduce pruning depth. A lower pruning number means less state in memory. Consider switching to a lite node if historical queries aren't needed
• • Swap space. As a temporary measure, add swap space, though SSD is required for acceptable performance