Run A Node

Environment Setup

Here, we'll be installing go-quai, the Go implementation of a Quai Network Node. This article is focused for Linux Distributions and MacOS systems. If you're running Windows, this may require additional environment config related to WSL2.

Install Dependencies

To run an instance of go-quai, you'll need to install these programs first:
  • Git - A DevOps tool used for source code management
  • Golang - A simple, statically typed language for building secure and scalable systems.


To download the node program files, you'll need to install git. Instructions on how to download git can be found on the Git Guides.


Running an instance of Quai Network also requires your machine has Go version 1.19.0 or higher. Directions on how to install Go can be found in the Golang development guide.
You can verify your install and version by running:
go version
Add Go to the $PATH environment variable by running:
export PATH=$PATH:/usr/local/go/bin

Install go-quai

Now that you've installed the base dependencies, we can go ahead and clone the go-quai repo. We recommend making a directory to house all of your Quai related repositories for easy access.
cd path/to/directory
mkdir quai
Now that we've made our parent directory, we can navigate to it and download the repository.
cd quai
git clone
cd go-quai
This command checks out the main branch to your local.

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.
  • LOCATION_COINBASE : the address in each chain (location) that mining rewards are paid to.
  • NETWORK : the network (testnet, devnet, etc.) your node is running on.
  • THREADS : the number of CPU threads your node can utilize.
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, such as VSCode. If you are mining, replace the dummy coinbase addresses with your own for the chains that you intend to mine. If you do not do this, your mining rewards will not be sent to the your addresses.
Set the NETWORK variable to the network you plan on running. Set the THREADS to your desired number, but note using more than 80% of the cores on your machine will likely result in performance issues.


Build the Source

To start the node, we first need to build the source. Building go-quai requires both go and a C-compiler. You can easily install a C-compiler using your favorite package manager.
After installing the dependencies, you can build via Makefile by running:
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 full or slice node depending on individual use case and hardware.

Run a Full Node

Full nodes validate all of the chains within Quai Network. To spin up a full node run:
make run-all

Run a Slice Node

In the codebase, Quai Network's blockchains are identified as regions 0-2 and zones 0-2 within each region.
Region Identification
Zone Identification
Prime - Cyprus - Cyprus1
Prime - Cyprus - Cyprus2
Prime - Cyprus - Cyprus3
Prime - Paxos - Paxos1
Prime - Paxos - Paxos2
Prime - Paxos - Paxos3
Prime - Hydra - Hydra1
Prime - Hydra - Hydra2
Prime - Hydra - Hydra3
Slice nodes validate a subset of three chains within Quai Network. When starting a slice node, you'll have to specify the specific slice you want to run. To spin up a Prime, Cyprus, and Cyprus-1 slice node, you'll need to set the region and zone values in the config file:
Then run the following command to start the slice node:
make run-slice
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 expidite the minimization of latency.
Starting a node will run all instances of go-quai in the background and create a directory named nodelogs. Outputs from the node will be piped to a context specific .log file inside of nodelogs. To view the last 100 lines of log output for a specific location, use:
tail -n 100 nodelogs/prime.log
# OR
tail -n 100 nodelogs/region-2.log
# OR
tail -n 100 nodelogs/zone-0-0.log
If you're running a slice node, logs will only populate in the contexts the slice node is validating.
Checking the node logs output is the best way to verify that your full node is running correctly. You can also easily view node logs in your favorite IDE, we recommend using this method.
The outputs of a node that is running correctly should look like:
INFO [01-30|19:55:15.397] Starting Quai 0.1.0-pre.0 on local testnet
INFO [01-30|19:55:15.414] Maximum peer count ETH=50 total=50
WARN [01-30|19:55:15.460] Disable transaction unindexing for archive node
INFO [01-30|19:55:15.460] Enabling recording of key preimages since archive mode is used
INFO [01-30|19:55:15.460] Set global gas cap cap=50,000,000
INFO [01-30|19:55:15.460] Allocated trie memory caches clean=307.00MiB dirty=0.00B
INFO [01-30|19:55:15.461] Allocated cache and file handles database=/Users/user/Library/Quai/local/zone-0-0/quai/chaindata cache=512.00MiB handles=5120
INFO [01-30|19:55:17.727] Opened ancient database database=/Users/user/Library/Quai/local/zone-0-0/quai/chaindata/ancient readonly=false
INFO [01-30|19:55:17.728] Writing custom genesis block
Depending on what your node is currently doing, your logs may not look exactly the same as above.


Stopping your node should be done any time you make changes to your config file or prior to shutting your machine down. A full node instance can be terminated by running:
make stop
This will kill all instances of go-quai on your machine. This can sometimes take a few seconds to complete.


Making sure your node is running correctly is crucial to both the functionality of any dependent infrastructure and the network as a whole.

Updating the Node

To update a node, first make sure to kill all instances of go-quai using the above stop command.
After stopping the node, you should pull any updated code using:
git pull origin main
and rebuild the source using:
make go-quai
After pulling any new code and rebuilding the source, you can safely restart the node and continue running.
Initiating the node update process while the node or manager are currently running could cause issues. Make sure to stop all processes before updating.