firepeel
API
No. 01 / microvm hypervisor

firecracker VMs
in under a second

Firepeel is a lightweight control plane for Firecracker microVMs — launch, isolate, and tear down tenant workloads across a cluster of stateless worker nodes, with a live web console for operating everything by hand.

Get Started View the API See what it does
No. 02 / capabilities

what it does

A control plane and a fleet of workers, talking over a small internal HTTP API — everything a Firecracker cluster needs and nothing it doesn't.

01

Sub-second VM launch

Boots a Firecracker microVM from a launch request to a running guest in well under a second, with tap, netns, and disk provisioned per call.

02

Multi-tenant isolation

Every tenant gets its own netns, bridge, veth, and NAT on every node — independent address space, no cross-tenant visibility.

03

Stateless worker nodes

Nodes hold no durable state and own no allocation logic — they execute exactly what the orchestrator tells them, and the orchestrator reconciles on restart.

04

Centralized VM registry

Postgres-backed registry tracks which VM lives on which node, with sequence-based tap/index allocation so addresses never collide across the cluster.

05

Least-loaded scheduling

Launch requests are dispatched to the healthiest, least-loaded node automatically — or pinned to a specific node when needed.

06

Live health & state tracking

Nodes heartbeat every 15 seconds and push state transitions as they happen, so the registry always reflects reality.

07

Web console

A single-file browser UI lists every VM, streams a live console over WebSocket, and drives launch/stop without touching the API directly.

08

Configurable per-VM disk & DNS

Writable disk size, disk quota, and DNS are all set per launch request — no rebuilding images for different tenant needs.

No. 03 / architecture

orchestrator + node

A durable control plane paired with disposable, fully-isolated workers.

fc-orchestrator

control plane / owns all state
  • VM registry — which VM lives on which node
  • Global tap/VM index allocation via Postgres sequences
  • Node registration and health tracking
  • External operator-facing API (launch / stop / list)
  • Dispatches work to the least-loaded healthy node

fc-node

worker / stateless, root-privileged
  • Provisions disk, cgroup, tap, and netns per VM
  • Runs and supervises the Firecracker process itself
  • Serves a console WebSocket for live guest access
  • Reports every state transition back to the orchestrator
  • Holds no persistent state — orchestrator reconciles on restart
No. 04 / api reference

endpoints

The orchestrator exposes an operator-facing API and an internal node-facing API; nodes expose their own launch/stop surface to the orchestrator.

orchestrator — external (operator-facing)
POST/vm/launchLaunch a VM — { instancename, tenant, dns?, rw_size_mb?, disk_quota_mb?, node_id? }
POST/vm/stopStop a VM — { instancename, force? }
GET/vm/listList VMs, optionally filtered — ?tenant=<t>
orchestrator — internal (node-facing)
POST/internal/node/registerNode registers itself — { node_id, addr }
POST/internal/node/heartbeatNode liveness ping, every 15s — { node_id }
POST/internal/vm/stateNode pushes a VM state transition event
node — orchestrator-facing
POST/node/vm/launchProvision and boot a VM — { vm_id, tenant, tap_idx, vm_idx, dns, rw_size_mb }
WS    /consoleLive console stream for a running guest