Hero Compute

Slice-based virtual machine manager for the Hero Ecosystem. Divides a physical host into 4 GB RAM slices, each backing exactly one VM. Built on the hero_rpc OSIS framework with JSON-RPC 2.0 over Unix sockets.

New here? Read the Hero Compute Explainer for a visual guide to how slices, VMs, secrets, and the explorer work together.

How It Works

On bootstrap the server reads /proc/meminfo and df, reserves 1 GB for the OS, and carves the rest into slices:

Example: 64 GB RAM, 2 TB SSD
  usable     = 64 - 1 = 63 GB
  slices     = floor(63 / 4) = 15
  disk/slice = floor(2000 / 15) = 133 GB

Deploy a VM into any free slice; start/stop/restart return immediately while the hypervisor works in the background.

Requirements

• Linux (x86_64) bare-metal server with hardware virtualization (KVM)
• Rust toolchain (1.92+)
• System packages: libssl-dev, pkg-config, iproute2, busybox-static
• hero_proc process supervisor (must be running)
• my_hypervisor (VM hypervisor)
• cloud-hypervisor (VMM backend)

Quick Start

Single command install (downloads all binaries, configures, and starts services):

curl -sfL https://forge.ourworld.tf/lhumina_code/hero_compute/raw/branch/development/scripts/install.sh | bash

The installer checks each component and only downloads what's missing or outdated. Re-run safely at any time to update. See the Setup Guide for full installation details and multi-node deployment.

Or build from source:

make configure   # install deps + build
make start       # start in local mode
# Open http://<server-ip>:9001

Register the node, then deploy a VM. The UI guides you through image selection (images come from the hero_compute_registry, all with SSH key auth pre-configured). Add your SSH key in Settings, then SSH in via Mycelium IPv6: ssh root@<ip>.

Multi-Node Setup

# Master node (explorer hub -- other nodes connect here):
make start MODE=master

# Worker node (connects to a master):
make start MODE=worker MASTER_IP=<master-ip>

See Setup Guide for full installation and multi-node instructions.

Service Architecture

Hero Compute uses the hero_proc_service_selfstart pattern:

• hero_compute -- CLI binary that registers all components with hero_proc (--start / --stop)
• hero_compute_server -- JSON-RPC daemon (foreground, managed by hero_proc)
• hero_compute_ui -- Admin dashboard (foreground, binds TCP port 9001 directly)
• hero_compute_explorer -- Multi-node registry (foreground, managed by hero_proc)

hero_compute --start                                  # Local mode (default)
hero_compute --start --mode master                    # Explorer hub
hero_compute --start --mode worker --master-ip X.X.X  # Worker node
hero_compute --stop                                   # Stop everything

Make Targets

Target	Description
make configure	Install all dependencies and build
make start	Build + start in local mode (single node)
make start MODE=master	Start as master (explorer hub for workers)
make start MODE=worker MASTER_IP=x.x.x.x	Start as worker connected to a master
make stop	Stop all services
make status	Show service status via hero_proc
make build	Build all binaries (musl static, x86_64-unknown-linux-musl)
make clean	Remove build artifacts
make test	Run unit tests
make lint	Run clippy linter
make fmt	Format code

Security -- VM Secrets

VMs are protected by a secret -- a capability token you set at deploy time. All VM operations (start, stop, delete, list) require the matching secret.

Important: The secret is your identity, not a password. Anyone who knows your secret can see and manage your VMs. This is by design for simplicity.

• Always use generated secrets. The UI auto-generates a 16-character random secret on first visit. Use it.
• Never use common words or short strings. If two users pick the same secret, they share VM access.
• Treat it like a private key. Store it securely. Don't share it.
• Empty secret = no protection. All operations work without a secret (backward compatible, for single-tenant setups).

See API Reference -- Security Model for full details.

Documentation

• Hero Compute Explainer -- how slices, VMs, secrets, and the explorer work (with diagrams)
• Architecture -- system design, crate map, code generation, protocols
• Configuration -- all environment variables with defaults
• Setup Guide -- installation and multi-node deployment
• API Reference -- all RPC methods, VM states, data types
• Testing Guide -- RPC testing via Unix sockets

Crates

Crate	Description
hero_compute	CLI -- registers and manages all service components via hero_proc
hero_compute_server	JSON-RPC daemon -- VM lifecycle, slice management
hero_compute_explorer	Multi-node registry -- aggregates nodes via heartbeats
hero_compute_sdk	Generated OpenRPC client library
hero_compute_ui	Admin dashboard (Bootstrap + Askama + Axum)
hero_compute_examples	SDK usage examples

License

Apache-2.0