Run a Node

Deploy RPC and Validator nodes on HyperPaxeer using the hpx CLI

Overview

The hpx CLI manages the full lifecycle of HyperPaxeer nodes — install, deploy, monitor, upgrade, and remove. Each node runs as an isolated Docker Compose stack with its own chain data, ports, and an FD Guardian sidecar that auto-restarts on file-descriptor leaks.

---

🚀 HyperPax Node: The Official “No-Headache” Setup Guide

Setting up a node involves preparing your server, installing the HyperPax OS, and ensuring your node is visible for delegation. Follow these steps exactly to avoid the common command not found or Docker missing errors.

Phase 1: Server Preparation

Before running the main script, ensure your environment is clean.

1. Log in as Root: Most commands require administrative privileges.
2. Verify Shell Path: If you just installed the OS or shell updates, ensure your shell knows where to look for commands:
   source ~/.bashrc
   
   Note: If you get a “No such file” error, don’t panic. It just means you are using a clean shell that hasn’t been modified yet.

---

Phase 2: Installing HyperPax-OS

Run the installation script provided by the team.

• Pro Tip: If the script asks to install Docker and seems “stuck,” wait. Docker installation can take 2–5 minutes depending on the server’s CPU and network speed.

🛠 Troubleshooting Common Install Errors

If the installer fails on Step 2/6 (Checking Dependencies) with a Missing: docker-compose-plugin error:

1. Manual Docker Compose Fix: Run these commands one by one to manually place the plugin where the system expects it:

   mkdir -p ~/.docker/cli-plugins
   curl -SL https://github.com/docker/compose/releases/download/v5.1.2/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose
   chmod +x ~/.docker/cli-plugins/docker-compose
   

2. System Tuning: The script may ask: Apply recommended system tuning? [y/N].

   • Always Choose Y. * If you skip this, your node may hit “FD (File Descriptor) limits” and crash once the network load increases.

---

Phase 3: Configuration & Data Sync

Once the OS is installed, you need to configure your node.

1. The Setup Command: Type hpx setup to begin.
2. Storage Location: When asked Where to store node data? [/root/hyperpax-nodes], simply Press Enter to use the default path.
3. Syncing the Chain: You will see a prompt for a Chain data tarball URL.
   • Unless you have been given a specific private link by the team, Press Enter to use the latest official snapshot.

---

Phase 4: Activation & Delegation

Your node is running, but it needs “Voting Power” to earn rewards.

1. Get your IP and Port: Find your node’s connection string. It usually looks like this: http://[YOUR_IP_ADDRESS]:[PORT].
2. Send to the Registry: Provide this URL to the network admin. This allows them to:
   • Add you to the official Registry.
   • Delegate staked coins to your node so you can begin validating blocks.

---

💡 Top 3 “Newbie” Tips from the Logs:

• Don’t Spam Commands: If you run the “longer script” multiple times, you might create conflicting directory paths (e.g., /usr/bin/ vs /root/). Run it once and troubleshoot specific errors instead.
• The “hpx” Command: If hpx isn’t found immediately after installation, try running source ~/.bashrc again or logging out and back into your SSH session.
• Docker is Heavy: If the screen says Installing Docker..., grab a coffee. Interrupting this process is the #1 cause of broken node environments.

---

Requirements

Resource	Minimum
RAM	16 GB
CPU	6 cores
Disk	300 GB (SSD recommended)
OS	Ubuntu 22.04+

---

Install

curl -sSL https://hyperpaxeer.com/hyper-os/new/get-hpx.sh | sudo bash

The installer:

1. Checks system resources (RAM, CPU, disk)
2. Installs Docker, curl, jq, zstd if missing
3. Installs the hpx binary to /usr/local/bin/
4. Offers to run the Setup Wizard (system tuning, Docker image pull, capacity check)

---

Deploy a Node

hpx deploy <name> <type>

Type	Purpose	Configuration
rpc	Serve JSON-RPC, gRPC, REST, WebSocket	Full indexing, all endpoints exposed
validator	Produce blocks, participate in consensus	Default pruning, optimised for consensus

Examples:

hpx deploy my-rpc rpc
hpx deploy mainnet-val validator

The CLI assigns ports automatically. Multiple nodes on one server get auto-incremented ports:

Protocol	Node 1	Node 2	Node 3
P2P	26656	26756	26856
CometBFT RPC	26657	26757	26857
REST API	1317	1417	1517
gRPC	9090	9190	9290
JSON-RPC	8545	8645	8745
WebSocket	8546	8646	8746

---

Node Management

Command	Purpose
hpx	Interactive menu
hpx list	List all registered nodes
hpx info <name>	Sync status, block height, peers
hpx logs <name>	Stream node logs
hpx start <name>	Start a node
hpx stop <name>	Stop a node
hpx restart <name>	Restart a node
hpx start all	Start all nodes
hpx stop all	Stop all nodes
hpx remove <name>	Delete a node and its data
hpx dashboard	Live status dashboard
hpx capacity	Show server resource usage
hpx setup	Re-run the setup wizard

---

File Structure

/root/hyperpax-nodes/
  .hpx-registry              # tracks all nodes
  .hpx-setup-done            # setup wizard completion marker
  my-rpc/
    data/                     # chain data + config
    scripts/                  # start script + FD guardian
    logs/                     # guardian logs
    docker-compose.yml        # isolated compose stack

---

Create a Validator

After your node syncs to the latest block, create a validator using the hyperpaxd binary inside the container:

hyperpaxd tx staking create-validator \
  --amount=1000000ahpx \
  --pubkey=$(hyperpaxd tendermint show-validator) \
  --moniker="your-moniker" \
  --chain-id=hyperpax_125-1 \
  --commission-rate="0.05" \
  --commission-max-rate="0.10" \
  --commission-max-change-rate="0.01" \
  --min-self-delegation="1000000" \
  --gas="auto" \
  --gas-prices="0.025ahpx" \
  --from=<key_name>

Ensure your server timezone is UTC. A different timezone can cause LastResultsHash mismatch errors that halt your node.

---

Unjail a Validator

If your validator is jailed for downtime (missing 500 of the last 10,000 blocks):

hyperpaxd tx slashing unjail \
  --from=<key_name> \
  --chain-id=hyperpax_125-1

---

Confirm Validator Status

hyperpaxd query tendermint-validator-set | grep "$(hyperpaxd tendermint show-address)"

Or check the Network Status page for the current validator set.

---

Troubleshooting

“Permission denied” — Run with sudo.

“docker: denied” — Stale credentials. Run docker logout ghcr.io and retry.

“Cannot connect to Docker daemon” — Start Docker: sudo systemctl start docker.

Node stuck syncing — Check peers with hpx info <name>. If peers is 0, verify your firewall allows the P2P port.

“too many open files” — The FD Guardian sidecar handles this automatically. If running outside Docker, increase limits: ulimit -n 4096.

---

Update

Re-run the installer to update to the latest version. Existing nodes and chain data are preserved:

curl -sSL https://hyperpaxeer.com/hyper-os/new/get-hpx.sh | sudo bash

---

Uninstall

curl -sSL https://hyperpaxeer.com/hyper-os/new/uninstall.sh | sudo bash