Intermediate

How to run an Avalanche Node Manually

This tutorial will guide you through the process of installing and running an Avalanche node manually. The tutorial is geared towards developers and those interested in the inner workings of the Avalanche Platform. The tutorial covers the requirements for hardware, operating system, and networking to run an Avalanche node. The tutorial will also show you how to download and build the node from source or download a pre-built binary. Finally, the tutorial will cover the steps to start a node and connect it to the Avalanche network.

To gain a quick understanding of Avalanche, running a node and interacting with the network is the best approach. This tutorial will guide you through the steps of:

  1. Installing and running an Avalanche node

  2. Connecting to the Avalanche network

Note: If you prefer using a third-party service to host your node or become a validator, explore your options.

This tutorial is primarily intended for developers and individuals who want to comprehend how the Avalanche platform operates. If your main goal is to set up a node for staking, we suggest following the “Set Up Avalanche Node with Installer” tutorial instead. The installer streamlines the installation process and sets it up as a system service, making it ideal for non-attended operation. Alternatively, you can first follow this tutorial for hands-on experience, and later switch to using the installer for a permanent setup.

Requirements

Computer Hardware and OS

Avalanche is an incredibly lightweight protocol, so nodes can run on commodity hardware. Note that as network usage increases, hardware requirements may change.

  • CPU: Equivalent of 8 AWS vCPU

  • RAM: 16 GiB

  • Storage: 1 TiB

  • OS: Ubuntu 20.04 or MacOS >= 12

Networking

To run successfully, AvalancheGo needs to accept connections from the Internet on the network port 9651. Before you proceed with the installation, you need to determine the networking environment your node will run in.

Running on a Cloud Provider

If your node is running on a cloud provider computer instance, it will have a static IP. Find out what that static IP is, or set it up if you didn’t already.

Running on a Home Connection

If you’re running a node on a computer that is on a residential internet connection, you have a dynamic IP; that is, your IP will change periodically. You will need to set up inbound port forwarding of port 9651 from the internet to the computer the node is installed on.

As there are too many models and router configurations, we cannot provide instructions on what exactly to do, but there are online guides to be found (like this, or this ), and your service provider support might help too.

DANGER

Please note that a fully connected Avalanche node maintains and communicates over a couple of thousand of live TCP connections. For some low-powered and older home routers that might be too much to handle. If that is the case you may experience lagging on other computers connected to the same router, node getting benched, failing to sync and similar issues.

Run an Avalanche Node

Let’s install AvalancheGo, the Golang implementation of an Avalanche node, and connect to the Avalanche primary network.

Download AvalancheGo

The node is a binary program. You can either download the source code and then build the binary program, or you can download the pre-built binary. You don’t need to do both.

Downloading pre-built binary is easier and recommended if you’re just looking to run your own node and stake on it.

Building the node from source is recommended if you’re a developer looking to experiment and build on Avalanche.

Source Code

First install Go 1.18.1 or later. Follow the instructions here. You can verify by running go version.

Set $GOPATH environment variable properly for Go to look for Go Workspaces. Please read this for details. You can verify by running echo $GOPATH.

Download the AvalancheGo repository into your $GOPATH:

cd $GOPATH
mkdir -p src/github.com/ava-labs
cd src/github.com/ava-labs
git clone git@github.com:ava-labs/avalanchego.git
cd avalanchego

 

Note: This checkouts to the master branch. For the latest stable version, checkout the latest tag.

Build AvalancheGo:

./scripts/build.sh

 

The binary, named avalanchego, is in avalanchego/build. If you’ve followed the instructions so far, this will be within your $GOPATH at: $GOPATH/src/github.com/ava-labs/avalanchego/build.

To begin running AvalancheGo, run the following (hit Ctrl+C to stop your node):

./build/avalanchego

 

Binary

If you want to download a pre-built binary instead of building it yourself, go to our releases page, and select the release you want (probably the latest one.)

Under Assets, select the appropriate file.

For MacOS: Download: avalanchego-macos-<VERSION>.zip Unzip: unzip avalanchego-macos-<VERSION>.zip The resulting folder, avalanchego-<VERSION>, contains the binaries.

For Linux on PCs or cloud providers: Download: avalanchego-linux-amd64-<VERSION>.tar.gz Unzip: tar -xvf avalanchego-linux-amd64-<VERSION>.tar.gz The resulting folder, avalanchego-<VERSION>-linux, contains the binaries.

For Linux on RaspberryPi4 or similar Arm64-based computers: Download: avalanchego-linux-arm64-<VERSION>.tar.gz Unzip: tar -xvf avalanchego-linux-arm64-<VERSION>.tar.gz The resulting folder, avalanchego-<VERSION>-linux, contains the binaries.

Start a Node, and Connect to Avalanche

If you built from source:

./build/avalanchego

 

If you are using the pre-built binaries on MacOS:

./avalanchego-<VERSION>/build/avalanchego
 

If you are using the pre-built binaries on Linux:

 
./avalanchego-<VERSION>-linux/avalanchego

 

By default (without specifying any parameters), this node will connect to the Mainnet which may take much longer time to finish bootstrapping. See this for connecting to Fuji Testnet.

When the node starts, it has to bootstrap (catch up with the rest of the network). You will see logs about bootstrapping. When a given chain is done bootstrapping, it prints logs like this:

[09-09|17:01:45.295] INFO <C Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2qaFwDJtmCCbMKP4jRpJwH8EFws82Q2yC1HhWgAiy3tGrpGFeb"}
[09-09|17:01:46.199] INFO <P Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2ofmPJuWZbdroCPEMv6aHGvZ45oa8SBp2reEm9gNxvFjnfSGFP"}
[09-09|17:01:51.628] INFO <X Chain> avalanche/transitive.go:334 consensus starting {"lenFrontier": 1}

 

To check if a given chain is done bootstrapping, in another terminal window call info.isBootstrapped by copying and pasting the following command:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info

 

If this returns true, the chain is bootstrapped; otherwise, it returns false. If you make other API calls to a chain that is not done bootstrapping, it will return API call rejected because chain is not done bootstrapping. If you are still experiencing issues please contact us on Discord.

Your node is running and connected now. If you want to use your node as a validator on the main net, check out this tutorial to find out how to add your node as a validator using the web wallet.

You can use Ctrl + C to kill the node.

To be able to make API calls to your node from other machines, when starting up the node include argument --http-host= (for example ./build/avalanchego --http-host=)

Connect to Fuji Testnet

To connect to the Fuji Testnet instead of the Mainnet, use argument --network-id=fuji. You can get funds on the Testnet from the faucet.