# mgf-vm-libvirt

> **The libvirt adapter for the Magogi Foundation distributed vm-vmanager-app.**
> Implements `mgf-vm-core`'s `HypervisorBackend` and `StorageBackend`
> Protocols against libvirt / KVM / QEMU. The wrap (not marry) of libvirt.

| Field | Value |
|---|---|
| **Status** | Pre-`0.1.0`. Phase 0 of the vm-vmanager-app roadmap. |
| **Federation sibling.** | Depends on `mgf-common>=0.38,<0.39` + `mgf-vm-core>=0.1,<0.2`. |
| **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.** | `python3-libvirt` from apt (ABI-matched to host `libvirtd`). |

---

## Where the docs live

**Everything load-bearing — what this adapter does, why it exists,
what its conformance obligations are — lives in the central docs:**

> **`vm-vmanager-docs`** — `~/PycharmProjects/vm-vmanager-docs/` ·
> Codeberg: `vm-vmanager-docs`

| What | Where |
|---|---|
| End-to-end architecture | `vm-vmanager-docs/ARCHITECTURE.md` |
| **The contracts this adapter implements** | `vm-vmanager-docs/component-specs/contracts.md` — §3 (Hypervisor), §4 (Storage) |
| Decision register (D-B2 = the split; D-F4 = storage separability) | `vm-vmanager-docs/DECISIONS.md` |
| Roadmap (Phase 0 Stream B) | `vm-vmanager-docs/ROADMAP.md` |
| Test strategy + integration tier | `vm-vmanager-docs/TESTING.md` |
| Dev loop (`LIBVIRT=1` opt-in) | `vm-vmanager-docs/DEV-LOOP.md` |

If you're here to *use* this adapter, you import `mgf-vm-core`'s
contracts and instantiate this adapter against them. If you're here
to *extend* this adapter, the spec is `contracts.md` — that is the
contract.

---

## What this library contains

(Phase 0 — see `vm-vmanager-docs/ROADMAP.md` Stream B.)

```
src/mgf/vm/libvirt/
├── __init__.py
├── py.typed
├── adapter.py         # LibvirtAdapter: HypervisorBackend + StorageBackend
├── xml/               # VmSpec ↔ libvirt domain XML translation (contained here)
├── errors.py          # libvirt → mgf-vm-core exceptions translation (EH-02)
└── _internal/         # private helpers; not importable by consumers
```

**Containment principle.** Libvirt's sprawling domain XML and its
thin Python binding ergonomics stay in this library. They never leak
above the adapter. Anything you see in `xml/` and the `libvirt-python`
import sites is the price; everything else above this adapter — `vm-core`,
the SDK, the clients — sees clean typed Python.

The adapter's surface is exactly the union of `HypervisorBackend` +
`StorageBackend` from `mgf-vm-core`. It MUST pass the
`mgf.vm.core.conformance` suite against a real `libvirtd`. See
[`tests/integration/`](tests/integration/) for the runner.

---

## Install (consumer)

```bash
sudo apt install python3-libvirt libvirt-daemon-system   # the system binding + daemon
pip install mgf-vm-libvirt
```

Use:

```python
from mgf.vm.libvirt import LibvirtAdapter

adapter = LibvirtAdapter("qemu:///system")
domain_id = adapter.define(spec)
adapter.start(domain_id)
```

## Develop

```bash
cd ~/PycharmProjects/mgf_vm_libvirt
uv venv --python 3.12 --system-site-packages         # pick up python3-libvirt
uv sync --extra dev
uv run pytest -q -m "not integration"                # unit only
uv run pytest -q -m integration                       # vs containerized libvirtd
uv run mypy --strict src/
uv run ruff check src tests
uv run lint-imports
```

For the integration tier you'll need Docker (for the libvirtd
container). The fixtures live in `tests/integration/conftest.py`.

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

---

## Federation context

`mgf-vm-libvirt` is a federation sibling. Depends on `mgf-common`
(foundation) and `mgf-vm-core` (the contracts). Depended on by
`vm-vmanager-agent` (which composes it with the `mgf-hrb` client to
form the per-host kernel).

Per federation discipline:
- **`USERS.md`** — who depends on this library
- **`STANDARDS_NOTE.md`** — conformance-level argument
- **`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`** — per-rule status

## 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`.
