Running Your Own Avalanche Node in Go and Understanding the Network Architecture

Setting up an Ethereum or Bitcoin node from scratch is no quick task. You have to download hundreds of gigabytes of data and wait weeks for synchronization. The Avalanche developers take a slightly different approach, though you still shouldn't expect a walk in the park.

The official Avalanche network node implementation in Go is available in the avalanchego repository. This is the core component of the entire project infrastructure. Without it, you won't be able to run a validator or deploy a private test network.

What You Need to Get Started

Developers call the hardware requirements modest, but the numbers in the README suggest otherwise. For Mainnet operation, you'll need:

• 8 vCPU
• 16 GB RAM
• 1 TB of free disk space
• Ubuntu (22.04/24.04) or macOS 12+

The main bottleneck during the first startup occurs during the bootstrapping phase. The node downloads the network history and verifies the state. This process takes several days. The main constraint is disk I/O speed (IOPS). If you use a regular HDD or a slow SSD, the process will drag on for a long time, so an NVMe drive is practically mandatory here.

How to Build and Run the Client

There are several installation options. For Ubuntu, an official APT repository is available, so you can install the utility through the standard package manager.

If you want to build the binary from source code, you'll need Go version 1.25.10 or newer, as well as gcc and g++. The build process takes just a couple of steps:

git clone [email protected]:ava-labs/avalanchego.git
cd avalanchego
./scripts/run_task.sh build

The compiled binary appears in the build directory. Running without parameters connects the node to the Mainnet:

./build/avalanchego

To connect to the Fuji test network, add one flag:

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

If you don't want to clutter your operating system with dependencies, it's easier to build a Docker image:

./scripts/run-task.sh build-image
docker run -ti -p 9650:9650 -p 9651:9651 avaplatform/avalanchego:latest /avalanchego/build/avalanchego

Ports 9650 and 9651 handle HTTP API and P2P connections between nodes.

Platform Support and Code Generation

The team's approach to operating system support is quite strict. Platforms are divided into three tiers.

Tier 1 includes 64-bit Linux systems on amd64 and arm64 architectures. Full e2e and stress tests are run for them.

Tier 2 includes macOS on Apple Silicon chips (arm64). Here, passing module and integration tests is guaranteed, but e2e tests are not claimed. macOS on Intel processors, as well as Windows, are not officially supported.

The project actively uses gRPC and Protobuf. If you plan to make changes to the protocol, you'll need to install buf, protoc-gen-go and run the internal generation script:

scripts/run_task.sh generate-protobuf

Development in a Local Environment

Running terabytes of data for local development and smart contract debugging doesn't make sense. For such tasks, the team offers a separate utility avalanche-cli. It spins up a local environment in literally two commands:

avalanche network start
avalanche network status

This saves hours of time since you don't have to wait for initial synchronization with public networks.

Conclusion

AvalancheGo is solid source code for anyone diving into Avalanche infrastructure. The code is open under the BSD-3 license, and the repository is active with regular updates. If you're building services around this blockchain or planning to run your own validator, studying this repository is definitely worth it.