Running a Cardano node is the most direct way to participate in the network's consensus, validate transactions, and contribute to the decentralization that makes Cardano secure. Whether you're a developer building dApps, a stake pool operator, or an enthusiast who wants full control over their ADA interactions, learning to run a Cardano node gives you independence from third-party APIs and direct access to the blockchain's state.
This tutorial covers everything from hardware requirements and software installation to configuration, synchronization, and ongoing maintenance. By the end, you'll have a fully operational Cardano node running on mainnet or testnet.
---
Why Run Your Own Cardano Node?
Before diving into the technical setup, it's worth understanding what you gain by operating your own node:
Trustless verification — You validate every block and transaction yourself instead of relying on a block explorer or wallet provider. This is the foundation of "don't trust, verify."
Direct transaction submission — Submit transactions directly to the mempool without going through a third-party API. Lower latency, no rate limits, no API keys.
Full blockchain history — Query any block, transaction, or UTxO at any time. Essential for dApp development, analytics, and auditing.
Stake pool operations — If you plan to run a stake pool, you need at least two nodes (block producer + relay). This guide is your starting point.
Network health contribution — Every additional full node strengthens Cardano's decentralization and resilience against attacks.
---
Hardware Requirements for a Cardano Node
Cardano's node software is resource-intensive, especially during initial blockchain synchronization. Plan your hardware accordingly.
Minimum Specifications (Mainnet)
| Component | Minimum | Recommended | Notes | |-----------|---------|-------------|-------| | CPU | 4 cores (x86_64) | 8+ cores | ARM64 (Apple Silicon, Raspberry Pi 4+) supported but slower sync | | RAM | 16 GB | 32 GB | 8 GB works but risks OOM during sync; swap helps but degrades performance | | Storage | 100 GB SSD | 500 GB+ NVMe | Blockchain grows ~50 GB/year; NVMe dramatically speeds sync | | Network | 10 Mbps up/down | 100 Mbps+ | Unmetered connection preferred; sync downloads ~100 GB | | OS | Linux (Ubuntu 22.04+, Debian 12) | Linux | macOS works; Windows via WSL2 only |
Storage Breakdown (Mainnet, August 2026)
- Chain database (immutable DB): ~120 GB
- Ledger state (volatile DB): ~15 GB
- Logs & config: ~2 GB
- Buffer for growth: 50 GB minimum
Total: ~200 GB minimum, 500 GB+ recommended for 3+ years.
> ⚠️ Do not use HDDs. The random I/O pattern during sync and block validation makes mechanical drives unusably slow. NVMe SSD is strongly recommended.
---
Software Prerequisites
Operating System Setup (Ubuntu 22.04 LTS Example)
sudo apt update && sudo apt upgrade -y
sudo apt install -y \
build-essential \
pkg-config \
libgmp-dev \
libssl-dev \
libsystemd-dev \
zlib1g-dev \
libncursesw5-dev \
libtinfo5 \
git \
jq \
wget \
curl \
tmux \
htop
Install GHC and Cabal (via GHCup)
Cardano node requires specific GHC versions. Use GHCup for reliable version management.
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
source ~/.ghcup/env
ghcup install ghc 9.6.5
ghcup set ghc 9.6.5
ghcup install cabal 3.10.3.0
ghcup set cabal 3.10.3.0
ghc --version # Should show 9.6.5
cabal --version # Should show 3.10.3.0
> 💡 Version Pinning: Always check the [cardano-node release notes](https://github.com/IntersectMBO/cardano-node/releases) for the exact GHC/Cabal versions required. Using mismatched versions causes build failures.
---
Building Cardano Node from Source
Building from source ensures you get the exact version you need and can apply patches if necessary.
Clone and Build
mkdir -p ~/cardano && cd ~/cardano
git clone https://github.com/IntersectMBO/cardano-node.git
cd cardano-node
git fetch --tags
git checkout $(git tag -l "10.*" | sort -V | tail -1) # Adjust version pattern as needed
cabal update
cabal configure -O2 -w ghc-9.6.5
cabal build all
./dist-newstyle/build/x86_64-linux/ghc-9.6.5/cardano-node-*/x/cardano-node/build/cardano-node/cardano-node --version
Alternative: Pre-built Binaries (Faster Setup)
For production deployments, pre-built binaries from the official releases are perfectly fine:
cd ~/cardano
wget https://github.com/IntersectMBO/cardano-node/releases/download/10.1.1/cardano-node-10.1.1-linux.tar.gz
tar -xzf cardano-node-10.1.1-linux.tar.gz
./cardano-node --version
---
Network Configuration: Mainnet vs Testnet
Cardano has multiple networks. Choose based on your use case.
Mainnet (Production)
- Real ADA — Real value, real stakes
764824073Preprod Testnet (Recommended for Testing)
- Test ADA — Free from faucets
1Preview Testnet (Cutting Edge)
- Newest features — May be unstable
2---
[VISUAL: Flowchart - Cardano Node Setup Decision Tree]
---
Configuration Files
Cardano node uses a topology file, configuration file, and genesis files. All three must match your target network.
Directory Structure
mkdir -p ~/cardano-node/{mainnet,preprod}/{config,db,logs,socket}
Genesis Files
Download the genesis files for your network:
cd ~/cardano-node/mainnet/config
wget https://book.world.mobile/genesis/mainnet/byron-genesis.json
wget https://book.world.mobile/genesis/mainnet/shelley-genesis.json
wget https://book.world.mobile/genesis/mainnet/alonzo-genesis.json
wget https://book.world.mobile/genesis/mainnet/conway-genesis.json
cd ~/cardano-node/preprod/config
wget https://book.world.mobile/genesis/preprod/byron-genesis.json
wget https://book.world.mobile/genesis/preprod/shelley-genesis.json
wget https://book.world.mobile/genesis/preprod/alonzo-genesis.json
wget https://book.world.mobile/genesis/preprod/conway-genesis.json
> 📍 Official Genesis Sources: The book.world.mobile mirror is community-maintained. For production, prefer official IOG sources or verify checksums.
---
[VISUAL: Diagram - Cardano Node Configuration File Relationships]
---
Topology File (topology.json)
Defines which peers your node connects to. For a relay node:
{
"Producers": [
{
"addr": "relays-new.cardano-mainnet.iohk.io",
"port": 3001,
"valency": 1
},
{
"addr": "relays-new.cardano-mainnet.iohk.io",
"port": 3002,
"valency": 1
}
]
}
For a block producer, you'd configure it to connect only to your relay nodes (not public relays).
Configuration File (config.json)
{
"AlonzoGenesisFile": "alonzo-genesis.json",
"ByronGenesisFile": "byron-genesis.json",
"ConwayGenesisFile": "conway-genesis.json",
"ShelleyGenesisFile": "shelley-genesis.json",
"RequiresNetworkMagic": "RequiresMagic",
"LastKnownBlockVersion-Major": 10,
"LastKnownBlockVersion-Minor": 0,
"Protocol": "Cardano",
"NodeName": "my-cardano-node",
"HasEKG": 12788,
"HasPrometheus": [ "127.0.0.1", 9090 ],
"minSeverity": "Info",
"maxConcurrencyBulkSync": 2,
"maxConcurrencyDeadline": 6,
"viewMode": "LiveView",
"tracerTracer": "default"
}
Key settings explained:
| Setting | Purpose | Recommended Value |
|---------|---------|-------------------|
| RequiresNetworkMagic | Network identifier | "RequiresMagic" (testnet) / "RequiresNoMagic" (mainnet) |
| HasEKG | EKG monitoring port | 12788 (disable with 0) |
| HasPrometheus | Prometheus metrics | [ "127.0.0.1", 9090 ] |
| maxConcurrencyBulkSync | Parallel sync workers | 2 (increase for faster sync on good hardware) |
| viewMode | Logging verbosity | "LiveView" or "SimpleView" |
---
Starting Your Cardano Node
First Run: Sync from Genesis
The initial sync downloads and validates the entire blockchain. This takes 12-48 hours on recommended hardware.
cd ~/cardano-node/mainnet
tmux new-session -s cardano-node
cardano-node run \
--topology config/topology.json \
--config config/config.json \
--database-path db \
--socket-path socket/node.socket \
--port 3001 \
--host-addr 0.0.0.0 \
--log-config config/log-config.json
What happens during sync:
1. Block fetch — Downloads blocks from peers (bulk sync phase) 2. Block validation — Verifies cryptographic proofs, consensus rules 3. Ledger replay — Reconstructs UTxO state from genesis 4. Chain selection — Chooses the heaviest valid chain
Monitoring Sync Progress
Open a second terminal and check sync status:
cardano-cli query tip \
--mainnet \
--socket-path ~/cardano-node/mainnet/socket/node.socket
watch -n 10 'cardano-cli query tip --mainnet --socket-path ~/cardano-node/mainnet/socket/node.socket'
Output interpretation:
{
"epoch": 450,
"hash": "abc123...",
"slot": 45000000,
"block": 10245000,
"era": "Conway"
}
- block = Current block height (compare to explorers like CardanoScan)
slot = Current slot numberera = Current protocol era (Byron → Shelley → Allegra → Mary → Alonzo → Babbage → Conway)---
[VISUAL: Sequence - Blockchain Synchronization Phases]
---
Running as a Systemd Service (Production)
For production, run the node as a systemd service for auto-restart and logging.
sudo tee /etc/systemd/system/cardano-node.service > /dev/null <<'EOF'
[Unit]
Description=Cardano Node
After=network.target
[Service]
Type=simple
User=cardano
Group=cardano
WorkingDirectory=/home/cardano/cardano-node/mainnet
ExecStart=/home/cardano/.local/bin/cardano-node run \
--topology config/topology.json \
--config config/config.json \
--database-path db \
--socket-path socket/node.socket \
--port 3001 \
--host-addr 0.0.0.0
Restart=always
RestartSec=10
LimitNOFILE=65535
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable cardano-node
sudo systemctl start cardano-node
sudo systemctl status cardano-node
---
Verifying Your Node is Operational
Basic Health Checks
cardano-cli query tip --mainnet --socket-path ~/cardano-node/mainnet/socket/node.socket
cardano-cli query protocol-parameters --mainnet --socket-path ~/cardano-node/mainnet/socket/node.socket
cardano-cli query epoch --mainnet --socket-path ~/cardano-node/mainnet/socket/node.socket
cardano-cli query utxo --address addr1... --mainnet --socket-path ~/cardano-node/mainnet/socket/node.socket
Prometheus Metrics (if enabled)
curl http://127.0.0.1:9090/metrics | grep cardano
Key metrics to watch:
cardano_node_metrics_blockHeight_int — Current block heightcardano_node_metrics_peers_connected_int — Connected peers (should be > 0)cardano_node_metrics_mempool_txs_int — Transactions in mempool---
Common Issues and Troubleshooting
Sync Stuck or Extremely Slow
| Symptom | Cause | Fix |
|---------|-------|-----|
| Peers = 0 | Topology file wrong / firewall | Verify topology.json, open port 3001 |
| High CPU, low disk I/O | CPU bottleneck | Increase maxConcurrencyBulkSync |
| High disk I/O, low CPU | Slow storage | Use NVMe; check disk health |
| OOM kills | Insufficient RAM | Add swap, increase RAM, reduce concurrency |
cardano-cli query node-state --mainnet --socket-path ~/cardano-node/mainnet/socket/node.socket
journalctl -u cardano-node -f
tail -f ~/cardano-node/mainnet/logs/node.log
"Chain DB Corrupted" Errors
sudo systemctl stop cardano-node
mv ~/cardano-node/mainnet/db ~/cardano-node/mainnet/db.backup
sudo systemctl start cardano-node
> ⚠️ Never delete the DB while the node is running. Always stop the service first.
Version Mismatch After Upgrade
cardano-node --version
cardano-cli --version
---
[VISUAL: Comparison - Sync Performance: HDD vs SSD vs NVMe]
---
Advanced Configuration
Running a Relay Node (For Stake Pools)
A relay node sits between your block producer and the public network. It protects your block producer from direct exposure.
Relay topology.json:
{
"Producers": [
{ "addr": "relay1.yourdomain.com", "port": 3001, "valency": 1 },
{ "addr": "relay2.yourdomain.com", "port": 3001, "valency": 1 },
{ "addr": "relays-new.cardano-mainnet.iohk.io", "port": 3001, "valency": 2 }
]
}
Block producer topology.json (connects ONLY to your relays):
{
"Producers": [
{ "addr": "relay1.yourdomain.com", "port": 3001, "valency": 1 },
{ "addr": "relay2.yourdomain.com", "port": 3001, "valency": 1 }
]
}
Firewall Configuration
sudo ufw allow 3001/tcp comment "Cardano P2P"
sudo ufw allow from YOUR_MONITORING_IP to any port 9090
sudo ufw allow ssh
sudo ufw enable
Log Rotation
Prevent logs from filling disk:
sudo tee /etc/logrotate.d/cardano-node > /dev/null <<'EOF'
/home/cardano/cardano-node/mainnet/logs/*.log {
daily
rotate 14
compress
delaycompress
missingok
notifempty
create 640 cardano cardano
}
EOF
---
Maintenance and Upgrades
Regular Maintenance Tasks
| Task | Frequency | Command |
|------|-----------|---------|
| Check sync status | Daily | cardano-cli query tip |
| Monitor disk usage | Weekly | df -h ~/cardano-node/mainnet/db |
| Check peer count | Daily | cardano-cli query node-state |
| Review logs for errors | Weekly | journalctl -u cardano-node --since "1 week ago" |
| Update topology peers | Monthly | Edit topology.json, restart node |
Upgrading Cardano Node
sudo systemctl stop cardano-node
cp ./new-cardano-node /home/cardano/.local/bin/cardano-node
sudo systemctl start cardano-node
cardano-node --version
cardano-cli query tip --mainnet --socket-path ~/cardano-node/mainnet/socket/node.socket
> 🔄 Upgrade Strategy: Test on testnet first. Mainnet upgrades should be coordinated with the community (check Discord/forums for upgrade windows).
---
[VISUAL: Diagram - Cardano Node Architecture: Components & Data Flow]
---
Security Best Practices
Network Security
1. Run as non-root user — Create a dedicated cardano user
2. Firewall — Only expose port 3001 (P2P) and optionally 9090 (Prometheus) to trusted IPs
3. SSH hardening — Key-only auth, disable root login, use fail2ban
4. Regular updates — apt update && apt upgrade weekly
Operational Security
1. No keys on relay nodes — Block producer keys stay on air-gapped/offline machine 2. Backup topology & config — Version control your configuration 3. Monitor for anomalies — Unexpected peer drops, sync stalls, unusual CPU/memory 4. Incident response plan — Document steps for: node crash, fork detection, security breach
---
Performance Tuning
For Faster Sync
{
"maxConcurrencyBulkSync": 4,
"maxConcurrencyDeadline": 12,
"blockFetchBatchSize": 100
}
For Lower Resource Usage (After Sync)
{
"maxConcurrencyBulkSync": 1,
"maxConcurrencyDeadline": 2,
"viewMode": "SimpleView"
}
Database Tuning (PostgreSQL not used — Node uses immutable DB)
The node's internal database is optimized for append-heavy workloads. No manual tuning required beyond adequate RAM and NVMe storage.
---
FAQ: Running a Cardano Node
Q: Can I run a Cardano node on a Raspberry Pi?
A: Yes, on Raspberry Pi 4 (8 GB RAM) or Pi 5 with NVMe HAT. Sync takes 5-7 days. Use 64-bit OS (Ubuntu Server 22.04 ARM64). Not recommended for stake pool relays due to network latency.
Q: How much bandwidth does a node use?
A: Initial sync: ~100 GB download. Ongoing: ~50-200 GB/month depending on peer count and mempool activity. Unmetered connection strongly recommended.
Q: Do I need to stake ADA to run a node?
A: No. Running a node (relay or block producer) requires no ADA. Only registering a stake pool requires a 500 ADA deposit + pledge.
Q: Can I run multiple nodes on one machine?
A: Yes, with different ports, database paths, and socket paths. Common for running mainnet + testnet simultaneously, or relay + block producer (though separate machines preferred for pools).
Q: What's the difference between a full node and a light wallet?
A: A full node (this guide) downloads and validates the entire blockchain. A light wallet (like Yoroi, Eternl, Lace) trusts a remote server for blockchain data. Full nodes provide trustless verification; light wallets provide convenience.
Q: How do I know if my node is on the correct chain?
A: Compare your node's tip hash and block height with multiple block explorers (CardanoScan, CExplorer, PoolTool). They should match exactly.
Q: What happens during a hard fork?
A: Your node will automatically follow the chain with the most cumulative work, provided you've upgraded to a version supporting the new protocol rules. Always upgrade before the hard fork epoch.
Q: Can I run a node on Windows?
A: Only via WSL2 (Windows Subsystem for Linux). Native Windows builds are not officially supported. Performance in WSL2 is near-native.
---
Next Steps
Now that your Cardano node is running, consider these paths:
1. Stake Pool Operator — Set up block producer + relay pair, register pool
2. dApp Developer — Use cardano-cli or Ogmios/Kupo for indexed queries
3. Network Monitor — Set up Prometheus + Grafana dashboards
4. Community Relay — Add your relay to community topology lists
---
Resources and References
- Official Documentation: https://docs.cardano.org/
---
This guide covers Cardano node version 10.x (Conway era). Configuration details may change with future protocol upgrades. Always consult the official release notes for your specific version.