Hyperspace CLI

The command-line agent for the Hyperspace decentralized P2P AI inference network.

Website | Dashboard | Twitter/X

Hyperspace CLI (hyperspace) is the primary way to run an agent on the Hyperspace network -- a fully decentralized peer-to-peer AI inference network with over 2 million agents worldwide. Run local AI models, earn points, and contribute compute to the network.

This is a release-only repository. Binary releases are published here for direct download and auto-update. The source code lives in a private monorepo.

Table of Contents

• Install
• Quick Start
• Command Reference
• Features
• Platform Support
• GPU Recommendations
• Configuration
• Migrating from v1
• Troubleshooting
• Uninstall
• Links
• License

Install

Linux / macOS

curl -fsSL https://download.hyper.space/api/install | bash

Windows (PowerShell as Administrator)

curl https://download.hyper.space/api/install?platform=windows | powershell -

What the installer does

• Auto-detects your OS and CPU architecture
• Downloads the correct pre-built binary
• Installs to ~/.hyperspace/bin/ and adds it to your PATH
• Installs llama-server for native GPU inference (CUDA on Linux/Windows, Metal on macOS)
• Auto-detects and integrates with existing Ollama installations
• On desktop machines, installs the Hyperspace Tray app (use --no-tray to skip)

The binary is named hyperspace. The legacy name aios-cli is kept as an alias for backward compatibility.

Quick Start

# Start your agent (auto-detects hardware and selects the best profile)
hyperspace start

# Or start with all 9 capabilities enabled
hyperspace start --profile full

# Start with the management API on a specific port
hyperspace start --api-port 8080

# Auto-download the best models for your GPU
hyperspace models pull --auto

# Check your agent status, peer count, and points
hyperspace status

Command Reference

Core Commands

Start Options

hyperspace start                          # Auto-detect everything
hyperspace start --profile full           # All 9 capabilities
hyperspace start --profile inference      # GPU inference only
hyperspace start --profile embedding      # CPU-only embedding agent
hyperspace start --profile relay          # Lightweight relay agent
hyperspace start --profile storage        # Storage + memory
hyperspace start --api-port 8080          # Management API port
hyperspace start --cuda                   # Force CUDA acceleration
hyperspace start --verbose                # Verbose logging
hyperspace start --no-api                 # Disable management API

Model Management

Inference

hyperspace infer --prompt "Explain quantum computing" --p2p   # P2P network inference
hyperspace infer --prompt "Hello" --local                      # Local inference
hyperspace infer --model <model-id> --prompt "Hello"           # Specific model
hyperspace infer --interactive                                 # Interactive chat
hyperspace chat                                                # Agent chat mode

Wallet and Staking

Identity

Configuration

Proxy

System

Features

• Native GPU Inference -- Full local AI inference via node-llama-cpp with CUDA (NVIDIA) and Metal (Apple Silicon) support
• Auto Model Selection -- Automatically picks the best models for your available VRAM
• Ollama Integration -- Discovers and uses locally installed Ollama models out of the box
• Background Daemon -- Runs as a persistent background process that survives terminal close
• Points System -- Earn points through pulse verification rounds and serving inference to the network
• P2P Networking -- Built on libp2p with GossipSub, Kademlia DHT, and Circuit Relay for NAT traversal
• Auto-Update -- Checks for new versions on startup and applies updates seamlessly
• Management API -- REST and WebSocket API on a configurable port for programmatic control

Network Capabilities

Each agent provides up to 9 capabilities:

Platform Support

The CUDA variants include GPU acceleration for NVIDIA GPUs. On macOS, Metal acceleration for Apple Silicon is included in the standard binary.

GPU Recommendations

CPU-only agents can still contribute by running embedding models and acting as relay or storage agents.

Configuration

All data is stored under ~/.hyperspace/:

On Windows, the equivalent base path is %LOCALAPPDATA%\Hyperspace\.

Migrating from v1

• The binary auto-updates from v1 to v2 on next launch.
• Your v1 points are frozen and preserved.
• The aios-cli command name continues to work as an alias.
• V2 replaces manual tier selection with automatic hardware detection.

Troubleshooting

Agent not starting

# Check logs
cat ~/.hyperspace/logs/hyperspace.log

# Ensure no other instance running
hyperspace status

# Try different API port
hyperspace start --api-port 9090

No GPU detected

• NVIDIA: Ensure CUDA drivers are installed and nvidia-smi works.
• Apple Silicon: Metal support is built-in with the aarch64-apple-darwin binary.
• CPU-only: Falls back to CPU inference with smaller models. Use --profile embedding.

Models not downloading

• Check available disk space (models range from 1-20 GB).
• Downloads support resume -- re-run hyperspace models pull --auto to continue.

Connection issues

• Outbound internet access on TCP port 4002 (WebSocket) required.
• Agents behind NAT are supported via circuit relay -- no port forwarding needed.

Uninstall

Linux / macOS

curl https://download.hyper.space/api/uninstall | bash

Windows (PowerShell)

(Invoke-WebRequest "https://download.hyper.space/uninstall?platform=windows").Content | powershell -

Removes the binary, tray app, and configuration. Downloaded models in ~/.hyperspace/models/ are preserved by default.

Links

• Website: https://hyper.space
• Dashboard: https://p2p.hyper.space
• Twitter/X: @HyperspaceAI

Maintainer

Varun (@twobitapps)

License

See LICENSE for details.