Run an IOTA Node on Guix

Here’s how to get a full node running.

Networks

IOTA runs three networks:

Setup

Create the config directory and get the starter config:

mkdir -p /etc/iota && cd /etc/iota
curl -L https://fullnode-docker-setup.iota.org/mainnet | tar -zx
mv data/config/fullnode.yaml .

Download the genesis and migration files:

# mainnet, testnet
curl -fLJ https://dbfiles.mainnet.iota.cafe/genesis.blob -o genesis.blob
# mainnet
curl -fLJ https://dbfiles.mainnet.iota.cafe/migration.blob -o migration.blob

For testnet, replace mainnet with testnet in the URLs above. Testnet doesn’t need the migration.blob.

Configuration

The default config uses /opt/iota which is a Docker convention. On Guix, we use /var/lib for service data. Edit /etc/iota/fullnode.yaml:

# Database
db-path: "/var/lib/iota/db"

# Genesis files
genesis:
  genesis-file-location: "/etc/iota/genesis.blob"
migration-tx-data-path: "/etc/iota/migration.blob"  # mainnet only

# Your public hostname - peers need this to find you
p2p-config:
  external-address: /dns/your-hostname.example.com/udp/8084

Leave the rest (seed peers, archive fallback) as-is.

Ports

Make sure these are open:

Test Run

Before setting up the service, you can run the node manually to make sure everything works:

guix shell iota -- iota-node --config-path /etc/iota/fullnode.yaml

Or with debug logging:

guix shell iota -- sh -c 'RUST_LOG="info,iota_core=debug,consensus=debug" iota-node --config-path /etc/iota/fullnode.yaml'

Once you see checkpoints coming in, you’re good to set up the service.

System Service

Add the service:

(use-modules (px services iota))

(services
 (cons* (service iota-node-service-type
                 (iota-node-configuration
                  (config-file "/etc/iota/fullnode.yaml")))
        %base-services))

The service creates an iota user, sets up directories, and handles log rotation.

Start

sudo guix system reconfigure /etc/system.scm

The node starts automatically. Check on it:

sudo herd status iota-node
sudo tail -f /var/log/iota-node.log

Verify

Query the node to see if it’s syncing:

curl -X POST http://localhost:9000 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"iota_getLatestCheckpointSequenceNumber","id":1}'

The checkpoint number should increase over time. Initial sync from genesis is slow - IOTA provides snapshots at dbfiles.iota.org if you want to speed things up.

CLI

The package also includes the iota CLI:

guix shell iota -- iota client

For validator nodes (staking, key generation), see the IOTA operator docs.
The IOTA package is available from my Guix channel: panther.