go-quai: building and running a Quai Network node in Go

What Go Quai is for, and who ends up running it

Go Quai is the reference implementation of the Quai protocol, written in Go. That single sentence from the README sets the audience: people who need a Quai node rather than a Quai wallet. The repository is the client, not an application. It carries the consensus, p2p, core, trie, rpc, stratum and quaiclient packages that a chain client needs, and it exposes a start subcommand rather than a graphical interface.

The practical users are node operators, miners, and developers integrating against Quai. Miners matter here because the README's own run example is a mining command, and the repository contains a stratum directory, which is the protocol mining hardware speaks. If you are looking for something to install on a laptop and click, this is not that project. The README offers no installer and no release binary instructions; it offers a clone, a make target and a start command.

How the client is put together: subsystems and the config directory

The top-level layout is the clearest documentation of the architecture. consensus, core, trie, ethdb and rlp form the state and chain layer. p2p holds networking, and go.mod shows libp2p components (go-libp2p-kad-dht, go-libp2p-pubsub) rather than a hand-rolled gossip layer. rpc and quaiclient sit at the API boundary, and stratum is the mining endpoint. quaistats and metrics_config point at reporting.

Slices are the concept a new operator meets first, because the start command requires them. The README's example passes node.slices "[0 0]" for a node in cyprus-1 (zone-0-0). That value is a two-element list, so the node is being told which part of the network hierarchy it participates in, not merely which chain to follow. The same command sets node.coinbases, the address that receives mining rewards, and node.environment, which selects the network.

Configuration is not command-line only. The README states that all options may be supplied in a config file located in the directory given by --global.config-dir, and that command-line values override the file. That ordering is worth internalising before you debug a node: a flag you thought you set can be correct while the running process uses a file value, or the reverse.

Building go-quai from source and starting a garden node

The README's build path assumes prerequisites it links to but does not restate. Once those are present, clone the repository and build with the Makefile target. The Makefile routes this through build/ci.go, so the build is not a bare go build.

git clone https://github.com/dominant-strategies/go-quai.git
cd go-quai
make go-quai

On success the binary lands at build/bin/go-quai. The Makefile also defines a debug target that builds with -gcflags=all="-N -l", which is useful when you need a debuggable binary rather than an optimised one.

Starting a node means choosing slices, a coinbase and an environment. The README's example is a miner in cyprus-1 (zone-0-0) on the garden test network.

./build/bin/go-quai start --node.slices "[0 0]" --node.coinbases "0x00a3e45aa16163F2663015b6695894D918866d19" --node.environment "garden"

If you are not mining, the coinbase argument is the part to reconsider before copying the line. The README describes it as the parameter to specify "if you plan on mining", and the address in the example belongs to someone else. Note also that the help invocation in the README is written as ./build/go-quai --help, while the binary path given everywhere else is ./build/bin/go-quai. Use the build/bin path.

For the full option list and defaults, run the help menu.

./build/bin/go-quai --help

The repository also has a test entry point. The README gives it as ./build/go-quai test, and the same path correction applies.

./build/bin/go-quai test

The Dockerfile, its build argument, and the ports it opens

The Dockerfile is a two-stage build: golang:1.23-alpine compiles with make go-quai, then the binary is copied into a plain alpine:latest runtime image along with VERSION, params/genesis_alloc.json and params/forfeiture_addresses.json. Those last two files are copied explicitly, which tells you the runtime needs genesis allocation and forfeiture address data present on disk.

The network is a build-time argument, ARG NETWORK=colosseum, and also a runtime environment variable, ENV QUAI_ENVIRONMENT=colosseum. The Dockerfile comment enumerates the accepted values as colosseum, garden, orchard, lighthouse and local. That is a wider set than the README's run example, which only demonstrates garden. Because the argument is consumed at build time and the environment variable at run time, an image built for one network and started with another environment variable is a configuration mismatch the Dockerfile does not prevent.

The image exposes 4002/tcp, 4002/udp, 8001, 8002, 8200, 9001, 9002 and 9200, and its entry point runs the binary with the start subcommand. There is also a .dockerignore in the repository, so the build context is trimmed. The Dockerfile does not copy any config file into the image, so a containerised node relies on flags or on a config directory you mount yourself.

Where go-quai is the wrong tool, and what to use instead

Go Quai is a full node client. It is the wrong choice when you want to read chain data without operating infrastructure, when you need a hosted endpoint, or when you cannot give the process a persistent data directory and open inbound ports. The Dockerfile's exposed port list is a fair picture of what a node expects from its network environment.

The honest alternative inside this repository is quaiclient. It is a separate top-level package, and it exists precisely for the case where you want to talk to a Quai node from Go rather than be one. The difference in approach is the difference between running consensus and consuming it: go-quai maintains state, participates in p2p and can serve stratum work, while quaiclient is the client side of that boundary. If your goal is an application that queries Quai, building go-quai and pointing quaiclient at a node is a lighter path than treating your application host as a node.

Compared with a general-purpose Ethereum toolchain, the split is different again. Go Quai carries its own consensus, p2p and stratum packages, and its configuration is organised around slices and environments. Tooling written against Ethereum's client conventions will not map onto the node.slices and node.environment flags, so familiarity with an Ethereum node does not transfer to the command line here.

Maintenance cadence, licence, and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-09. Release v0.56.0 was tagged the same day, following v0.55.0 on 2026-06-25 and v0.54.0 on 2026-06-08. That is a real cadence, and it means an operator should expect to rebuild rather than treat a deployment as finished. The README documents no upgrade procedure, no migration steps and no rollback path, so the mechanics of moving between tagged releases are not described in the documentation available here.

The licence is GPL-3.0, stated in the README and present as a LICENSE file. For anyone embedding this code in another product, that is a copyleft licence with distribution obligations, and the practical consequence is that linking it into a proprietary binary is a question for your own counsel rather than something this article can settle. Running a node as a service is a different situation from redistributing a modified client, and the distinction is worth raising before you fork. The README asks contributors to read CONTRIBUTING.md, which is the place to look if you intend to send changes upstream rather than carry a private patch set.

Editorial conclusion

Adopt go-quai if you need a Quai node, a miner-facing endpoint, or the reference client for protocol work; the last push was on 2026-09-09 and v0.56.0 shipped the same day. Do not adopt it if you want a packaged installer, because the README starts and ends at building from source, and do not run it on a machine you cannot rebuild from a clean checkout. Verify first that your Go toolchain satisfies the go 1.24 directive in go.mod, that the node.slices and node.coinbases values you pass match the network you intend to join, and that your build host has the prerequisites the README points to before you run make go-quai.

Frequently asked questions

Official sources

1. dominant-strategies/go-quai on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases