239 lines
5 KiB
Markdown
239 lines
5 KiB
Markdown
|
||
# 🚀 MNMIVM
|
||
|
||
### *Fire-and-Forget Virtual Machines*
|
||
|
||
|
||
|
||
**MNMIVM** is a minimal, single-binary VM launcher built on **QEMU + KVM + cloud-init**.
|
||
It is designed for *fast iteration*, *ephemeral usage*, and *zero ceremony*.
|
||
|
||
If Docker feels too constrained, and OpenStack / Proxmox feel like overkill — MNMIVM sits comfortably in the middle.
|
||
|
||
> Spin it up.
|
||
> Get a random port.
|
||
> SSH in.
|
||
> Done.
|
||
|
||
---
|
||
|
||
## ✨ What MNMIVM Is
|
||
|
||
* A **fire-and-forget VM launcher**
|
||
* A **CLI-first** virtualization tool
|
||
* A **thin orchestration layer**, not a platform
|
||
* A way to spin up *real Linux VMs* without running a control plane
|
||
|
||
MNMIVM intentionally avoids:
|
||
|
||
* Long-lived port bindings
|
||
* Static network assumptions
|
||
* Cluster state
|
||
* Databases
|
||
* APIs
|
||
* Daemons
|
||
|
||
It launches a VM, hands you SSH + VNC, and gets out of the way.
|
||
|
||
---
|
||
|
||
## 🧠 Design Philosophy
|
||
|
||
MNMIVM is built around a few hard rules:
|
||
|
||
* **No background services**
|
||
* **No required config files**
|
||
* **No global state beyond `/var/lib/microvm`**
|
||
* **Every VM is self-contained**
|
||
* **Cloud-init is the source of truth**
|
||
* **Root-only, explicit control**
|
||
|
||
This makes MNMIVM ideal for:
|
||
|
||
* Homelabs
|
||
* CI runners
|
||
* Testing OS images
|
||
* Disposable dev environments
|
||
* Learning QEMU/KVM internals
|
||
* “I just need a VM *right now*”
|
||
|
||
---
|
||
|
||
## 🆚 How It Compares (At a Glance)
|
||
|
||
| Feature | MNMIVM | Docker | LXC/LXD | Proxmox | OpenStack |
|
||
| ---------------------- | ----------- | ------- | ------- | ------- | --------- |
|
||
| Real VMs | ✅ | ❌ | ⚠️ | ✅ | ✅ |
|
||
| Cloud-init | ✅ | ❌ | ⚠️ | ✅ | ✅ |
|
||
| Requires Daemons | ❌ | ✅ | ✅ | ✅ | ✅ |
|
||
| Random Ports | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||
| Cluster-aware | ❌ | ❌ | ⚠️ | ✅ | ✅ |
|
||
| Stateful Control Plane | ❌ | ❌ | ⚠️ | ✅ | ✅ |
|
||
| Setup Time | **Seconds** | Minutes | Minutes | Hours | Days |
|
||
|
||
> MNMIVM behaves more like **`docker run` for VMs**, not like a cloud.
|
||
|
||
---
|
||
|
||
## 🧱 Architecture Overview
|
||
|
||
* **QEMU + KVM** for virtualization
|
||
* **User-mode networking** (no bridges required)
|
||
* **Cloud-init seed ISO** (`cidata`) for provisioning
|
||
* **QCOW2 backing images**
|
||
* **Ephemeral SSH + VNC ports**
|
||
* **State stored on disk only**
|
||
|
||
```
|
||
/var/lib/microvm/
|
||
├── images/ # Base cloud images
|
||
└── vms/
|
||
└── vm1/
|
||
├── disk.qcow2
|
||
├── seed.iso
|
||
├── pubkey.pub
|
||
├── os.name
|
||
├── ssh.port
|
||
├── vnc.port
|
||
└── vm.pid
|
||
```
|
||
|
||
No database.
|
||
No API.
|
||
No daemon.
|
||
|
||
---
|
||
|
||
## 📦 Supported Operating Systems
|
||
|
||
| OS | Version | Boot Mode |
|
||
| ------ | ----------- | --------- |
|
||
| Ubuntu | 24.04 LTS | BIOS |
|
||
| Debian | 13 (Trixie) | BIOS |
|
||
| Fedora | 43 Cloud | BIOS |
|
||
| Alpine | 3.22 | BIOS |
|
||
|
||
> UEFI images are intentionally avoided for simplicity and reliability.
|
||
|
||
---
|
||
|
||
## 🔑 SSH & Identity Management
|
||
|
||
* SSH keys are injected via **cloud-init**
|
||
* Keys are **fully replaced**, not appended
|
||
* Old keys are **revoked**
|
||
* `update-cloud` regenerates the seed ISO
|
||
* Changes apply on **next boot**
|
||
|
||
This gives you **real identity revocation**, not just key sprawl.
|
||
|
||
---
|
||
|
||
## 📀 Disk Behavior
|
||
|
||
* Base disk size is **12GB** (configurable constant)
|
||
* Uses **QCOW2 backing images**
|
||
* Root filesystem auto-expands on first boot
|
||
* Predictable, uniform VM sizing
|
||
|
||
This keeps resource usage balanced and intentional.
|
||
|
||
---
|
||
|
||
## 🧰 CLI Usage
|
||
|
||
### Create a VM
|
||
|
||
```bash
|
||
sudo mnmivm create vm1 --os debian --pubkey-path ~/.ssh/id_ed25519.pub
|
||
```
|
||
|
||
### Start a VM
|
||
|
||
```bash
|
||
sudo mnmivm start vm1
|
||
```
|
||
|
||
### Stop a VM
|
||
|
||
```bash
|
||
sudo mnmivm stop vm1
|
||
```
|
||
|
||
### Update SSH key (cloud-init)
|
||
|
||
```bash
|
||
sudo mnmivm update-cloud vm1 --pubkey-path newkey.pub
|
||
```
|
||
|
||
### List VMs
|
||
|
||
```bash
|
||
sudo mnmivm list
|
||
```
|
||
|
||
### Delete a VM
|
||
|
||
```bash
|
||
sudo mnmivm delete vm1
|
||
# Requires typing YES in all caps
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 VM List Output
|
||
|
||
MNMIVM renders a clean Unicode table showing:
|
||
|
||
* Name
|
||
* Running state
|
||
* OS
|
||
* SSH endpoint
|
||
* VNC endpoint
|
||
* SSH public key path
|
||
|
||
This makes it usable *without* scripting.
|
||
|
||
---
|
||
|
||
## ⚠️ What MNMIVM Is Not
|
||
|
||
* ❌ A cloud platform
|
||
* ❌ A hypervisor manager
|
||
* ❌ A replacement for Proxmox
|
||
* ❌ A Kubernetes node orchestrator
|
||
* ❌ A long-lived VM manager
|
||
|
||
If you want **policy, HA, scheduling, quotas, tenants** — use Proxmox or OpenStack.
|
||
|
||
If you want **a VM right now**, MNMIVM wins.
|
||
|
||
---
|
||
|
||
## 🧪 Project Status
|
||
|
||
* ✅ Actively working
|
||
* ✅ Under ~600 lines of Go
|
||
* ✅ No external Go dependencies
|
||
* ⚠️ API not stabilized yet
|
||
* ⚠️ CLI flags may evolve
|
||
|
||
This project is intentionally **hackable** and **readable**.
|
||
|
||
---
|
||
|
||
## 🐧 Why MNMIVM Exists
|
||
|
||
Sometimes you don’t want:
|
||
|
||
* A cluster
|
||
* A UI
|
||
* A dashboard
|
||
* A service mesh
|
||
|
||
You just want to:
|
||
|
||
> “Launch a VM and throw it into orbit.”
|
||
|
||
That’s MNMIVM.
|
||
|