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 inlib/hyper/vm/spec.ex, allocates a disk layer vialib/hyper/img/oci_loader.ex, and hands the spec tolib/hyper/node/fire_vmm/boot_spec.ex. - Execution (
Hyper.exec/2) forwards commands to the running VM throughlib/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.
Application.start/2launchesHyper.cluster.ex– a distributed process that discovers peers via the:libclusterlibrary.Hyper.cluster.scheduler.exreceives a VM spec, consultsHyper.cluster.routing.exto pick a target node, and forwards the spec to the chosen node’sHyper.node.fire_vmm.ex.FireVmm.boot_spec/2writes a Firecracker JSON config inpriv/, then spawns the Rust guest agent (native/guest‑agent/src/main.rs).- The guest agent creates a COW layer (
native/hyperrs‑fs), mounts the rootfs (native/hyperrs‑firecracker), and starts the Firecracker process. - For
exec,Hyper.exec/2callsHyper.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 byconfig/config.exs). - Filesystem – Thin layers in
/var/lib/hyper/created bynative/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 workflowgithub/workflows/ci.ymlruns them. - Coverage –
codecov.ymlreports 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 docswill 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.