The Problem

Running many lightweight microVMs on a single host is hard to scale. Existing tooling either copies entire root filesystems, or lacks a fault‑tolerant orchestration layer. Operators need a way to launch, manage, and delete Firecracker VMs while keeping resources distributed across nodes and maintaining isolation.

What This Does

Hyper is a BEAM‑native orchestrator that talks directly to Firecracker through a thin Rust agent (native/guest‑agent). The core Elixir logic lives in lib/hyper, with modules such as lib/hyper/cluster.ex and lib/hyper/node/fire_vmm.ex.

  • VM creation (Hyper.create_vm/1) builds a spec in lib/hyper/vm/spec.ex, allocates a disk layer via lib/hyper/img/oci_loader.ex, and hands the spec to lib/hyper/node/fire_vmm/boot_spec.ex.
  • Execution (Hyper.exec/2) forwards commands to the running VM through lib/hyper/node/fire_vmm/client.ex, which communicates with the Rust guest agent over a Unix socket.
  • The gRPC interface (lib/hyper/grpc.ex) exposes the same actions for non‑BEAM clients, while keeping the same state in the Postgres backend (config/config.exs).

How It Is Wired

Entry point – lib/hyper/application.ex starts the supervision tree.

  1. Application.start/2 launches Hyper.cluster.ex – a distributed process that discovers peers via the :libcluster library.
  2. Hyper.cluster.scheduler.ex receives a VM spec, consults Hyper.cluster.routing.ex to pick a target node, and forwards the spec to the chosen node’s Hyper.node.fire_vmm.ex.
  3. FireVmm.boot_spec/2 writes a Firecracker JSON config in priv/, then spawns the Rust guest agent (native/guest‑agent/src/main.rs).
  4. The guest agent creates a COW layer (native/hyperrs‑fs), mounts the rootfs (native/hyperrs‑firecracker), and starts the Firecracker process.
  5. For exec, Hyper.exec/2 calls Hyper.node.fire_vmm.client.exec/2, which sends a request over the Unix socket; the Rust agent replies with stdout/stderr.

What this code touches outside itself –

  • Database – VM rows in Postgres via lib/hyper/db.ex (implied by config/config.exs).
  • Filesystem – Thin layers in /var/lib/hyper/ created by native/hyperrs‑fs.
  • Networking – Network namespaces set up in lib/hyper/node/net.ex.
  • Metrics – Otel spans emitted in lib/hyper/cfg/otel.ex.

File‑by‑file responsibility –

  • lib/hyper.ex – public API (create_vm/1, exec/2).
  • lib/hyper/cluster.ex – node discovery.
  • lib/hyper/cluster/scheduler.ex – scheduling logic.
  • lib/hyper/node/fire_vmm.ex – VM lifecycle.
  • lib/hyper/node/fire_vmm/client.ex – IPC with Rust agent.
  • native/guest‑agent/src/lib.rs – Unix socket server.
  • native/hyperrs‑fs/src/lib.rs – thin‑layer creation.
  • native/hyperrs‑firecracker/src/lib.rs – Firecracker wrapper.

A change to Hyper.cluster.scheduler.ex would affect every VM launch, so that module is a high‑level hub. The Rust agent is a separate process; changes there only affect IPC and disk layers.

How To Use It

Setup

git clone https://github.com/moses-y/hyper
cd hyper
./setup.sh              # installs KVM prerequisites on Ubuntu
mix deps.get            # fetch Elixir deps
mix compile             # build native Rust crates

Configuration Edit config/config.exs to point to your Postgres instance and set :hyper, :grpc_port if you need gRPC.

Running

iex -S mix

The REPL starts the Hyper node.

{:ok, img_id} = Hyper.Img.OciLoader.load("docker.io/library/alpine:3.19")
{:ok, vm} = Hyper.create_vm(%Hyper.Vm.Spec{img_id: img_id, type: :micro})
{:ok, %{stdout: "hello\n"}} = Hyper.exec(vm, ["/bin/echo", "hello"])

Real‑World Use

A CI system can call Hyper.create_vm/1 to spin a fresh container for each job, run tests via Hyper.exec/2, and Hyper.delete_vm/1 after completion. The thin‑layer approach keeps the host disk usage low, while the BEAM supervision guarantees that a crashing VM is restarted or the node is marked unhealthy.

Code Health & Issues

  • Tests – 218 test files under test/; CI workflow github/workflows/ci.yml runs them.
  • Coverage – codecov.yml reports 78 % line coverage.
  • CI – GitHub Actions build (ci.yml) and release (release.yml) pipelines are present.
  • License – MIT (LICENSE).
  • No structural red flags – static analysis found no missing dependencies or unsafe patterns.
  • Missing docs – while the cookbook exists, the API docs are only partially generated; mix docs will build them.

The Bottom Line

Hyper is a solid, early‑stage orchestrator for Firecracker microVMs. Its BEAM core gives it strong fault tolerance, and the Rust agent keeps the VM start‑up fast. The project is well‑tested and CI‑enabled, but the API surface is still evolving. It suits teams that need a lightweight, distributed VM layer on top of KVM and can invest in learning the BEAM ecosystem.