# 🚀 MNMIVM

### *Fire-and-Forget Virtual Machines*

![MNMIVM Hero](./assets/tuxrockets.jpg)

**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.