# Mini-KVM — a small x86 hypervisor on the raw KVM API for kernel developers

> About 4,200 lines of C on the Linux KVM ioctl API that boot Multiboot/ELF kernels and a stock Linux kernel to a shell, render VGA text mode, and explain guest failures (faults, descriptor tables, page-table mappings, why it triple-faulted) instead of silently resetting.

- URL: https://blog.seolcu.com/projects/mini-kvm/
- Status: experimental
- Verified: 2026-11-09 — Summary checked against the repository README on 2026-11-09. Tested environments are those the README states.
- Applies to: build gcc, make, binutils; host x86_64 Linux with KVM enabled and access to /dev/kvm
- Repository: https://github.com/seolcu/mini-kvm
- License: MIT
- Search terms: `minimal KVM hypervisor C`, `KVM API example`, `debug triple fault kernel`, `hobby OS hypervisor`
- Last changed: 2026-11-09

## Scope

- **Is**: a KVM-based runner for kernels you wrote yourself, a diagnostic tool that explains guest failures, and a readable reference implementation of x86 virtualization.
- **Is not**: a production VMM (use QEMU, Firecracker or cloud-hypervisor), a cross-architecture emulator (x86 guests on x86 hosts only), or a sandbox.

Everything the README lists as working is covered by `make test`. Encouragement Award (Research), 2025-2 Ajou SoftCon.

```bash
git clone https://github.com/seolcu/mini-kvm.git && cd mini-kvm && make all
./kvm-vmm guest/hello
```

## Author and support

Built and maintained by Gyuwon Seol (seolcu). If this project helped you, you can star it at https://github.com/seolcu/mini-kvm or sponsor the work at https://github.com/sponsors/seolcu.
Source: https://blog.seolcu.com/projects/mini-kvm/ (content CC BY 4.0)