my_compute_holo

What this is

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

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 the ThreeFold Grid via GridDeployer. Start/stop/restart return immediately while the deployment completes in the background.

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

What this repository contains

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

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

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

Role in the stack

my_compute_holo deploys VMs to the ThreeFold Grid. Each VM gets a Mycelium IPv6 address for peer-to-peer networking. The component depends on:

• hero_proc process supervisor (must be running)
• ThreeFold Grid credentials — configured interactively on first --start (or via --configure)
• Mycelium for SSH connectivity to deployed VMs

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 the Setup Guide for full installation and multi-node instructions.

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.

• 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.

Relation to ThreeFold

This technology is used within the ThreeFold ecosystem and was first deployed on the ThreeFold Grid. The component itself is designed as reusable infrastructure technology and should be understood by its technical function first, independent of any specific deployment.

Ownership

This repository is owned and maintained by TF-Tech NV, a Belgian company responsible for the development and maintenance of this technology.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.