Quick Start

1. Launch the Dev Environment

mvmctl dev

This single command detects your platform and handles everything. Builds run in a builder microVM that mvm sets up automatically — you don’t need Nix on your host. The builder owns its own /nix/store and keeps it warm across builds. Where the builder VM runs depends on your platform:

On Linux with /dev/kvm:

Selects Firecracker as the runtime backend
Bootstraps the builder microVM on first build (one-time fetch); nix build runs inside it
Drops you into a dev shell

On macOS (Apple Silicon or Intel):

Selects libkrun (libkrun on Hypervisor.framework)
Same builder microVM, hosted on libkrun
Drops you into a dev shell

On Linux without KVM:

Falls back to libkrun in software-emulation mode (slower; meant for CI / sandboxed CI runners)
Same builder-microVM flow

Docker fallback (any platform):

If no hypervisor backend works, falls back to Docker
Runs your workload in a container with pause/resume support; security collapses to Tier 3

Inside the dev shell your project directory is bind-mounted at /work. Exit with exit or Ctrl+D — background services keep running.

2. Day-to-Day Commands

mvmctl ls         # List running VMs (aliases: ps, status)
mvmctl dev shell  # Open a shell in the dev microVM
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. Manifests

A manifest is the project-local build contract. It sits next to flake.nix and records the flake target plus runtime sizing:

mvmctl init base-worker --preset worker
cd base-worker
$EDITOR mvm.toml
mvmctl build
mvmctl up

Use mvmctl manifest ls and mvmctl manifest info to inspect built manifest slots. See Manifests for the full flow.

5. Image Catalog

Browse the bundled catalog and scaffold from a curated entry:

mvmctl catalog list                       # Browse available entries
mvmctl init my-app --catalog minimal      # Scaffold from a catalog entry
mvmctl build my-app                       # Build the manifest
mvmctl up my-app                          # Boot the VM

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. Sandboxed One-Shot Commands

mvmctl exec boots a fresh transient microVM, runs a single command, and tears it down on exit — like docker run --rm, but with a Firecracker microVM as the sandbox. No --flake or --manifest needed; the bundled default image boots automatically the first time.

mvmctl exec -- uname -a                            # bundled default image
mvmctl exec --add-dir .:/work -- ls /work          # share host dir, read-only
mvmctl exec --env DEBUG=1 -- env | grep DEBUG      # inject env vars
mvmctl exec --manifest my-tpl -- /bin/true         # registered template

When you reuse a registered template that has a captured snapshot, exec restores from the snapshot instead of cold-booting — typically sub-second. See the Sandboxed Exec guide for details.

8. Named Networks

Create isolated networks for different projects:

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

9. Diagnostics & Security

mvmctl doctor           # Deps, available backends, and security posture (one report)
mvmctl logs vm1         # View guest console logs
mvmctl cache info       # Cache directory disk usage

Next Steps

Your First MicroVM — write a Nix flake and boot it
Sandboxed Exec — run a single command in a fresh microVM
CLI Commands — full command reference
Manifests — reusable base images via mvm.toml
Troubleshooting — common issues