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 or aarch64) for production (VM operations require chvm)
• Rust toolchain (1.92+)
• System packages: libssl-dev, pkg-config, socat
• Zinit process supervisor (must be running)

See Setup Guide for full installation instructions.

Quick Start

make build            # compile all binaries
make start            # start all services + TCP proxy on port 9001
make stop             # stop all services + proxy

Open http://localhost:9001 to access the admin dashboard.

Test with socat:

echo '{"jsonrpc":"2.0","method":"cloud.ComputeService.node_register","params":{},"id":1}' \
  | socat - UNIX-CONNECT:$HOME/hero/var/sockets/hero_compute_server.sock

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 development
• API Reference — all RPC methods, VM states, data types
• Testing Guide — full VM lifecycle walkthrough with socat

Crates

Crate	Description
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