matrix

Run lightweight microVMs using Firecracker or Cloud Hypervisor (WIP) via one minimal REST API.

Status: UNDER ACTIVE DEVELOPMENT (pre-alpha) – interfaces and behavior will change.

Goal

Provide the easiest developer on-ramp to spin up microVMs: hide per-hypervisor quirks behind a small, pragmatic HTTP surface.

Current Features (Firecracker backend)

• Launch microVM (UUID id) with basic machine config
• Kernel + rootfs drive attach
• Simple TAP networking (static IP allocation 172.16.0.x)
• List / inspect / stop / restart
• Structured JSON responses & tracing logs

Roadmap (abridged)

Stage	Items
M1	Configurable launch params (request body), cleanup of TAP devices
M2	Cloud Hypervisor backend parity
M3	Image management / caching, metrics & health
M4	AuthN/Z, multi-tenant isolation
M5	Advanced networking modes, event streaming

Architecture

Client -> HTTP (Rouille) -> matrix server -> Spawn & configure VMM via Unix socket HTTP calls -> Firecracker process.

Each VM: separate Firecracker process, /tmp/firecracker-<id>.socket used for configuration; state kept in-memory.

Security / Safety Notice

NOT PRODUCTION READY. No auth, no persistence, minimal validation, simplified networking. Use only in controlled dev setups.

Prerequisites

Host (Linux recommended; macOS not supported natively for KVM/TAP):

• Rust toolchain
• ip, wget, curl, qemu-img, unsquashfs, mkfs.ext4, sudo
• KVM + TUN/TAP enabled

Firecracker assets:

• firecracker binary
• vmlinux-* kernel image
• ubuntu-*.ext4 rootfs

Convenience script: ./setup-firecracker.sh (downloads latest Firecracker, kernel, builds ext4 rootfs).

Cloud Hypervisor (work in progress): use ./setup-ch.sh to fetch cloud-hypervisor, firmware, and base image.

Quick Start (Firecracker)

git clone <repo-url>
cd matrix
cargo build --release
./setup-firecracker.sh
./target/release/matrix

Create a microVM:

curl -X POST http://localhost:8000/fc/containers

List microVMs:

curl http://localhost:8000/fc/containers

Stop microVM:

curl -X POST http://localhost:8000/fc/containers/<id>/stop
# or
curl -X DELETE http://localhost:8000/fc/containers/<id>

Restart microVM:

curl -X POST http://localhost:8000/fc/containers/<id>/restart

REST API (Firecracker)

Base: http://localhost:8000

Method	Path	Description
POST	/fc/containers	Create microVM
GET	/fc/containers	List microVMs
GET	/fc/containers/{id}	Inspect microVM
DELETE	/fc/containers/{id}	Stop & remove microVM
POST	/fc/containers/{id}/stop	Stop microVM
POST	/fc/containers/{id}/restart	Restart microVM

Create response example:

{ "container_id": "<uuid>", "message": "Container creation started" }

Inspect response example (fields abbreviated):

{
  "id": "<uuid>",
  "status": "Running",
  "socket_path": "/tmp/firecracker-<uuid>.socket",
  "config": {
    "vcpu_count": 1,
    "mem_size_mib": 512,
    "kernel_image_path": "./vmlinux-6.1.128",
    "rootfs_path": "./ubuntu-24.04.ext4",
    "boot_args": "console=ttyS0 reboot=k panic=1 pci=off"
  },
  "guest_ip": "172.16.0.2"
}

Networking

• Static IP allocation: sequential 172.16.0.X (wrap after .254)
• TAP interface per VM (name derived from id)
• Host side currently fixed to 172.16.0.1/30 (simplistic; subject to change)
• MAC derived from IP (06:00:AC:10:00:XX)
• TAP deletion on stop not fully implemented yet (may need manual sudo ip link del <tap>)

Development

cargo run            # debug server
cargo fmt --check    # formatting
cargo clippy -- -D warnings