The cardano node is the beating heart of the Cardano blockchain — the software that connects your computer to the global network, validates transactions, and keeps the decentralized ledger in sync. Think of it as the gateway through which you don't just use Cardano, but actively participate in it. Whether you're a developer exploring the code, an aspiring stake pool operator, or simply someone who believes in decentralization, understanding cardano node software is your first step toward meaningful network participation.
In this guide, we'll walk through what the cardano node actually does, why it matters for decentralization, the different types of nodes you can run, how to download and install the software, and how to navigate the cardano node github repository if you want to explore the code yourself. By the end, you'll have a clear roadmap to run cardano node software on your own machine.
[VISUAL: Diagram - Cardano node architecture overview: three layered boxes (Ledger, Consensus, Networking) with the node executable wrapping them, connecting to peers on both sides]
Why Cardano Nodes Matter — Decentralization Explained
Before diving into the software itself, let's understand why nodes exist in the first place.
The Problem with Centralized Systems
Traditional financial systems rely on central authorities — banks, payment processors, governments — to maintain the ledger of who owns what. If the central server goes down, the system stops. If the authority decides to freeze your funds, you have no recourse. This centralization creates single points of failure and trust dependencies.
How Nodes Solve This
A blockchain node is simply a computer running software that:
- Stores a complete copy of the blockchain ledger
- Validates new transactions against consensus rules
- Propagates valid transactions to other nodes
- Participates in the consensus protocol to agree on the next block
- A CLI (
cardano-cli) for querying the chain, building transactions, and managing keys - A submission API for submitting transactions programmatically
- Configuration management for different network environments (mainnet, testnet, preview)
- Accept incoming connections from many peers (dozens to hundreds)
- Do not produce blocks — they only validate and propagate
- Run on publicly accessible IP addresses with open ports
- Essential for network health: they help new nodes sync and transactions propagate
- Connect only to a small set of trusted relay nodes (typically 2-4)
- Never accept public connections — they're hidden behind relays
- Hold the KES/VRF keys needed to sign blocks and prove leader election
- Must be online and synced during their assigned slots
- URL: https://github.com/IntersectMBO/cardano-node/releases
- Pre-built binaries for Linux (x86_64, aarch64) and macOS
- Always verify SHA256 checksums against the release notes
- Image:
intersectmbo/cardano-node(official org) - Tags for each release:
1.35.6,latest,mainnet,preview,preprod - Easiest path for consistent environments across machines
- Flake:
github:IntersectMBO/cardano-node - Reproducible builds, declarative configuration
- Preferred by many SPOs for production deployments
When thousands of independent nodes run the same software and follow the same rules, no single entity controls the network. This is decentralization in action.
Cardano's Unique Approach
Cardano uses Ouroboros Proof of Stake — a consensus protocol built on peer-reviewed research. Unlike Proof of Work (where miners compete with energy), Ouroboros selects block producers based on the stake they hold or control. This makes running a cardano node far more energy-efficient while maintaining strong security guarantees.
Every cardano node you run strengthens the network. More nodes = more decentralization = more resilience against attacks, censorship, and single points of failure.
[VISUAL: Comparison - Relay node vs Core node: two side-by-side panels showing relay (public-facing, many connections, no block production) vs core (private, few connections, produces blocks when elected)]
Cardano Node Software Architecture
The cardano node software isn't a monolithic blob — it's a carefully layered system that mirrors the academic rigor behind the protocol.
Three Core Layers
1. Ledger Layer — The rulebook This layer defines what a valid transaction looks like, how the UTXO (Unspent Transaction Output) model works, and what state transitions are allowed. It implements the formal specifications from the Ouroboros papers, ensuring mathematical correctness.
2. Consensus Layer — The agreement engine
Built on ouroboros-consensus, this layer implements the Praos and Genesis variants of Ouroboros Proof of Stake. It handles leader election, chain selection, and fork resolution. When your node decides which chain tip to follow, this layer makes that decision.
3. Networking Layer — The communication fabric
Using ouroboros-network, this layer manages peer-to-peer connections, block and transaction propagation, and chain sync protocols. It's designed for high throughput and low latency — critical for a global network.
The Node Executable Wraps It All
The cardano-node binary you download ties these layers together with:
This modular design means upgrades can target specific layers without rewriting everything — a key advantage as the protocol evolves through eras like Conway and beyond.
[VISUAL: Flowchart - Node installation flow: Start → Check system requirements → Choose install method (Docker/Nix/Binary/Source) → Download → Configure topology → Start node → Verify sync → Done]
Types of Cardano Nodes
Not all nodes are created equal. The cardano node software supports different roles depending on what you're trying to achieve.
Relay Nodes — The Network's Connective Tissue
Relay nodes are the public-facing nodes that form the backbone of the Cardano network's connectivity.
Characteristics:
Who runs them: Stake pool operators (as infrastructure), infrastructure providers, enthusiasts with good bandwidth.
Core Nodes (Block Producers) — The Block Makers
Core nodes are the ones that actually mint new blocks when elected by Ouroboros.
Characteristics:
Who runs them: Stake pool operators exclusively. If you're delegating ADA to a pool, you don't run a core node — the pool operator does.
Edge Cases: Light Clients and Wallets
Most users don't run full nodes at all. Daedalus runs a full node embedded in the wallet (great for sovereignty, heavy on resources). Yoroi, Eternl, Lace, and other light wallets connect to remote nodes operated by third parties — convenient, but you trust their node's view of the chain.
[VISUAL: Diagram - Node synchronization process: timeline showing genesis → header sync (fast) → block body sync (slower) → fully synced tip, with progress markers]
How to Download Cardano Node Software
The cardano node download process has multiple paths depending on your operating system and comfort level.
Official Sources
Primary: GitHub Releases (IntersectMBO/cardano-node)
Secondary: Docker Hub
Tertiary: Nix / NixOS
System Requirements (Minimum)
| Resource | Relay Node | Core Node | |----------|------------|-----------| | CPU | 2+ cores | 4+ cores | | RAM | 8 GB | 16 GB | | Storage | 50 GB SSD (growing) | 50 GB SSD | | Bandwidth | Unmetered, ≥100 Mbps | Unmetered, ≥100 Mbps | | OS | Linux (Ubuntu 22.04+, Debian 12+) or macOS | Linux only for production |
> Note for Vietnamese users: If you're running on a VPS in Vietnam (Viettel, FPT, VNPT clouds), ensure your provider allows the required ports (default 3001 for relay, core nodes behind firewall). Many local VPS providers offer unmetered bandwidth which is ideal.
Choosing Your Install Method
| Method | Best For | Difficulty | |--------|----------|------------| | Docker | Quick start, consistent env, CI/CD | ★☆☆☆☆ | | Pre-built Binary | Linux/macOS users wanting native speed | ★★☆☆☆ | | Nix | Reproducible production deployments | ★★★☆☆ | | Build from Source | Developers, custom patches, latest main | ★★★★☆ |
[VISUAL: Diagram - Cardano node GitHub repository structure: tree view showing key directories (cardano-node, cardano-cli, cardano-submit-api, cardano-node-capi, ouroboros-consensus, ouroboros-network, cardano-ledger) with descriptions]
How to Run a Cardano Node — Step by Step
Let's walk through the most accessible path: Docker on Linux. This method works identically on a local machine, a VPS, or a cloud instance.
Step 1: Prepare Your Environment
sudo apt update && sudo apt upgrade -y
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
newgrp docker # or log out/in
sudo apt install docker-compose-plugin
Step 2: Create Project Directory
mkdir -p ~/cardano-node/{config,db,logs,ipc}
cd ~/cardano-node
Step 3: Download Configuration Files
You need three files from the official repository matching your target network (mainnet shown):
wget -O config/mainnet-config.json \
https://raw.githubusercontent.com/IntersectMBO/cardano-node/main/config/mainnet-config.json
wget -O config/mainnet-byron-genesis.json \
https://raw.githubusercontent.com/IntersectMBO/cardano-node/main/config/mainnet-byron-genesis.json
wget -O config/mainnet-shelley-genesis.json \
https://raw.githubusercontent.com/IntersectMBO/cardano-node/main/config/mainnet-shelley-genesis.json
wget -O config/mainnet-alonzo-genesis.json \
https://raw.githubusercontent.com/IntersectMBO/cardano-node/main/config/mainnet-alonzo-genesis.json
wget -O config/mainnet-conway-genesis.json \
https://raw.githubusercontent.com/IntersectMBO/cardano-node/main/config/mainnet-conway-genesis.json
wget -O config/mainnet-topology.json \
https://raw.githubusercontent.com/IntersectMBO/cardano-node/main/config/mainnet-topology.json
Step 4: Create docker-compose.yml
version: '3.8'
services:
cardano-node:
image: intersectmbo/cardano-node:1.35.6 # pin specific version
container_name: cardano-node
restart: unless-stopped
volumes:
- ./config:/config:ro
- ./db:/db
- ./logs:/logs
- ./ipc:/ipc
ports:
- "3001:3001" # relay port - only open if running a relay!
command: >
run
--config /config/mainnet-config.json
--database-path /db
--socket-path /ipc/node.socket
--topology /config/mainnet-topology.json
--port 3001
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
Step 5: Start the Node
docker compose up -d
Step 6: Monitor Sync Progress
docker compose logs -f
docker exec cardano-node cardano-cli query tip --mainnet
Step 7: Verify Full Sync
Wait for the output to show "synced": true and the block height matching a block explorer like CardanoScan or Koios.
{
"epoch": 480,
"hash": "abc123...",
"slot": 42345678,
"block": 10485760,
"synced": true
}
For Core Nodes (Block Producers)
The setup is similar, but you:
1. Don't expose port 3001 publicly
2. Add your KES/VRF/operational certificate files to the config volume
3. Update topology to connect only to your relay nodes
4. Run with --host-addr 0.0.0.0 but firewall all external access except your relays
> Security reminder: Never expose a core node's port to the internet. A compromised core node = stolen block rewards = slashed stake.
[VISUAL: Flowchart - Step-by-step node startup verification: docker compose up → check logs → query tip → compare with explorer → synced? → yes: done / no: wait and retry]
The Cardano Node GitHub Repository
If you want to explore, contribute, or understand the code behind the node, the cardano node github repository is your starting point.
Repository Structure (Simplified)
cardano-node/
├── cardano-node/ # Main executable entry point
├── cardano-cli/ # Command-line interface
├── cardano-submit-api/ # REST API for tx submission
├── cardano-node-capi/ # C API for language bindings
├── ouroboros-consensus/ # Consensus protocol implementation
├── ouroboros-network/ # Networking layer
├── cardano-ledger/ # Ledger rules and state
├── cardano-api/ # Higher-level API types
├── cardano-crypto/ # Cryptographic primitives
├── cardano-prelude/ # Shared utilities
├── flake.nix # Nix flake for reproducible builds
├── cabal.project # Cabal build configuration
├── docker-compose.yml # Docker development environment
└── README.md # Getting started guide
Key Directories for Beginners
| Directory | What You'll Find |
|-----------|------------------|
| cardano-node/ | Main.hs — the program entry point, CLI argument parsing |
| cardano-cli/ | All cardano-cli subcommands (query, transaction, key, governance) |
| ouroboros-consensus/ | The consensus protocol — leader election, chain selection |
| ouroboros-network/ | Peer-to-peer protocols, diffusion layer, mini-protocols |
| cardano-ledger/ | UTXO validation, script execution, state transition logic |
How to Build from Source
git clone https://github.com/IntersectMBO/cardano-node.git
cd cardano-node
nix build .#cardano-node
cabal update
cabal build all -j$(nproc)
The built binaries end up in dist-newstyle/build/.../x/cardano-node-*/build/cardano-node/.
Contributing
The project welcomes contributions:
Read CONTRIBUTING.md and the developer portal's contribution guide before submitting.
FAQ — Common Questions About Cardano Nodes
Do I need to run a node to stake ADA?
No. You can delegate your ADA to a stake pool using any wallet (Daedalus, Yoroi, Eternl, Lace, etc.). The pool operator runs the core node; you just choose which pool to delegate to. Running your own node gives you sovereignty (you verify the chain yourself) but isn't required for staking rewards.
How much does it cost to run a cardano node?
A relay node on a modest VPS (4 vCPU, 8 GB RAM, 100 GB SSD, unmetered bandwidth) costs $20–50/month depending on provider. Core nodes need similar specs but stricter security. Compare this to Proof of Work mining rigs costing thousands in hardware and electricity.
Can I run a node on Windows?
Not natively for production. The official binaries target Linux and macOS. You can run via WSL2 (Windows Subsystem for Linux) or Docker Desktop, but for a 24/7 production node, a Linux VPS is strongly recommended.
What's the difference between cardano-node and cardano-cli?
- cardano-node: The long-running daemon that syncs the chain, validates blocks, and participates in consensus.
How do I update my node to a new version?
Docker: Update the image tag in docker-compose.yml, then docker compose pull && docker compose up -d.
Binary: Download the new release, replace the binary, restart the service.
Nix: Update the flake reference, rebuild, switch.
Always check the release notes for migration steps — some upgrades require database migration or config changes.
What ports does the node use?
- 3001 (default): P2P communication port. Open for relays, firewalled for core nodes.
cardano-submit-api REST endpoint if enabled./ipc/node.socket): Local CLI communication.Can I run a node on a Raspberry Pi?
Technically yes (ARM64 builds exist), but not recommended for mainnet. The blockchain state has grown beyond what a Pi's RAM and I/O can comfortably handle for continuous sync. Fine for learning/testnet; not for production.
What happens if my node goes offline?
- Relay: Peers disconnect, network loses some connectivity. No direct penalty.
Is running a node profitable?
Not directly. Running a relay node has no direct rewards — it's a public good. Running a core node as a stake pool operator earns rewards from delegation, but you need significant stake (own + delegated) to be elected regularly. Most individuals delegate rather than operate.
Where do I get help if something breaks?
1. Cardano Stack Exchange — technical Q&A 2. IntersectMBO Discord — #node-operations channel 3. GitHub Issues — for confirmed bugs in the software 4. SPO Telegram/Discord groups — operator community knowledge sharing
Conclusion: Your Gateway to Cardano Participation
The cardano node software is more than just code — it's your invitation to become a first-class citizen of the Cardano network. Whether you run a relay to strengthen the network's connectivity, operate a core node as a stake pool operator, or simply run a full node for personal sovereignty, you're contributing to the decentralization that makes Cardano resilient.
Start small: spin up a testnet node via Docker, watch it sync, query the tip, submit a transaction. The learning curve is real but manageable, and the community resources are extensive. The cardano node github repository is open for exploration, and the path from "curious beginner" to "competent node operator" is well-trodden.
Decentralization isn't an abstract ideal — it's built one node at a time. Yours could be next.
---
Related Reading: