Here, we’ll be installing go-quai, the Go implementation of Quai Network. This tutorial is focused on Linux distributions and MacOS systems.

Running go-quai on Windows or WSL2 is not currently supported.

Prefer a video tutorial? Check it out here:


Quai consists of many “slices,” or execution shards, that work together to form an overarching network. A global node runs all of these slices, while a slice node runs only a single slice. Our team at Dominant Strategies recommends a slice node for the vast majority of users.

To run a global node during the Iron Age Testnet, you’ll need a MacOS or Ubuntu machine with the following specifications:

Fast CPU with 16+ cores


Fast SSD with at least 3TB free space

10+ MBit/sec download Internet service

To run a slice node during the Iron Age Testnet, you’ll need a MacOS or Ubuntu machine with the following specifications:

Fast CPU with 8+ cores


Fast SSD with at least 1TB free space

10+ MBit/sec download Internet service

The above hardware specifications are for when Quai Network is operating at no/low load. To see the required hardware specifications when Quai Network is operating at high/maximum load, visit the Node Overview page.

Install Dependencies

To run an instance of go-quai, you’ll need to install a few dependencies. You can install dependencies with your favorite package manager (apt, brew, etc.). The following dependencies are required to run a node:


Go v1.21.0+

Snap is not default installed on all Linux distros

  # install snapd if you don't have it already
  sudo apt install snapd

  # install go
  sudo snap install go --classic

If you’re not on Ubuntu or MacOS, instructions on how to install go directly can be found on the golang installation page.


Git & Make

Install git and make with the following command:

# install git and make
sudo apt install git make


Now that you’ve installed the base dependencies, we can go ahead and clone the go-quai repo.

To clone the go-quai repo and navigate to it, run the following commands:

git clone
cd go-quai

This command installs the main branch to your local machine. Unless you intend to develop, you must checkout the latest release.

You can find the latest release on the go-quai releases page. Then, check out the latest release with:

git checkout put-latest-release-here

For example (this not the latest release, check the releases page for the latest release number)

git checkout v1.2.3-rc.4

Node Configuration

After you’ve successfully installed go-quai, you’ll need to configure your node. The network.env.dist is a boilerplate node configuration file. Copy the boilerplate file into network.env so that we can create our own custom config.

cp network.env.dist network.env

The network.env file houses a number of important parameters that we will configure to run our node correctly. The variables listed below will need to be set correctly for every experience level.

  • COINBASE: the address in each chain (location) that mining rewards are paid to. Note that there is one coinbase address per shard.
  • NETWORK: the network (testnet, devnet, etc.) your node is running on.
  • SLICES: the slices of the network that the node will run. Note that the default configuration is for a global node, and that this parameter must be modified to run a slice node.
  • ENABLE_ARCHIVE: whether or not the node will run in archive mode. Note that archive mode is required during the iron age testnet.
This file also contains a number of more advanced parameters that will not be covered in this article.

Open the config file in your favorite text editor or IDE.

# edit network.env with nano
nano network.env

# open go-quai in vscode to edit network.env
code .

# edit network.env with vim
vim network.env

If you are mining, replace the default coinbase addresses below with your own for the chains that you intend to mine. You can generate addresses for each shard easily with Pelagus Wallet or Koala Wallet.

You must generate a unique address for each COINBASE that is maps to a shard, i.e. generate a Cyprus-1 address with Pelagus and set it as the ZONE_0_0_COINBASE below. Even if you do not plan to mine all the chains, you must still enter a unique address for each.

# Replace addresses below with your addresses for each shard
ZONE_0_0_COINBASE=0x04a3e45aa16163F2663015b6695894D918866d19 # cyprus1
ZONE_0_1_COINBASE=0x21c7650E65b164B2ab645eAF1141b569B2c82Bd7 # cyprus2
ZONE_0_2_COINBASE=0x3e742F0AE63d62304153526A51EE8BF0531d1887 # cyprus3
ZONE_1_0_COINBASE=0x72c871f639ed156De0b97C1b533e2617730b7ec2 # paxos1
ZONE_1_1_COINBASE=0x755c3603c5688CF3105F1a1AfC11fa0e1981b03B # paxos2
ZONE_1_2_COINBASE=0x9fF7B1A33BB22b70F5fb78A420CEd9075C437c87 # paxos3
ZONE_2_0_COINBASE=0xb8094B2bc411942fd078D994Cc4e9418D6A5B071 # hydra1
ZONE_2_1_COINBASE=0xC83cb918dd9267a344B51f57e28e8cf977057E05 # hydra2
ZONE_2_2_COINBASE=0xF39E7d05B5A1a2F934cC43221383f29e4794c822 # hydra3

If you do not replace the addresses in the network.env with Quai addresses you generate and hold the private keys for, you will not receive any mining rewards.

Make sure to set the ENABLE_ARCHIVE variable to true in your network.env file. This will ensure that your node is running in archive mode, which is required for the Iron Age Testnet. It is default set to false.


Set the NETWORK variable to the network you plan on running. Available network options can be found in the network specifications page.

Set the SLICES parameter to whichever slices of the network you would like to run.

Router Configuration

In order to connect directly to peers in the network, you’ll need to make sure the peering ports on your router are forwarded or externally accessible.

The easiest way to ensure the peering ports are forwarded on your router is to enable the universal plug and play (UPNP) option on your router. General information on how to enable UPNP for multiple different types of routers can be found in this article. If your router is not covered in this article, you may have to search for UPNP instructions for your specific model.

If your router does not have UPNP or port-forwarding enabled, your node will return an error when starting and immediately stop running.

If your local router doesn’t support UPNP and you’re port forwarding or you’re setting up on a server (VPS/VDS), you’ll need to configure a few variables in the Networking Variables section in your network.env.

# Networking Variables

Set ENABLE_NAT to true, and replace the placeholder for EXT_IP above with your public server or WAN IP address. This will allow for other nodes in the network to properly connect to your node.

Make sure to uncomment the EXT_IP line (i.e. remove the # from the beginning of the line).

Starting a Node


To start the node, we first need to build the source. You can build via Makefile by running the following command:

make go-quai


Now that we’ve built the source, we need to decide which type of node to run. As detailed in the Node Overview page, users can opt for either a global node or slice node depending on individual use case and hardware.

Run a Global Node

Global nodes validate all of the chains within Quai Network. To spin up a global node run:

make run

Run a Slice Node

Slice nodes run what is called a “slice” of Quai Network. A slice is a subset of the network that validates prime, one region, and one zone chain. In the codebase, a slice is identified by its region and zone index. Region and zone indices are 0-indexed and range from 0-2.

To spin up a slice node, you’ll need to edit the network.env file to specify the slices you want to run. Slice specification can be done by editing the SLICES variable, which is default set to run all slices in the network.

For example, if you wanted to run two slices, you would change SLICES to the following (replace the corresponding INDEX variables for your desired slices):


After configuring the slices you’d like to run in your network.env, start your node using the same command by running:

make run
Running a slice node will start processes for all chains, but only validate state in the chains you specify.

This will start up your slice node with the slices specified in your network.env.

Node operators should self-select the slice least latent to them, in order to minimize their uncle rate and maximize network bandwidth. Providing an initial suggestion for geographic organization will expedite the minimization of latency.

Other Node Operations