Run a Mainnet Node
Running a CKB Mainnet node allows you to participate directly in the live Nervos blockchain, verify transactions, and support network decentralization. This guide will cover the steps needed to set up and run a Mainnet node on CKB, which is ideal for those looking to be actively involved in the network's governance and day-to-day activities.
Recommended Requirements
- At least 150 GB of available disk space
- Stable internet connection
- Syncing from genesis may take up to several days depending on your CPU, bandwidth, and disk performance
Step 1: Download the CKB Binary
Download the latest version of CKB from the official GitHub Releases page. Make sure to download the correct version for your operating system.
This guide uses version ckb_v0.115.0 as an example.
Step 2: Navigate to the CKB Directory
Unzip the downloaded archive into a location that's easy to find. We recommend:
- MacOS:
~/Documents/ckb_v0.115.0/...
- Windows:
C:\ckb_v0.115.0\...
- Mac
- Windows
Open a terminal and navigate into the folder using the following command:
cd /Users/(NAME)/Documents/ckb_v0.115.0_aarch64-apple-darwin-portable/ckb
Remember to replace “(NAME)” with your actual name on the device.
Open a command prompt and navigate into the folder using the following command:
cd C:/ckb_v0.115.0_x86_64-pc-windows-msvc
Step 3: Verify Installed Versions
Run the following commands:
- Mac
- Windows
./ckb --version
./ckb-cli --version
Notice for Unix-like systems, you need to explicitly use ./
to tell the shell to run ckb
file in the current folder.
You should see the installed version printed in the terminal, like this:
ckb 0.115.0 (d845cbf 2024-04-01)
ckb-cli 1.8.0-rc1 (cf4159b 2024-03-28)
If you see a message like 'ckb' cannot be opened because the developer cannot be verified
, this is macOS blocking unsigned binaries. To bypass:
- Go to System Settings → Privacy & Security
- Scroll down and click “Open Anyway”
- Rerun the command
ckb --version
ckb-cli --version
You should see the installed version printed in the terminal, like this:
ckb 0.115.0 (d845cbf 2024-04-01)
ckb-cli 1.8.0-rc1 (cf4159b 2024-03-28)
Step 4: Initialize the Node for Mainnet
Enter the following command to set up default configuration and data
folders.
ckb init --chain mainnet
If you're using a Unix-like system, run ./ckb init --chain mainnet
instead.
Step 5: Start the Node
Now that your node is initialized, you can start syncing to the Mainnet. Make sure you run the following command from the folder where you initialized the node in Step 4.
ckb run
If you're using a Unix-like system, run ./ckb run
instead.
If your node is running successfully, you’ll see log messages similar to this:
...
2025-05-30 01:57:58.941 +00:00 verify_blocks INFO ckb_chain::verify [verify block] new best block found: 9768557 => 0x1412c40a9ffcb18754e0e8349e383179ea47c4f2183a2e1e830a274ba37b5222, difficulty diff = 0x14f821cdc0fe600e, unverified_tip: 9768562
2025-05-30 01:57:58.941 +00:00 verify_blocks INFO ckb_chain::verify block: 9768557, hash: 0x1412c40a9ffcb18754e0e8349e383179ea47c4f2183a2e1e830a274ba37b5222, epoch: 7507(1713/1800), total_diff: 0x54a33f4b40bf2ab7232c3, txs: 3
2025-05-30 01:57:58.942 +00:00 verify_blocks INFO ckb_chain::verify [verify block] new best block found: 9768558 => 0x53fce8b632b3e4d011dd682aef73e018a885560a363599d5f00818a1ee3f3762, difficulty diff = 0x14f821cdc0fe600e, unverified_tip: 9768562
2025-05-30 01:57:58.943 +00:00 verify_blocks INFO ckb_chain::verify block: 9768558, hash: 0x53fce8b632b3e4d011dd682aef73e018a885560a363599d5f00818a1ee3f3762, epoch: 7507(1714/1800), total_diff: 0x54a3409ac2dc06c7092d1, txs: 2
2025-05-30 01:57:58.943 +00:00 verify_blocks INFO ckb_chain::verify [verify block] new best block found: 9768559 => 0x6b4a3c48a2035681f429cd206af3a6906cd72ce9c48b8a7f56eb2844ea8a56f1, difficulty diff = 0x14f821cdc0fe600e, unverified_tip: 9768562
2025-05-30 01:57:58.944 +00:00 verify_blocks INFO ckb_chain::verify block: 9768559, hash: 0x6b4a3c48a2035681f429cd206af3a6906cd72ce9c48b8a7f56eb2844ea8a56f1, epoch: 7507(1715/1800), total_diff: 0x54a341ea44f8e2d6ef2df, txs: 3
These logs indicate that your node is downloading and verifying blocks in real time.
The first time you run a node, it will begin syncing the entire blockchain from the genesis block. This process can take up to several days, depending on your internet speed, CPU, and disk performance.
You don’t need to keep it running continuously — you can stop the process at any time using Ctrl + C
. When you restart the node from the same folder, it will resume syncing from where it left off, as long as you haven't deleted or modified the data
folder.
Many operating systems automatically enter low-power or sleep mode after a period of inactivity — even while a terminal process is running. This can silently pause your node, halting sync without an error message. Try disable automatic sleep/suspend in your system settings to ensure your node continues syncing properly.
Check Sync Progress
To check whether your node has fully synced with the Mainnet, open a new terminal window and run:
ckb-cli rpc sync_state
If you're using a Unix-like system, run ./ckb-cli rpc sync_state
instead.
Look for this line in the response:
"ibd": false
The "ibd"
flag stands for initial block download. When it is false
, your node is considered fully synced.
What Happens During IBD?
While your node is still syncing (”ibd”: true
), it behaves differently from a fully participating peer:
- It only connects to one remote peer (not multiple peers) to download blocks.
- It does not relay transactions or blocks to other peers.
- It does not respond to most P2P requests (such as relay or identify).
- It cannot help other nodes sync.
Once IBD is complete, your node becomes fully-synced.
Make Your Node Connectable
By default, your CKB node can download data from others – but it does not allow inbound connections. But unless your node accepts inbound connections, it’s not contributing to the p2p layer of the network.
Why This Matters?
- Connectable nodes allow other peers to sync from you
- You help improve network decentralization and resilience
Track Your Node’s Connectivity
- Ensure your node is running
- Update the
ckb.toml
file in your ckb folder by following this instruction. - Search your node ID on Node Probe and you should be prompted that your node is connectable and visible on the network.
Node Discovery Criteria
To be visible on Node Probe, your node must meet all of the following criteria:
- Supports core protocols: The node must support the discovery, identify, relay, and sync protocols. If you follow the steps in this guide, this shouldn’t be a problem.
- Reachability confirmed: The node must be reported as reachable by at least four other nodes in the network.
- Well-synced and active: The node is well-synced (not necessarily fully synced) and is actively validating transactions and blocks.
- Stable uptime: The node must remain online and meet the above conditions for at least 4 epochs (~16 hours).