6 min read

Run a devnet node

The public lab devnet lets anyone run a Heartwood relay. It has no value, may be reset or shut down at any time, and is not the public testnet or mainnet. Never reuse real keys or passphrases. Running a node is not validating: validators apply separately. A joining relay needs no private keys and receives no tokens.

This network uses the current classical signatures and reference-compatible formats. The proposed mainnet protocol is a separate target.

Requirements

Use Linux x86-64 and a normal user account with HOME set. You need Git, curl, tar, SHA-256 tools and a C compiler to build from source, plus Rust 1.98 or later. Release binaries do not need Rust; they need glibc 2.34 or newer (Ubuntu 22.04 or later, Debian 12 or later), and on an older system you build from source. Keep a correct clock using NTP or chrony before starting; the node does not synchronize the host clock for you.

Use local SSD storage. The operator guide’s planning figures for a relay are 4 vCPU, 8 GB RAM, 250 GB NVMe storage and a 1 Gbit/s network port. These are planning figures, not measured minimums. Storage grows with the chain. See the repository’s operating guide.

Allow outbound TCP 6002 to the seeds below. This guide binds both listeners to loopback. You can sync without opening an inbound port. To accept outside peers, follow Accept outside peers. Do not expose your node’s API to the internet without a proxy that supplies access controls and rate limits. Keep CORE_API_HOST=127.0.0.1.

Download

Choose one method. Install the binary at a permanent path before creating a service.

Release binary: the v0.1.0-devnet.1 release carries a Linux x86-64 tarball and its SHA256SUMS file. Download both into one empty directory, verify the checksum, then install the heartwood executable. The tarball’s SHA-256 is 11c639568fc8acaab5e2195fd13d79b2e668f8e9e6f76cf9427ee11f0770b95c; compare it with the release page too.

cd "$(mktemp -d)"
curl -fLO https://github.com/iceroot-network/heartwood-core/releases/download/v0.1.0-devnet.1/heartwood-v0.1.0-devnet.1-linux-x86_64.tar.gz
curl -fLO https://github.com/iceroot-network/heartwood-core/releases/download/v0.1.0-devnet.1/SHA256SUMS
sha256sum -c SHA256SUMS
tar -xzf heartwood-v0.1.0-devnet.1-linux-x86_64.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 755 heartwood "$HOME/.local/bin/heartwood"
export PATH="$HOME/.local/bin:$PATH"
heartwood --version

The last command prints heartwood 4.3.1-heartwood.0.1.0.

Build from source:

git clone --branch prod https://github.com/iceroot-network/heartwood-core.git
cd heartwood-core
cargo build --release --locked -p heartwood-core
mkdir -p "$HOME/.local/bin"
install -m 755 target/release/heartwood "$HOME/.local/bin/heartwood"
export PATH="$HOME/.local/bin:$PATH"
heartwood --version
cd ..

For repeatable upgrades, check out the revision named by the release before building. Build only heartwood-core for a release; workspace builds enable test features.

Configure the network

Download the public parameters from this docs site. Verify the archive before extracting it:

curl -fLO https://docs.iceroot.com/devnet/join-bundle.tar.gz
printf '%s  join-bundle.tar.gz\n' 'fcf9126765e91a4036d9a7be9767d092a508e2d45dd08a2e2d51858e2e0b6f5a' | sha256sum -c -
mkdir -p "$HOME/.config/iceroot-core/preview"
tar -xzf join-bundle.tar.gz -C "$HOME/.config/iceroot-core/preview"
(cd "$HOME/.config/iceroot-core/preview" && sha256sum -c SHA256SUMS)

Use a fresh configuration directory. The bundle supplies app.json, peers.json, .env, an empty delegates.json key list and four crypto/*.json files. Public genesis delegate keys are network parameters, not private signing keys. Do not generate a new network or change the crypto files.

Parameter	Value
Configuration network name	`preview`
Local token directory name	`iceroot`
Nethash	`d720707ae730d4ec79f83b6a3735c4eb0bf5abe8d911222845386b99843938b4`
Active delegates	53
Block interval	8 seconds
Seeds, TCP 6002	`2.31.21.34`, `2.31.23.5`, `188.245.3.39`
Local API	`http://127.0.0.1:6003/api/`

The reference API node is not a P2P seed. The --token iceroot flag names local directories; it does not give you currency or credentials. The relay reads these files from ~/.config/iceroot-core/preview, keeps data in ~/.local/share/iceroot-core/preview, and writes logs in ~/.local/state/iceroot-core/preview. heartwood env paths --token iceroot --network preview shows all five directories.

If ports 6002 or 6003 are already occupied, choose unused local ports before starting. For example:

heartwood env set --token iceroot --network preview --key CORE_P2P_PORT --value 26002
heartwood env set --token iceroot --network preview --key CORE_API_PORT --value 26003

These change local listeners only; leave the seed ports at 6002. Use the chosen API port in the checks below.

Run and check sync

heartwood relay run --token iceroot --network preview

Leave this terminal open. Initial sync downloads and applies the chain; the API may not answer until startup sync finishes. Logs should show responsive peers and downloaded blocks. In another terminal, check at most once every few seconds:

curl -fsS http://127.0.0.1:6003/api/blockchain
curl -fsS http://127.0.0.1:6003/api/peers

data.block.height is your local height; /api/peers lists discovered peers. Peer discovery can add the reference node even though it is absent from the seed list. Compare your height with the lab explorer at scan.iceroot.com. A few blocks of difference while requests run is normal; compare block IDs at the same height when investigating a disagreement. This network has no deterministic finality.

Press Ctrl-C to stop gracefully. If startup cannot reach the seeds, check outbound TCP 6002, the network files and the clock. If it reports another network, download the current bundle and follow the reset instructions. Check heartwood doctor --token iceroot --network preview and the logs before changing configuration.

The API applies a request limit to loopback too. Pace scripts below two requests per second and back off when you receive HTTP 429.

Run with systemd

After the foreground run succeeds, stop it before starting a service. A user service needs a working systemd user manager; a minimal container may not have one.

heartwood service install --role relay --token iceroot --network preview
systemctl --user daemon-reload
systemctl --user enable --now iceroot-preview-relay.service
loginctl enable-linger "$USER"
systemctl --user status iceroot-preview-relay.service
journalctl --user -u iceroot-preview-relay.service -f

loginctl enable-linger may need administrator authorization under your host’s policy. The generated unit fixes the binary and data paths. heartwood relay status --token iceroot --network preview reports the service state. Use the journal for a service, and heartwood relay log --token iceroot --network preview for a relay started with the built-in supervisor.

Accept outside peers (optional)

By default your relay only connects outward and listens on loopback, so no other node can connect to it. You can also accept inbound connections, which helps other nodes find the network. This shows your server’s address to the network, and peer traffic is not encrypted, so use a server with nothing else important on it. The steps below never open the API.

Allow inbound TCP 6002, or the P2P port you chose, on the host firewall, on any cloud firewall and, at home, as a router port forward. Do not open the API port.

Make only the P2P listener public:

heartwood env set --token iceroot --network preview --key CORE_P2P_HOST --value 0.0.0.0

Restart the relay. Press Ctrl-C and start it again, or for a service run systemctl --user restart iceroot-preview-relay.service.
Check the listeners and the connections:
Terminal window
```
ss -Htln | grep -E ':600[23]\b'
ss -Htn state established '( sport = :6002 )'
curl -fsS http://127.0.0.1:6003/api/peers
```
The first command should show 0.0.0.0:6002 for P2P and 127.0.0.1:6003 for the API. Use your own port numbers if you changed them. Within a minute the second command lists inbound connections from the network’s nodes, and /api/peers shows them. On a fresh server, the three seeds and the reference node connected in about 15 seconds.

To check from another machine, probe once with nc -vz <your-address> 6002. After the first minute of operation, a connection that never completes its handshake, such as a plain port probe, gets its address banned from your node for 10 seconds.

Validator applicants need this: the team’s sync proof looks for your node in the network’s peer lists.

To stop accepting outside peers, set CORE_P2P_HOST back to 127.0.0.1 and restart.

Upgrade, reset and uninstall

Read the release announcement before upgrading. Stop the relay with Ctrl-C for a foreground run or systemctl --user stop iceroot-preview-relay.service for a service. Replace the binary at the same permanent path with a verified release or a source build, then start it again. Keep configuration and data unless the announcement requires a reset.

For a lab reset, stop the relay, save any logs you need, and remove only this instance’s data directory, ~/.local/share/iceroot-core/preview. Replace its configuration with the new verified bundle, then start again. Old heights, block IDs and balances do not survive a reset. Never copy keys from another network into this one.

To uninstall a service:

systemctl --user disable --now iceroot-preview-relay.service
heartwood service uninstall --role relay --token iceroot --network preview
systemctl --user daemon-reload

After stopping the process, use heartwood env paths --token iceroot --network preview to identify this instance’s directories and remove them if you no longer need them. Remove ~/.local/bin/heartwood only if no other instance uses it.

What this guide does not cover

Validators. A relay follows the chain; it does not produce blocks. Validators apply separately, and forging instructions are not published yet.
The public testnet and mainnet. This guide is for the lab devnet only. The public testnet opens later; see Network status.
A network of your own. There is no guide for creating a separate genesis or a private network.
Serving the API. The guide keeps your node’s API on loopback. Do not expose it to the internet without a proxy that supplies access controls and rate limits.

Network status →