Hero Compute

Slice-based virtual machine manager for the Hero Ecosystem. Divides a host into 4 GB RAM slices, each backing exactly one VM deployed to TFGrid v3 (ThreeFold Grid). 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; VMs are deployed to TFGrid v3 via GridDeployer. Start/stop/restart return immediately while the deployment completes in the background.

Requirements

• Any platform (Linux, macOS — VMs run on TFGrid, not locally)
• Rust toolchain (1.92+)
• System packages: libssl-dev, pkg-config, socat
• hero_proc process supervisor (must be running)
• TFGrid credentials — configured interactively on first --start (or via --configure)

Quick Start

# First time — install all dependencies and build:
make configure

# Start in local mode (single node):
make start

# Open the dashboard:
# http://localhost:9001

Register the node, then deploy a VM — the UI guides you through image selection (images come from the my_compute_holo_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.

Make Targets

Target	Description
make configure	Install all dependencies (system packages, Rust, hero_proc) 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 + proxies
make status	Show service and proxy status
make build	Build all binaries
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.
• Secret is always required. Every VM must have a secret set at deploy time. Empty secrets are rejected.

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 — full VM lifecycle walkthrough with socat

Crates

Crate	Description
my_compute_holo_server	JSON-RPC daemon — VM lifecycle, slice management
my_compute_holo_explorer	Multi-node registry — aggregates nodes via heartbeats
my_compute_holo_sdk	Generated OpenRPC client library
my_compute_holo_ui	Admin dashboard (Bootstrap + Askama + Axum)
my_compute_holo_examples	SDK usage examples

License

Apache-2.0