Skip to content

Running a HyperBEAM Node

This guide provides the basics for running your own HyperBEAM node, installing dependencies, and connecting to the AO network.

System Dependencies

To successfully build and run a HyperBEAM node, your system needs several software dependencies installed.

Install core dependencies using Homebrew:

brew install cmake git pkg-config openssl ncurses

Install core dependencies using apt: 

sudo apt-get update && sudo apt-get install -y --no-install-recommends \
    build-essential \
    cmake \
    git \
    pkg-config \
    ncurses-dev \
    libssl-dev \
    sudo \
    curl \
    ca-certificates

Using the Windows Subsystem for Linux (WSL) with a distribution like Ubuntu is recommended. Follow the Linux (Debian/Ubuntu) instructions within your WSL environment.

Erlang/OTP

HyperBEAM is built on Erlang/OTP. You need a compatible version installed (check the rebar.config or project documentation for specific version requirements, typically OTP 27).

Installation methods:

brew install erlang

sudo apt install erlang

Download from erlang.org and follow the build instructions for your platform.

Rebar3

Rebar3 is the build tool for Erlang projects.

Installation methods:

brew install rebar3

Get the rebar3 binary from the official website. Place the downloaded rebar3 file in your system's PATH (e.g., /usr/local/bin) and make it executable (chmod +x rebar3).

Node.js

Node.js might be required for certain JavaScript-related tools or dependencies.

Installation methods:

brew install node

# Check your distribution's recommended method, might need nodesource repo
sudo apt install nodejs npm

asdf-vm with the asdf-nodejs plugin is recommended. 

asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
asdf install nodejs <version> # e.g., lts
asdf global nodejs <version>

Rust

Rust is needed if you intend to work with or build components involving WebAssembly (WASM) or certain Native Implemented Functions (NIFs) used by some devices (like ~snp@1.0).

The recommended way to install Rust on all platforms is via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env" # Or follow the instructions provided by rustup

Prerequisites for Running

Before starting a node, ensure you have:

Starting a Basic Node

The simplest way to start a HyperBEAM node for development or testing is using rebar3 from the repository's root directory:

rebar3 shell

This command:

  1. Starts the Erlang Virtual Machine (BEAM) with all HyperBEAM modules loaded.
  2. Initializes the node with default settings (from hb_opts.erl).
  3. Starts the default HTTP server (typically on port 10000), making the node accessible via HyperPATHs.
  4. Drops you into an interactive Erlang shell where you can interact with the running node.

This basic setup is suitable for local development and exploring HyperBEAM's functionalities.

Optional Build Profiles

HyperBEAM uses build profiles to enable optional features, often requiring extra dependencies. To run a node with specific profiles enabled, use rebar3 as ... shell:

Available Profiles (Examples):

  • genesis_wasm: Enables Genesis WebAssembly support.
  • rocksdb: Enables the RocksDB storage backend.
  • http3: Enables HTTP/3 support.

Example Usage:

# Start with RocksDB profile
rebar3 as rocksdb shell

# Start with RocksDB and Genesis WASM profiles
rebar3 as rocksdb, genesis_wasm shell

Note: Choose profiles before starting the shell, as they affect compile-time options.

Node Configuration

HyperBEAM offers various configuration options (port, key file, data storage, logging, etc.). These are primarily set using a config.flat file and can be overridden by environment variables or command-line arguments.

See the dedicated Configuring Your HyperBEAM Node guide for detailed information on all configuration methods and options.

Verify Installation

To quickly check if your node is running and accessible, you can send a request to its ~meta@1.0 device (assuming default port 10000):

curl http://localhost:8734/~meta@1.0/info

A JSON response containing node information indicates success.

Running for Production (Mainnet)

While you can connect to the main AO network using the rebar3 shell for testing purposes (potentially using specific configurations or helper functions like hb:start_mainnet/1 if available and applicable), the standard and recommended method for a stable production deployment (like running on the mainnet) is to build and run a release.

1. Build the Release:

From the root of the HyperBEAM repository, build the release package. You might include specific profiles needed for your mainnet setup (e.g., rocksdb if you intend to use it):

# Build release with default profile
rebar3 release

# Or, build with specific profiles (example)
# rebar3 as rocksdb release

This command compiles the project and packages it along with the Erlang Runtime System (ERTS) and all dependencies into a directory, typically _build/default/rel/hb.

2. Configure the Release:

Navigate into the release directory (e.g., cd _build/default/rel/hb). Ensure you have a correctly configured config.flat file here. See the configuration guide for details on setting mainnet parameters (port, key file location, store path, specific peers, etc.). Environment variables can also be used to override settings in the release's config.flat when starting the node.

3. Start the Node:

Use the generated start script (bin/hb) to run the node:

# Start the node in the foreground (logs to console)
./bin/hb console

# Start the node as a background daemon
./bin/hb start

# Check the status
./bin/hb ping
./bin/hb status

# Stop the node
./bin/hb stop

Consult the generated bin/hb script or Erlang/OTP documentation for more advanced start-up options (e.g., attaching a remote shell).

Running as a release provides a more robust, isolated, and manageable way to operate a node compared to running directly from the rebar3 shell.

Stopping the Node (rebar3 shell)

To stop the node running within the rebar3 shell, press Ctrl+C twice or use the Erlang command q()..

Next Steps