Container speed, VM isolation.
mvmctl is the modern way to run microVMs — get the startup speed of containers with the security and isolation of traditional VMs. Built for developers who need lightweight, fast-booting virtual machines without the overhead.
- 🚀 Blazing fast — VMs boot in milliseconds, not minutes
- 🔥 Powered by Firecracker — AWS's battle-tested microVM technology, the engine behind Lambda and Fargate
- 🔒 Secure by default — Hardware-level isolation with KVM
- 📦 Works with your images — Ubuntu, Debian, Arch, and more
- ⚡ Simple CLI — One command to create, start, and SSH into a VM
- 💻 Console access — Interactive serial console without SSH (via
mvm console) - 🎯
Production ready(still under development to ensure stability) — Built for cloud-native and serverless workloads
# Create and SSH into a VM in under 60 seconds
mvm vm create --name myvm --image ubuntu-24.04
mvm vm ssh --name myvm-
Linux (x86_64 or aarch64) — Firecracker only runs on Linux
-
KVM access (
/dev/kvm):sudo usermod -aG kvm $USER # Log out and back in
-
Python 3.13+
-
System packages:
Ubuntu/Debian:
sudo apt-get install -y iproute2 iptables genisoimage qemu-utils
Arch Linux:
sudo pacman -S --needed iproute2 iptables libisoburn qemu-base
-
Root access (one-time): run
mvm initonce to create themvmgroup and a sudoers drop-in; normalmvmcommands require nosudoafter that. Checkprivileged_binariesin the src/mvmctl/assets/defaults.yaml for allowed binaries
No Python required:
curl -L -o mvm https://github.com/AlanD20/mvmctl/releases/latest/download/mvm
chmod +x mvm
sudo mv mvm /usr/local/bin/
mvm --helppipx install mvmctl
mvm --helppip install mvmctl
mvm --helpgit clone https://github.com/AlanD20/mvmctl
cd mvmctl
uv sync
uv run mvm --helpThe easiest way to get started is with the interactive setup wizard:
# Interactive setup - guides you through host init, downloads, and configuration
# (handles privilege escalation automatically when needed)
mvm init
# ⚠ Log out and back in when prompted, or run: newgrp mvm
# Create a key
mvm key create test
mvm key set-default test
# Create and start a VM
mvm vm create --name myvm --image ubuntu-24.04
# Follow the boot log until SSH is ready (~30-60 s)
mvm logs --name myvm --type boot --follow
# SSH in
mvm ssh --name myvm
# List running VMs
mvm vm ls
# Remove the VM when done
mvm vm rm --name myvmmvm vm create --name myvm --image ubuntu-24.04 # Create and start a VM
mvm vm ls # List all VMs
mvm vm ssh --name myvm # SSH into a VM
mvm console --name myvm # Console access (no SSH)
mvm vm rm --name myvm --force # Remove a VMmvm image fetch ubuntu-24.04 # Download an OS image
mvm image ls # List available images
mvm kernel fetch # Download Firecracker kernel
mvm bin fetch 1.15.0 # Download Firecracker binary
mvm key create mykey # Generate SSH keysudo mvm host init # One-time host setup (KVM, networking)
mvm cache prune # Clean up stale cacheSee docs/REFERENCES.md for the complete command reference with all flags and options.
Comprehensive documentation is available in the docs/ directory:
| Document | Description |
|---|---|
| docs/REFERENCES.md | Complete command reference — all mvm commands, flags, and optionsConfiguration — config files, environment variables, cache structure Cloud-Init — nocloud-net setup, security, modes |
| docs/TROUBLESHOOTING.md | Common issues and solutions Debug mode, permission fixes, network issues |
| docs/DEPENDENCIES.md | System dependencies by category Package names for Debian/Ubuntu/Arch |
| docs/custom-kernel.md | Building custom kernels for Firecracker |
| docs/RELEASE.md | Release process and distribution packages |
| docs/API.md | Python API reference for programmatic usage |
Produces a standalone single-file binary — no Python runtime required on the target machine:
git clone https://github.com/AlanD20/mvmctl
cd mvmctl
uv sync --group dev --group build
uv run python -m nuitka --onefile --output-dir=dist --output-filename=mvm \
--include-package=mvmctl --include-data-dir=src/mvmctl/assets=mvmctl/assets \
--lto=yes --enable-plugin=anti-bloat src/mvmctl/main.py
# Output: dist/mvm
./dist/mvm --versionSee docs/RELEASE.md for detailed build instructions.
~/.cache/mvmctl/
├── bin/ # Firecracker + jailer binaries
├── kernels/ # vmlinux kernel images
├── images/ # Root filesystem images (.ext4, .btrfs)
├── keys/ # Cached SSH public keys
├── networks/ # Per-network config + IP leases
├── vms/ # Per-VM state
│ └── <vm-name>/
│ ├── rootfs.ext4
│ ├── firecracker.json
│ ├── firecracker.log # Firecracker process log (--type os)
│ ├── firecracker.console.log # Serial console output (--type boot)
│ ├── firecracker.pid
│ ├── firecracker.sock # API socket (--enable-api-socket only)
│ └── cloud-init/
├── metadata.json # Asset registry (images, kernels, binaries)
└── audit.log # Append-only operation log
Common issues and quick fixes:
| Issue | Solution |
|---|---|
| Permission denied: /dev/kvm | sudo usermod -aG kvm $USER then log out/back in |
| Bridge not found | Run sudo mvm host init once |
| VM won't boot / SSH times out | Cloud-init takes 30-60s on first boot. Watch with mvm logs --name myvm --type boot --follow |
| Kernel not found | mvm kernel fetch |
| Image not found | mvm image fetch ubuntu-24.04 |
| NoCloud server failed | Port range exhausted. Check: sudo ss -tlnp | grep -E ':(8[0-9]{3}|9[0-9]{3})' |
See docs/TROUBLESHOOTING.md for complete troubleshooting guide including:
- Debug mode
- Console relay issues
- Network permission problems
- Cache corruption fixes
Contributions are welcome! See CONTRIBUTING.md for the full guide on:
- Development setup
- Running tests and linting
- Adding new commands and images
- Build system and version bumping
- Development guidelines
MIT — see LICENSE.