Quick Start

1. Launch the Dev Environment

mvmctl dev

This single command detects your platform and handles everything:

On macOS 26+ (Apple Silicon):

1. Uses Apple Virtualization.framework directly — no Lima needed
2. Drops you into a dev shell

On macOS <26 or Linux without KVM:

1. Installs Lima if not present
2. Creates and starts a Lima VM with /dev/kvm
3. Installs Nix and Firecracker inside the Lima VM
4. Drops you into the Lima VM shell

On Linux with /dev/kvm:

1. Skips Lima entirely
2. Installs Nix and Firecracker natively on the host
3. Drops you into a dev shell

Docker fallback (any platform):

1. If no hypervisor or KVM is available, falls back to Docker
2. Runs your workload in a container with pause/resume support

Inside the dev shell, your home directory (~) is mounted read/write (Lima) or directly available (native Linux) — your project files are right there. Nix, Firecracker, and /dev/kvm are all available.

Exit the shell with exit or Ctrl+D — the Lima VM (if used) keeps running in the background.

Note

On macOS / Linux without KVM, the first run downloads ~500MB of assets (Lima VM image). On native Linux, setup is much faster. Subsequent runs start in seconds on all platforms.

2. Day-to-Day Commands

mvmctl ls         # List running VMs (aliases: ps, status)
mvmctl dev shell  # Open a shell in the Lima VM
mvmctl down       # Stop all running VMs
mvmctl doctor     # Check system dependencies and configuration
mvmctl console vm # Interactive shell into a running VM (PTY-over-vsock)

3. Build and Run

Build a microVM image and run it in one command:

mvmctl up --flake . --cpus 2 --memory 1024

Run in background with port forwarding:

mvmctl up --flake . -d -p 8080:8080

Or build separately:

mvmctl build --flake . --profile minimal
mvmctl up --flake .

4. Templates

Build a base image once and share it across machines:

mvmctl template create base-worker \
    --flake . \
    --profile minimal \
    --role worker \
    --cpus 2 --mem 1024

mvmctl template build base-worker
mvmctl up --template base-worker

5. Image Catalog

Browse and build images without writing Nix flakes yourself:

mvmctl image list           # Browse available images
mvmctl image fetch minimal  # Build from catalog (creates template + Nix build)
mvmctl up --template minimal

6. Interactive Console

Access a running VM without SSH — uses PTY-over-vsock:

mvmctl console myvm                    # Interactive shell
mvmctl console myvm --command "ls -la" # One-shot command

7. Named Networks

Create isolated networks for different projects:

mvmctl network create myproject
mvmctl up --flake . --network myproject
mvmctl network list

8. Diagnostics & Security

mvmctl doctor           # Check system dependencies, available backends
mvmctl logs vm1         # View guest console logs
mvmctl security status  # Security posture evaluation
mvmctl cache info       # Cache directory disk usage

Next Steps

• Your First MicroVM — write a Nix flake and boot it
• CLI Commands — full command reference
• Templates — reusable base images
• Troubleshooting — common issues