Run A Miner

Environment Setup

Here, we'll be installing quai-cpu-miner, the Go implementation of a Quai Network CPU miner. 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 quai-cpu-miner, you'll need to have installed and configured a Quai node. The prerequisites to install and run the miner are the same as a node. As a part of the node install, you'll be required install and configure:
  • Git - A DevOps tool used for source code management
  • Golang - A simple, statically typed language for building secure and scalable systems
If you haven't set up your node, we recommend going through the Run A Node page before proceeding.

Install quai-cpu-miner

Now that we've installed the base dependencies and configured our node, we can go ahead and clone the quai-cpu-miner repo. I recommend cloning it in the parent directory we created in the node setup tutorial.
cd path/to/quai/directory
git clone
cd quai-cpu-miner
This command checks out the main branch to your local.


Simply copy the configuration template file config.yaml.dist into a local configuration file named config.yaml. This can be done by navigating to the config directory and running:
cp config.yaml.dist config.yaml
The default configuration will suffice for the duration of this tutorial. For more advanced users, the config file can be used to set up a connection to a mining proxy for pooled mining.
Before continuing, make sure to navigate back to the quai-cpu-miner root directory.

Run the Miner

Build the Source

Similar to the node, we'll need to build the source to run the miner. You'll again need a C-compiler which can be installed with your favorite package manager.
To build the source via Makefile, run:
make quai-cpu-miner


Now that we've built the source, we can prepare to run the miner.
Prior to running the miner, you must connect to a fully synced node, either local or remote. Once you've connected to a synced node, you can spin up an instance of the miner.
Miners always mine a subset of three chains within Quai Network. When starting the miner, you'll have to specify the subset of chains you want to mine. By default, every miner secures Prime. Miners must then choose a region chain and a corresponding zone chain to mine. Start the miner with the following commands:
# run in terminal
make run-mine region=R zone=Z
# run in background, save log output
make run-mine-background region=R zone=Z
# R and Z can range from 0 to 2
When choosing which contexts to mine, there are a few important things to consider:
  • Block difficulty in each context (lower difficulty = higher chance of finding a block)
  • Peer connection latency (related to geographic distance from peers)
Optimizing for latency drastically decreases the chance of finding an uncle block for which a decreased block reward is awarded. Miners who select contexts with the lowest block difficulties in tandem with minimizing peer latencies will generally be the most successful. Our team has provided a guide to inform optimal context selection based on your geographical location for miners.


You should stop the miner anytime you plan to pull an update, stop your node for any reason, or are shutting down your machine. A miner instance running the in background can be terminated by running:
make stop
If the miner is running inside your terminal, you can use CTRL+C to kill the process.


Making sure your miner is running correctly is crucial to being successful as a miner and the network as a whole. There are a few ways to verify that your miner is running smoothly.

Verify Log Outputs

Depending on whether or not the miner is running in background, logs will be viewable in different locations.
If you're running in the terminal, logs will be piped directly to the terminal and will not be saved. If the miner is running in the background, the miner output will be piped to a mining location specific .log file with the path logs/slice-R-Z.log. To view the last 100 lines of log output in Cyprus-1, run:
tail -n 100 logs/slice-0-0.log
You can also easily view miner logs via your favorite IDE, we recommend using this method. Logs are the best way to verify that your miner is running correctly and view information on efficiency and blocks mined.
A miner that is actively mining should have log outputs similar to:
2023/01/11 12:51:23 Mining Block: [16 22 78] location [0 0] difficulty [29209917 7353733 1913341]
2023/01/11 12:51:25 Zone block : [16 22 78] 0x0000086297dd6d1f635b01e3dc3d0c27d0ed9a571ae4e3e22ba89e876e71e398
2023/01/11 12:51:25 Mining Block: [16 22 79] location [0 0] difficulty [29209917 7353733 1914275]
2023/01/11 12:51:30 Zone block : [16 22 79] 0x000007c8d5b6ce6e7958eef2e3d12524538602400d1291744358efc43f57f266
2023/01/11 12:51:30 Mining Block: [16 22 80] location [0 0] difficulty [29209917 7353733 1915209]
2023/01/11 12:51:31 Zone block : [16 22 80] 0x000008094cf87697189620a51357b54827828fb9a693cc1e082b36736a406fcd
2023/01/11 12:51:31 Mining Block: [16 22 81] location [0 0] difficulty [29209917 7353733 1915209]
2023/01/11 12:51:33 Zone block : [16 22 81] 0x000006fb38aa98adddc3a6b0e5b887a55ea21065f05a5801ddca6aca0deba290
2023/01/11 12:51:33 Mining Block: [16 22 82] location [0 0] difficulty [29209917 7353733 1916144]
2023/01/11 12:51:34 Quai Miner : Hashes per second: 734038.5899168133
The miner logs provide the current block being mined, block type, the hash/second of your machine, and a number of other useful pieces of data.

Updating the Miner

Prior to updating your miner, make sure to kill any instances of quai-cpu-miner using the stop command above. After stopping your miner, pull any new code by running:
git pull origin main
Rebuild the source using:
make quai-cpu-miner
After completing the steps above, you can restart the miner and continue mining.
Starting the miner update process while the node or miner are running could cause issues. Make sure to stop all processes before updating.