Skip to content

README.md

Latest commit

 

History

History
144 lines (103 loc) · 4.08 KB

README.md

File metadata and controls

144 lines (103 loc) · 4.08 KB

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