Slice-based VM compute manager for the Hero Ecosystem, built on hero_rpc OSIS framework

Rust 59.1%
Shell 24.7%
JavaScript 8.5%
HTML 4.4%
Makefile 3.2%

Find a file

mik-tf b66772e88d Some checks failed Build Linux / build-linux (linux-amd64, false, x86_64-unknown-linux-musl) (push) Failing after 2s Details Test / test (push) Failing after 1s Details Build Linux / build-linux (linux-arm64, true, aarch64-unknown-linux-gnu) (push) Successful in 3m41s Details feat: add hero:theme listener for Hero OS theme sync Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>		2026-03-06 02:18:38 -05:00
.forgejo/workflows	ci: Disable publish step in CI workflow	2026-03-04 14:16:07 +02:00
crates	feat: add hero:theme listener for Hero OS theme sync	2026-03-06 02:18:38 -05:00
docs	docs: Update RPC method format, built-in methods, and timestamps	2026-03-04 14:53:29 +02:00
schemas/cloud	feat: expose vm_logs and vm_exec through RPC and SDK	2026-03-04 10:18:54 +02:00
scripts	feat: Refactor to workspace, add UI and comprehensive build	2026-03-03 20:10:21 +02:00
sdk/js	Initial hero_cloud project — slice-based VM compute manager	2026-03-03 16:47:57 +02:00
.gitignore	feat: Refactor to workspace, add UI and comprehensive build	2026-03-03 20:10:21 +02:00
buildenv.sh	feat: Refactor to workspace, add UI and comprehensive build	2026-03-03 20:10:21 +02:00
Cargo.lock	refactor: remove MockHypervisor, ChvmDriver is now the only driver; fix created_at/updated_at timestamps	2026-03-04 12:19:51 +02:00
Cargo.toml	fix: capture mycelium IP on start, force remove, add startup reconciliation	2026-03-04 10:06:21 +02:00
Makefile	feat: async fire-and-forget for start/stop/restart VM, add comprehensive logging	2026-03-04 13:19:46 +02:00
README.md	docs: Update RPC method format, built-in methods, and timestamps	2026-03-04 14:53:29 +02:00

README.md

Hero Cloud

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.

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)
chvm hypervisor installed
zinit process supervisor
Rust toolchain (1.92+)

Quick Start

make build        # compile workspace
make run          # start server + UI via zinit
make logs         # view server logs
make stop         # stop all services

Test with socat:

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

Documentation

Setup Guide — installation, chvm, environment variables
API Reference — all RPC methods, VM states, data types
Testing Guide — full VM lifecycle walkthrough with socat

Crate	Description
`hero_cloud_server`	JSON-RPC daemon (Unix socket)
`hero_cloud_sdk`	Generated OpenRPC client library
`hero_cloud_ui`	Admin dashboard (Axum + Askama)
`hero_cloud_examples`	SDK usage examples

License

Apache-2.0