Firemage

Firemage runs Firecracker microVMs from OCI images and disk images as a service. One binary is the server with an HTTP API and a web UI, the CLI, and a serverless direct mode for CI and single hosts.

Status: work in progress. The server has not had a third-party security review; do not expose it on adversarial networks.

Features

• Jobs and persistent VMs: a job boots a fresh clone of its image on every start and records the exit code; a persistent VM keeps its disk and can be paused and snapshotted.
• Egress policy: guests reach only the hosts, methods and paths a policy allows, through a proxy that injects or signs credentials the guest never holds.
• Network monitoring: every connection gets a verdict and a redacted proxy record, with optional packet capture, per VM or per network.
• Secrets, assets and kernels: an owner catalog of vault secrets, uploaded or downloaded files and kernels that VM documents reference by name.
• Jailed by default: each VM runs under the Firecracker jailer with its own UID, cgroup and TAP device; trusted workloads opt out.
• Direct mode: the same verbs run without a server against a self-contained data directory, so a CI step can boot a VM and exit with its status.

Quickstart

Linux with KVM is required; jailed operation also needs the Firecracker jailer, cgroup v2 and a reserved UID range, see Jailer.

Direct Mode Example

Direct mode offers the same engine and VM ergonomics without having to spin up a server:

# Download firemage from the latest release and put it on PATH, then:
sudo firemage direct -d ./lab init
sudo firemage direct -d ./lab kernel import vmlinux-6.1.155 \
  https://s3.amazonaws.com/spec.ccfc.min/firecracker-ci/v1.15/x86_64/vmlinux-6.1.155 \
  --sha256 <digest> --alias linux
sudo firemage direct -d ./lab vm create --name hello --kernel linux \
  --image docker.io/library/alpine:3 --size-mib 512 \
  --command '["/bin/sh","-c","echo hello from a microVM"]' --start

vm create --start boots the job in the foreground, echoes its console and exits with the guest's status. firemage direct -d ./lab dispose removes everything. For a shared server, firemage user bootstrap NAME then firemage serve and open the web UI, see Configuration.

Documentation

• Running VMs: VM, Jobs, Persistent VMs, Userdata, Guest agent, Snapshots
• Networking: Networks, Egress, Monitoring
• Catalog: Assets, Kernels
• Operating: CLI, Direct mode, Manifests, Configuration, Jailer

Building

Copy .env.example to .env and set FIREMAGE_DEPENDENCY_INDEX to a Cargo sparse index (crates.io or a proxy). With just and Docker or Podman installed:

just docker-build      # debug binary in dist/firemage
just docker-verify     # format, lint and tests
just docker-release    # release binary with the embedded web UI

Native builds need static libc development libraries (glibc-static on Fedora) for the firemage-guest helper that the host embeds; just builds it first, and direct Cargo commands take it from FIREMAGE_GUEST_BIN_PATH after just guest-build.