AvalancheGo: running an Avalanche node from source, APT or Docker

What AvalancheGo actually is, and who runs it

This is the reference client for the Avalanche network written in Go, not a library you import to add a feature to an application. It connects to Mainnet or Fuji, participates in consensus once it has caught up, and exposes the node APIs. The people who need it are operators: validators, RPC providers, and teams that need a local testnet to develop against. The README's minimum specification for a Mainnet node is 8 AWS vCPU equivalents, 16 GiB of RAM and 1 TiB of storage, on Ubuntu 22.04 or 24.04, or macOS 12 and later, with a reliable IPv4 or IPv6 connection and an open public port. That storage figure is not a ceiling. The README warns that nodes running for very long periods, or nodes with custom configurations, may see higher requirements. Treat 1 TiB as the floor for a fresh node, not a budget for the next two years.

Bootstrapping is the real cost of entry

A new node cannot serve API calls or take part in consensus until it has caught up to the latest network state. The README states this process currently takes several days on Mainnet, and that a node will not report healthy until it finishes. The bottleneck is database IO, so a faster CPU or higher database IOPS shortens the wait more than extra RAM does. This is the constraint that decides whether AvalancheGo fits your project. If you need a queryable node this afternoon, a hosted RPC endpoint is the correct answer and a self-run node is not. The README also notes that improvements to bootstrap time are under development, which is a statement about intent, not a shipped feature. Plan around the current behaviour.

Building AvalancheGo from source with Go 1.25.10

Building from source needs Go version 1.25.10 or newer, plus gcc and g++. The repository also carries Bazel files (BUILD.bazel, MODULE.bazel, .bazelrc) and a Taskfile.yml, but the README documents the task script path. Clone the repository and run the build task:

git clone git@github.com:ava-labs/avalanchego.git
cd avalanchego
./scripts/run_task.sh build

The clone checks out the master branch. The build writes an `avalanchego` binary into the `build` directory. Run it directly:

./build/avalanchego

With no flags, that connects to Mainnet and prints ASCII art and log messages. Ctrl+C stops the node. For the Fuji testnet, pass the network flag instead:

./build/avalanchego --network-id=fuji

The README does not document a rollback procedure for a bad node upgrade, so keep the previous binary and your database directory before replacing anything.

APT and Docker installation paths

On Ubuntu, the project publishes an APT repository, which avoids a Go toolchain entirely. The README gives these steps, run as root, which fetch the signing key and write the list file using your Ubuntu codename:

sudo su -
wget -qO - https://downloads.avax.network/avalanchego.gpg.key | tee /etc/apt/trusted.gpg.d/avalanchego.asc
source /etc/os-release && echo "deb https://downloads.avax.network/apt $UBUNTU_CODENAME main" > /etc/apt/sources.list.d/avalanche.list
exit

After that, `sudo apt update` then `sudo apt install avalanchego` installs the client. There is also a binary download page for the latest release per operating system and architecture, and the executable is named `avalanchego`. The Docker route builds an image from the current branch with `./scripts/run_task.sh build-image`, tagged as `avaplatform/avalanchego:xxxxxxxx` where the suffix is the shortened commit. The README's run command maps the API and staking ports explicitly:

docker run -ti -p 9650:9650 -p 9651:9651 avaplatform/avalanchego:xxxxxxxx /avalanchego/build/avalanchego

The Dockerfile takes the Go version as a build argument rather than hard-coding it, and configures a cross-compiler when the target platform differs from the build platform. That matters if you build arm64 images on an amd64 host.

A local testnet is a different tool

The README points at avalanche-cli as the easiest way to start a local network, and gives two commands: `avalanche network start` followed by `avalanche network status`. That is a separate repository and a separate binary. If your goal is contract development or integration testing, this path is far cheaper than syncing a Mainnet node, and it does not carry the multi-day bootstrap cost. The mistake to avoid is treating a locally started network as representative of Mainnet conditions. It is not, and the README makes no such claim.

Versioning, modules and API stability

The version scheme tracks the network, not the codebase. The README explains that v0.x.x denotes a development network version, v1.x.x a production network version, the second number is the count of network upgrades, and the patch number counts client upgrades since the last network upgrade. This has a direct consequence for anyone consuming AvalancheGo as a dependency: because the version denotes the network, the README states that interfaces exported by AvalancheGo's packages may change in Patch version updates. AvalancheGo is organized as multiple Go modules that must be consumed together at matching versions, and the repository has a separate document, docs/external_consumption.md, for that case. The API side is a different story. APIs exposed when running the node maintain backwards compatibility unless functionality is explicitly deprecated and announced when removed. So the running node is a stable integration surface, while the Go packages are not. Choose your integration point accordingly.

Licence and ongoing upgrade cost

AvalancheGo is BSD-3-Clause. That is a permissive licence, and it is the same family used by the Go standard library, so redistribution inside a product is normally acceptable. Check the LICENSE file for the exact terms and the copyright holder rather than relying on the identifier alone, and take legal advice if you are embedding the node in a commercial product. The upgrade cost is the part operators underestimate. Patch releases ship client changes between network upgrades, and the README's own go.mod comments show that a Go version bump requires touching CONTRIBUTING.md, README.md, RELEASES.md and nix/go/default.nix by hand. If you build from source, you own that chain. The APT and Docker paths move the toolchain problem to the maintainers, but you still need a process for restarting a node that is mid-bootstrap, and the README does not document one.

Where AvalancheGo is the wrong choice

Do not reach for it when you only need to read chain data. A hosted RPC endpoint answers queries without a 1 TiB disk or a multi-day sync. Do not build it from source on a workstation to try it out; the APT repository or a release binary gets you the same executable in minutes. Do not treat it as a general-purpose Go library for blockchain logic, because the README explicitly warns that exported interfaces can change in patch updates and that the modules must move in lockstep. And do not run it on a machine without an open public port: the README lists a public port as part of the minimum specification, so a node behind a closed firewall is not a supported deployment. The code generation tooling is another boundary. Regenerating protobuf code requires buf v1.31.0, protoc-gen-go v1.33.0 and protoc-gen-go-grpc v1.3.0, and the README says this should only be necessary when upgrading protobuf versions or editing .proto files. If you are not changing those files, you do not need that toolchain.

Editorial conclusion

Adopt AvalancheGo if you need a Mainnet or Fuji node, a local testnet via avalanche-cli, or the node APIs behind a validator. Do not adopt it as a Go library: the README states that exported package interfaces may change in Patch updates, and the modules must be consumed at matching versions. Before committing hardware, verify the 8 vCPU, 16 GiB RAM and 1 TiB storage minimum against your own growth, and check the health endpoint after bootstrapping rather than assuming the node is usable.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes