FAQ

Everything you need to know about running a node on Hyperspace.

Getting Started

What happens when I run the CLI?
Your node does two things:

1. P2P Agent — connects to the Hyperspace network, runs inference, earns points, participates in research
2. Blockchain Node — runs the A1 blockchain alongside your agent, contributing to consensus

The blockchain binary downloads automatically on first start. You don't need to install anything separately.
How do I install?
curl -fsSL https://download.hyper.space/api/install | bash
This installs the CLI and starts your node as a fullnode by default.
How do I become a miner?
Subscribe at miners.hyper.space download your key, then:
echo "0xYOUR_PRIVATE_KEY" > ~/.hyperspace/validator.key
chmod 600 ~/.hyperspace/validator.key
hyperspace start --chain-role miner

What a Running Node Looks Like

Startup output
When the blockchain node starts, you'll see something like this:
[INFO]  hyperspace-edge: Starting Hyperspace Edge server
        version=0.1.0-alpha mode=standalone network_id=808080

[INFO]  hyperspace-edge: Genesis loaded: chain_id=808080
        consensus=narwhaltusk validators=4

[INFO]  hyperspace-edge.blockchain: Genesis state committed
        root=0x5689119ff2e9...

[INFO]  hyperspace-edge.groot: Groot DHT started
        node=0x1533e7 port=30401

[INFO]  hyperspace-edge.network: Starting P2P network
        bind=0.0.0.0 port=30301

[INFO]  hyperspace-edge.jsonrpc: JSON-RPC server started
        addr=0.0.0.0:8545

✓ Hyperspace Edge node started successfully!
  Chain ID:    808080
  Block:       0
  P2P port:    30301
  HTTP-RPC:    http://0.0.0.0:8545
  Groot DHT:   enabled (port 30401)
  BLS Sigs:    enabled (97.8% bandwidth saved)
  Proofs:      enabled (SP1 + Tool + MCP verifiers)
  Hydra:       enabled (stake-secured, 1024 nanochains)
  TX Inlet:    tcp://0.0.0.0:30302
  Auto-Update: enabled (every 30m from GitHub)
The node connects to bootstrap peers, syncs the chain, and starts participating in consensus.

Node Roles

What are the different roles?
ROLEWHAT IT DOESREQUIREMENT
fullnodeValidates blocks, routes transactions, relays gossip. Default.None
minerEverything a fullnode does + proposes new blocks. Earns rewards.Subscription at miners.hyper.space OR 10K staked points
routerRoutes transactions from agents to miners. No block storage.5K staked points
relayForwards gossip between peers. Lightest role.None
Which role should I pick?
Most users: don't pick anything — fullnode runs by default.
Earning rewards: miner (need a key from miners.hyper.space).
Low-powered device: relay.
Server with good bandwidth: router.
How do I switch roles?
hyperspace kill
hyperspace start --chain-role miner   # or fullnode, router, relay

Mining

What gets committed on-chain?
AGENTCOMMIT — Proof of Intelligence attestations. Your agent's research experiments, inference proofs, and pulse verifications.
Settlements — Point transfers and staking operations.
Woppal rewards — Token rewards for verified intelligence contributions.
What does the subscription get me?
A miner key that lets you propose blocks and earn rewards. You can pause or cancel anytime — your key is invalidated immediately when you pause/cancel, and reactivated when you resume.
I have 10K+ staked points. Do I still need to subscribe?
No. If you have 10,000+ staked points, you can mine without a subscription:
hyperspace wallet stake 10000
hyperspace start --chain-role miner

System Requirements

Minimum (fullnode or relay)
RESOURCEMINIMUM
CPU2 cores
RAM4 GB
Disk10 GB free
Network10 Mbps
OSmacOS 12+, Ubuntu 20.04+, Windows 10+
Recommended (miner)
RESOURCERECOMMENDED
CPU4+ cores
RAM8 GB
Disk50 GB SSD
Network100 Mbps, low latency
Uptime99%+ (miners are penalized for downtime)
With GPU (AI inference + mining)
RESOURCERECOMMENDED
GPU8+ GB VRAM (RTX 3060+, M1+)
RAM16 GB
Disk100 GB SSD

Troubleshooting

"genesis file not found"
On v5.1.0+ this downloads automatically. If you see the error:
rm ~/.hyperspace/genesis.json
hyperspace start
Blockchain binary not starting
Check if it's running:
ps aux | grep hyperspace-agentic-blockchain | grep -v grep
Common causes:
1. Binary still downloading — first start downloads ~50MB. Wait for it.
2. Port conflict — check lsof -i :8545 and lsof -i :30301
3. Firewall — port 30301 needs to be open for inbound.
TUI shows blk:0 and p:0
Your chain node is running but hasn't synced yet:
blk:0 — no blocks received. Chain needs miners online to produce blocks.
p:0 — no chain peers. Check internet and firewall.
gs:○ — GossipSub bridge inactive. Activates when peers connect.
"miner requires 10,000 staked points"
Two ways to mine:
1. Stake points: hyperspace wallet stake 10000
2. Validator key: subscribe at miners.hyper.space and save the key to ~/.hyperspace/validator.key
How do I check chain status?
# Block height
curl -s http://localhost:8545 -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Peer count
curl -s http://localhost:8545 -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'
How do I run without the TUI (headless/server mode)?
Pipe output to disable the interactive TUI — useful for servers, systemd, or logging:
# Headless mode — plain text output
hyperspace start --chain-role miner 2>&1 | tee miner.log

# Run in background with nohup
nohup hyperspace start --chain-role miner > miner.log 2>&1 &

# Run in tmux/screen (recommended for servers)
tmux new -d -s miner 'hyperspace start --chain-role miner'

# Check first 100 lines of startup
hyperspace start --chain-role miner 2>&1 | head -100
Running the blockchain binary directly (without the CLI)
The CLI handles binary download, genesis, key setup, and auto-restart. If you download the binary directly from the AGI repo or GitHub releases, you need to initialize manually:
# Initialize data directory + genesis
./hyperspace-agentic-blockchain init --datadir ./chain-data

# Then run
./hyperspace-agentic-blockchain server --mine --datadir ./chain-data \
  --bootnodes /dns4/boot1.hyper.space/tcp/30301/p2p/... \
  --validator-key ./validator.key
The CLI does all of this for you — hyperspace start --chain-role miner is the recommended way.
How do I stop/restart?
hyperspace kill          # stop everything
hyperspace start         # restart
hyperspace start --chain-role miner   # restart as miner

File Locations

Where does everything live?
FILEPATH
CLI binary~/.local/bin/hyperspace
Chain binary~/.hyperspace/bin/hyperspace-agentic-blockchain
Genesis file~/.hyperspace/genesis.json
Chain data~/.hyperspace/chain/
Miner key~/.hyperspace/validator.key
Node identity~/.hyperspace/identity.json
Config~/.hyperspace/config.json

Network

Network details
PROPERTYVALUE
Chain ID808080
Block time~2 seconds
P2P port30301
RPC port8545
Bootnodesboot1.a1.hyper.space, boot2.a1.hyper.space, boot3.a1.hyper.space
Miner signupminers.hyper.space
What ports do I need open?
PORTPURPOSEREQUIRED FOR
30301Chain P2PAll roles
8545JSON-RPC (local only)Local queries
4001libp2p P2P (agent)All roles
8080Agent APITUI dashboard
Become a MinerDashboardLeaderboardGitHub