# mgf-vm-firecracker

> **The Firecracker microVM adapter for the Magogi Foundation
> distributed vm-vmanager-app.** Implements `mgf-vm-core`'s
> `HypervisorBackend` and `StorageBackend` against Firecracker
> (the Amazon-developed microVM monitor). The canonical
> *second adapter* per D-F2 — validates that the wrap-don't-marry
> seam (`contracts.md`) is real.

| Field | Value |
|---|---|
| **Status** | Phase 1 deliverable. Skeleton landed; implementation begins after `mgf-vm-core` contracts land. |
| **Federation sibling.** | Depends on `mgf-common>=0.38,<0.39` + `mgf-vm-core>=0.1,<0.2` + `httpx`. |
| **Conformance level.** | **L2 — Standard.** Per-rule ledger: [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md). |
| **License.** | MIT. |
| **Python.** | 3.11 / 3.12 / 3.13. |
| **System dep.** | `firecracker` + `jailer` binaries (from the Firecracker release). |

---

## Why Firecracker

Per D-F2 in `vm-vmanager-docs/DECISIONS.md`: the architecture earns
multi-platform support *only if you exercise the seam.* Firecracker
is chosen as the second adapter because:

- **Genuinely different from libvirt.** Jailer-based isolation
  (not sVirt), REST API over Unix socket (not RPC + XML), no live
  migration, no memory snapshots — every choice the contracts spec
  made *generically* gets stressed by a real second engine.
- **Real, useful, OSS.** MicroVMs are credible production workloads
  (serverless, isolated CI runners, lightweight per-tenant
  isolation). This isn't a thought-experiment adapter.
- **Honest scope.** Firecracker doesn't try to be libvirt; it tries
  to be the smallest correct hypervisor for stateless x86_64 Linux
  VMs. Capabilities will accurately reflect that.

---

## Where the docs live

> **`vm-vmanager-docs`** — `~/PycharmProjects/vm-vmanager-docs/`

| What | Where |
|---|---|
| The contracts this adapter implements | `vm-vmanager-docs/component-specs/contracts.md` §3 (Hypervisor), §4 (Storage) |
| Why this exists (D-F2) | `vm-vmanager-docs/DECISIONS.md` Category F |
| **The playbook for how to build this** | `vm-vmanager-docs/developer/adding-an-adapter.md` |
| Roadmap (Phase 1 deliverable) | `vm-vmanager-docs/ROADMAP.md` |
| Test strategy (esp. the conformance suite) | `vm-vmanager-docs/TESTING.md` |

If you're a contributor implementing the adapter, the playbook
(`developer/adding-an-adapter.md`) is your step-by-step guide. The
contracts spec (`contracts.md`) is the bar your code is measured
against.

---

## What this library will contain

Phase 1 — see `vm-vmanager-docs/ROADMAP.md`:

```
src/mgf/vm/firecracker/
├── __init__.py           # public re-exports (AP-01)
├── py.typed
├── adapter.py            # FirecrackerAdapter: HypervisorBackend + StorageBackend
├── api/                  # REST-over-UDS client for the Firecracker API
├── jailer.py             # jailer subprocess management (SC-02 argv discipline)
├── translate.py          # VmSpec ↔ Firecracker JSON config (no XML)
└── errors.py             # Firecracker error code → mgf.vm.core.exceptions
```

### Capabilities Firecracker reports (per `contracts.md` §3.5)

- `supports_live_migration` = **False**
- `supports_memory_snapshots` = **False** (jailer snapshots are
  different — full-VM-state snapshots are supported but
  semantically distinct; the adapter exposes them through the
  StorageBackend snapshot API anyway)
- `supports_device_attach_live` = **False** (PCI passthrough not
  supported in Firecracker)
- Image format: **raw only** (no qcow2; `mgf.vm.core` converts on
  import per D-E4)
- Snapshot model: **full-state snapshots only** (via Firecracker's
  pause + snapshot API)
- Isolation: **jailer-based** (`IsolationLevel.high` only;
  `medium`/`low` rejected with `SpecInvalid`)

The conformance suite (`mgf-vm-core/tests/conformance/`) will skip
the capability-gated tests automatically.

---

## What this library does NOT contain

- **No libvirt** — that's `mgf-vm-libvirt`.
- **No device passthrough** — Firecracker doesn't do PCI/USB
  passthrough; the `DeviceBackend` for a Firecracker host is a
  no-op stub that reports zero assignable devices.
- **No live migration** — Firecracker doesn't support it (and
  cross-platform live migration is a physics limit per
  ARCHITECTURE.md §10 regardless).

---

## Install

```bash
# System: Firecracker + jailer binaries from a release.
# https://github.com/firecracker-microvm/firecracker/releases
curl -L https://github.com/firecracker-microvm/firecracker/releases/...

pip install mgf-vm-firecracker
```

## Develop

```bash
cd ~/PycharmProjects/mgf_vm_firecracker
uv venv --python 3.12
uv sync --extra dev
uv run pytest -q -m "not integration"   # unit + conformance with fakes
uv run pytest -q -m integration          # against real Firecracker
uv run mypy --strict src/
uv run ruff check src tests
uv run lint-imports
```

For the full system dev loop, see `vm-vmanager-docs/DEV-LOOP.md`
(opt in to firecracker with `FIRECRACKER=1`).

---

## Federation context

Per discipline: `USERS.md` (consumers), `STANDARDS_NOTE.md`
(L2 argument), `docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`
(per-rule status). Same federation pattern as every other
`mgf-vm-*` sibling.

## Reporting issues

- **Feedback / design pushback / API friction**: file in this
  repo's `FEEDBACK.md` (or `mgf-vm-core`'s if it's about the
  contracts upstream).
- **Security vulnerabilities**: see `SECURITY.md`.
