First-Use Happy Paths

mvm has five primary audiences. Each one has a three-command happy path that takes you from “I have a thing to run” to “it’s running under mvm.” Pair each path with mvmctl doctor --workflow <name> to preflight only the host requirements that matter for your audience — nothing more, nothing less.

Audience	Preflight	What you’re doing
CLI user with a flake	--workflow cli-run	Boot a microVM from a Nix flake.
Python SDK user	--workflow python-sdk	Run a @mvm.app()-decorated Python script.
TypeScript / Node SDK user	--workflow typescript-sdk	Run an mvm.app() TypeScript app.
Prebuilt bundle operator	--workflow bundle-run	Launch a signed .mvmpkg artifact.
mvmctl dev user	--workflow dev-shell	Drop into a builder-VM shell for tinkering.

The preflight filter (plan 74 W5 / ADR-050 §1) only fails on missing prerequisites your workflow actually needs. A bundle operator no longer sees a “missing cargo” failure they don’t care about; a mvmctl dev user no longer needs host rustup.

CLI user with a flake

You have a flake.nix (or want to scaffold one) and want a microVM booted from it.

mvmctl doctor --workflow cli-run                # preflight
mvmctl up --flake . --cpus 2 --memory 1024      # build + boot
mvmctl down                                     # tear down

The first run downloads the builder VM image (or builds it from a source checkout); subsequent runs reuse the warm builder. Skip the --cpus / --memory flags to get the defaults from ~/.mvm/config.toml.

Failure recovery:

• host nix not required errors → none expected. mvm’s builder VM owns Nix; the host doesn’t need it.
• dev VM not running — run mvmctl dev up to verify → that’s just doctor telling you tool checks were skipped because the builder VM is asleep. It’s not a failure; mvmctl up boots it on demand.
• disk space < N GiB → free space on ~/.mvm/ (default cache location); mvmctl cache info shows what’s there.

Python SDK user

You have a Python file with an @mvm.app() decorator. mvm compiles the script to an artifact, builds the rootfs, and exposes it as a callable function.

mvmctl doctor --workflow python-sdk                              # preflight
mvmctl compile my_app.py --out /tmp/my-app && mvmctl up my-app   # compile + boot
mvmctl invoke my-app --input name='ari'                          # call

mvmctl compile parses the decorator statically; user code does not execute on the host (only inside the microVM). mvmctl invoke accepts function arguments via --input key=value (repeatable). See SDK guide for the decorator surface.

Failure recovery:

• app_deps_gate refused (prod profile) → CVE finding in your dependencies’ sealed volume. mvmctl deps inspect <vol> shows the offending entries; --dev admits high-severity findings for local iteration.
• compile error: missing @mvm.app() decorator → the file must declare exactly one decorated function.

TypeScript / Node SDK user

Same shape as the Python flow with a .ts (or .js) entry file.

mvmctl doctor --workflow typescript-sdk                          # preflight
mvmctl compile my-app.ts --out /tmp/my-app && mvmctl up my-app   # compile + boot
mvmctl invoke my-app --input name='ari'                          # call

The preflight specifically checks the local TypeScript runner (bun, tsx, or deno) — pick the one your project uses. doctor --workflow typescript-sdk flags it if none of them are available.

Failure recovery:

• no TypeScript runner found → install one of bun, tsx, or deno. mvm picks whichever is on $PATH.

Prebuilt bundle operator

You’re not building anything — you have a signed .mvmpkg artifact to launch.

mvmctl doctor --workflow bundle-run             # preflight (no host rust needed)
mvmctl up --bundle ./my-app.mvmpkg              # boot
mvmctl down                                     # tear down

bundle-run doctor scope explicitly drops prerequisites and tools — a missing host cargo or builder-VM Nix doesn’t block bundle launches. The platform + security + disk-space checks remain.

Failure recovery:

• bundle signature invalid → the .mvmpkg’s manifest signature didn’t match the local trust store. Source bundles from a trusted publisher; mvmctl bundle verify <path> exits non-zero on mismatch without launching.
• bundle pin missing (audit-chain admission) → the supervisor’s signed-plan path failed to find a matching PlanArtifact. Pull a fresh copy from the publisher.

mvmctl dev user

You want a shell with a real Linux toolchain — for building, testing, or just exploring.

mvmctl doctor --workflow dev-shell              # preflight (no host rust needed)
mvmctl dev                                      # boot + drop into shell
# inside the shell: do work; exit / Ctrl+D returns you to the host

mvmctl dev auto-bootstraps the first time (downloads the dev image or builds it locally from nix/images/dev-shell/). Your project directory is bind-mounted at /work. Background services keep running after you exit; mvmctl dev down stops them.

Failure recovery:

• builder VM image missing → mvmctl dev up downloads or builds it. From a source checkout, the in-repo flakes are always preferred over published artifacts.
• dev shell exited immediately with no command output → check ~/.mvm/dev/console.log for the kernel/init transcript. Plan 72 W5.D documented the nine bring-up bugs that produced this symptom; if you hit one of them the log names it.

See also

• mvmctl doctor — the full diagnostic command, including the --workflow flag added by plan 74 W5.
• Quick Start — the broader feature tour.
• Your First MicroVM — write a Nix flake from scratch.
• SDK guide — the Python and TypeScript decorator surface in detail.
• Sandboxed Exec — one-shot transient microVMs for docker run --rm-style use.