Documentation Index
Fetch the complete documentation index at: https://docs.paxeer.app/llms.txt
Use this file to discover all available pages before exploring further.
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.
- Log in as Root: Most commands require administrative privileges.
- Verify Shell Path: If you just installed the OS or shell updates, ensure your shell knows where to look for commands:
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:
-
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
-
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.
- The Setup Command:
Type
hpx setup to begin.
- Storage Location:
When asked
Where to store node data? [/root/hyperpax-nodes], simply Press Enter to use the default path.
- 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.
- Get your IP and Port:
Find your node’s connection string. It usually looks like this:
http://[YOUR_IP_ADDRESS]:[PORT].
- 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
- Checks system resources (RAM, CPU, disk)
- Installs Docker, curl, jq, zstd if missing
- Installs the
hpx binary to /usr/local/bin/
- Offers to run the Setup Wizard (system tuning, Docker image pull, capacity check)
Deploy a Node
| 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 |
hpx deploy my-rpc rpc
hpx deploy mainnet-val validator
| 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 evmosd binary inside the container:
evmosd tx staking create-validator \
--amount=1000000ahpx \
--pubkey=$(evmosd 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):
evmosd tx slashing unjail \
--from=<key_name> \
--chain-id=hyperpax_125-1
Confirm Validator Status
evmosd query tendermint-validator-set | grep "$(evmosd tendermint show-address)"
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
.png?fit=max&auto=format&n=6XYIkDjUrWNzW_la&q=85&s=940e0b626eac0ac66b4f36fa20462022)
