# STARTHERE — mgf-vm-firecracker

> **Sibling library in the Magogi Foundation federation.**
> See [README.md](README.md) for what this library does; see
> [DEPS.md](DEPS.md) / [DEPS.md](DEPS.md) for who depends on it;
> see
> [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md)
> for the federation contract.

`mgf-vm-firecracker` is the Firecracker microVM backend driver —
it implements `mgf-vm-core`'s `HypervisorBackend` +
`StorageBackend` against Firecracker (jailer-based isolation, a
REST API over a Unix socket, raw images, full-state snapshots, no
live migration). It is the canonical *second adapter* (D-F2) that
validates the wrap-don't-marry seam against an engine meaningfully
different from libvirt.

---

## For consumers (using this library)

1. **Pin** in your `pyproject.toml`:
   ```toml
   dependencies = ["mgf-vm-firecracker>=0.1,<0.2"]
   ```
   See [CHANGELOG.md](CHANGELOG.md) for the current minor.
2. **Install:** `uv add mgf-vm-firecracker` (or
   `pip install mgf-vm-firecracker`). The host also needs the
   `firecracker` + `jailer` binaries from a Firecracker release.
3. **Use the surface** — the public surface is `FirecrackerAdapter`
   + its constructor (the Protocol surface is owned by
   `mgf-vm-core`):
   ```python
   from mgf.vm.firecracker import FirecrackerAdapter
   ```
4. **Bootstrap your app** with mgf-common first — see
   [mgf-common/STARTHERE.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/STARTHERE.md).
5. **Adopt the federation contract** — file your
   `MGF_STANDARDS_CONFORMANCE.md` per
   [DOC-15](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md).
6. **Run** `mgf-common catch-up` periodically to verify
   federation drift; see [FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) §6.

---

## For contributors

See [CONTRIBUTING.md](CONTRIBUTING.md). Standards are inherited
from [mgf-common](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/).
The build playbook is `vm-vmanager-docs/developer/adding-an-adapter.md`;
the contract you implement is `vm-vmanager-docs/component-specs/contracts.md`
§3 (Hypervisor) / §4 (Storage).

---

## Quick links

| Resource | Where |
|---|---|
| Library purpose | [README.md](README.md) |
| Public surface | `FirecrackerAdapter` (`src/mgf/vm/firecracker/__init__.py`) |
| Release notes | [CHANGELOG.md](CHANGELOG.md) |
| What we depend on / who depends on us | [DEPS.md](DEPS.md) / [DEPS.md](DEPS.md) |
| Conformance ledger | [docs/inprogress/MGF_STANDARDS_CONFORMANCE.md](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md) |
| L2 conformance argument | [STANDARDS_NOTE.md](STANDARDS_NOTE.md) |
| Federation contract | [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) |
| Cross-project standards | [mgf-standard/docs/standards/](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/) |
