# STARTHERE — mgf-vm-libvirt

> **Sibling library in the Magogi Foundation federation.**
> See [README.md](README.md) for what this library does; see
> [vm-vmanager-docs/component-specs/contracts.md](https://codeberg.org/magogi-admin/vm-vmanager-docs/src/branch/main/component-specs/contracts.md)
> for the surface (the `mgf-vm-core` contracts it implements); see
> [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md)
> for the federation contract.

`mgf-vm-libvirt` is the libvirt backend driver — it implements
`mgf-vm-core`'s `HypervisorBackend` and `StorageBackend` Protocols
against libvirt / KVM / QEMU. It wraps (not marries) libvirt: the
sprawling domain XML and the thin `libvirt-python` binding stay
contained below the adapter; everything above sees clean typed Python.

---

## For consumers (using this library)

1. **Install the system binding first** — the adapter needs the
   ABI-matched libvirt Python binding from apt, not PyPI:
   ```bash
   sudo apt install python3-libvirt libvirt-daemon-system
   ```
2. **Pin** in your `pyproject.toml`:
   ```toml
   dependencies = ["mgf-vm-libvirt>=X.Y,<X.$((Y+1))"]
   ```
   See [CHANGELOG.md](CHANGELOG.md) for the current minor.
3. **Install:** `pip install mgf-vm-libvirt` (create dev venvs with
   `uv venv --system-site-packages` so the system binding resolves).
4. **Use** the adapter through the `mgf-vm-core` contracts:
   ```python
   from mgf.vm.libvirt import LibvirtAdapter

   adapter = LibvirtAdapter("qemu:///system")
   domain_id = adapter.define(spec)
   adapter.start(domain_id)
   ```
5. **Bootstrap your app** with mgf-common first — see
   [mgf-common/STARTHERE.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/STARTHERE.md).
6. **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).
7. **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 contracts this adapter implements live in `vm-vmanager-docs`.

---

## Quick links

| Resource | Where |
|---|---|
| Library purpose | [README.md](README.md) |
| Contracts implemented | [vm-vmanager-docs/component-specs/contracts.md](https://codeberg.org/magogi-admin/vm-vmanager-docs/src/branch/main/component-specs/contracts.md) |
| Release notes | [CHANGELOG.md](CHANGELOG.md) |
| What I depend on / who depends on me | [DEPS.md](DEPS.md) |
| Conformance ledger | [docs/inprogress/MGF_STANDARDS_CONFORMANCE.md](docs/inprogress/MGF_STANDARDS_CONFORMANCE.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/) |
