my_hypervisor

What this is

Narrow VM control-plane daemon for MOS. Runs cloud-hypervisor instances on behalf of the slice manager (hero_compute) and exposes lifecycle control over JSON-RPC 2.0 on a Unix socket.

Not a CLI. User-facing commands live in hero_compute and the MOS installer; my_hypervisor is a system daemon.

Scope:

See ADR-006. In one paragraph: cloud-hypervisor lifecycle (spawn / supervise / reap), per-VM 8-state FSM with transition ring buffer, plumbing (serial console UDS, vsock exec proxy, hero_rpc2 adapter). Delegates OCI, storage, and networking preparation to other daemons.

What this repository contains

Binary	Role
my_hypervisor-daemon	Long-running root daemon; listens on the RPC socket
my_hypervisor-init	Guest-side PID 1, statically linked via musl

Crate layout:

crates/
  my_hypervisor-lib/     library: orchestrator, FSM, state store, RPC adapter
  my_hypervisor-daemon/  thin binary wrapping run_server()
  my_hypervisor-init/    guest PID 1 (musl static)

Build:

cargo build --workspace --release

Integration with MOS image assembly lives in mos_builder.

Run (local dev):

sudo ./target/release/my_hypervisor-daemon \
    --rpc-socket   /run/my_hypervisor/rpc.sock \
    --state-dir    /run/my_hypervisor/vms \
    --console-dir  /run/my_hypervisor

Requires: KVM, cloud-hypervisor >= v50, root (for /dev/kvm and tap ioctls). See ADR-006 for the privilege stance.

Socket mode defaults to 0600 root:root; group-grant policy deferred to the hero_rpc2 rethink.

RPC surface:

compute.vm.* namespace over line-delimited JSON-RPC 2.0 at the RPC socket. Supported methods: create, start, stop, remove, status, list, events.tail, console.endpoint, logs, exec. See crates/my_hypervisor-lib/src/rpc/server.rs or call rpc.discover.

Lifecycle state machine:

Pending → Provisioning → Configured → Starting → Running
                                       ↓            ↓
                                  StartFailed   Stopping → Stopped
                                                    ↓
                                                 Failed

Architecture documents:

• ADR-006: the rewrite
• ADR-006 companion: v1 API + v1/v2 state.json
• discussion-vm-control-plane.md: committed design context
• [ADR-001..005]: historical; 003 and 005 are superseded by 006

Role in the stack

my_hypervisor is the low-level VM runtime daemon in the MOS/Hero stack. It owns cloud-hypervisor lifecycle, the VM state machine, serial console plumbing, and vm_exec proxying. It does not own scheduling, slice math, or tenancy — those live in hero_compute.

After the redesign, state authority is split:

• Cluster-level identity / tenancy — owned by hero_compute (slices, ownership, secrets, quotas). Persisted in OsiS. Survives node failure.
• Host-level VM runtime state — owned by my_hypervisor (PID, sockets, cloud-hypervisor config, OCI image cache pointers). Local to the host.

hero_compute talks to my_os_server exclusively; my_os_server proxies compute.* to the local my_hypervisor socket, mirroring how net.* proxies to mosnet and vol.* proxies to mos_volmgrd.

hero_proc is out of the VM path. It keeps doing what it is good at for non-VM workloads (declarative services, dependency graph, health checks, cron, PTY attach, secrets, web admin).

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.