# mvm Documentation Index mvm is a security-first local microVM runtime for building and running sandboxed workloads with signed plans, audited launches, and backend-specific snapshot recovery. Start at /skill.md for a single-page orientation aimed at coding agents. Every page listed below is also served as plain markdown with no navigation chrome: append `.md` to the page path with the trailing slash removed, so /guides/builder-vm/ is also available at /guides/builder-vm.md. ## Getting Started - [Installation](/getting-started/installation/): Install mvmctl on macOS or Linux. (markdown: /getting-started/installation.md) - [First-Use Happy Paths](/getting-started/happy-paths/): Three-command paths to get a microVM running for each mvm audience. (markdown: /getting-started/happy-paths.md) - [Quick Start](/getting-started/quickstart/): Get a microVM running in under 5 minutes. (markdown: /getting-started/quickstart.md) - [Python quickstart](/getting-started/python-quickstart/): Use the current Python SDK runtime surface and the static decorator compiler safely. (markdown: /getting-started/python-quickstart.md) - [Node.js quickstart](/getting-started/nodejs-quickstart/): Use the current TypeScript SDK runtime surface and static workload declarations. (markdown: /getting-started/nodejs-quickstart.md) - [Rust quickstart](/getting-started/rust-quickstart/): Declare mvm workloads from Rust and emit Workload IR. (markdown: /getting-started/rust-quickstart.md) - [Your First MicroVM](/getting-started/first-microvm/): Write a Nix flake and boot a microVM. (markdown: /getting-started/first-microvm.md) - [Connect an LLM](/getting-started/connect-an-llm/): Route model tool calls into an mvm sandbox with explicit boundaries. (markdown: /getting-started/connect-an-llm.md) - [Nix for mvm: A Beginner's Guide](/getting-started/nix-for-mvm/): Learn just enough Nix to write your first mvm flake — no prior Nix experience required. (markdown: /getting-started/nix-for-mvm.md) - [Core concepts](/getting-started/core-concepts/): The runtime, builder VM, Workload IR, plans, policies, and cold-mode states. (markdown: /getting-started/core-concepts.md) - [Design principles](/getting-started/design-principles/): The security-first rules that shape mvm developer experience. (markdown: /getting-started/design-principles.md) ## Install - [Install mvm on Linux](/install/linux/): mvm on Linux is the Tier 1 production target — Firecracker + KVM, no virtualization wrapper, sub-200ms cold boot. (markdown: /install/linux.md) - [Install mvm on macOS](/install/macos/): mvm on macOS supports Apple Silicon through Hypervisor.framework-backed local builder/runtime paths. Intel Macs are not a supported local microVM host. (markdown: /install/macos.md) - [Install mvm on Windows](/install/windows/): Neither native Windows nor WSL2 is a supported local microVM host. Use native Linux with /dev/kvm or an Apple Silicon Mac. (markdown: /install/windows.md) ## Working in the MicroVM - [Working in the MicroVM](/working/): Local sandbox management with mvmctl. (markdown: /working.md) - [Sandbox management](/working/sandbox-management/): Create, inspect, stop, pause, resume, and clean up local mvm sandboxes. (markdown: /working/sandbox-management.md) - [Lifecycle states](/working/lifecycle-states/): Running, stopped, paused, cold, restoring, and cleaned sandbox states. (markdown: /working/lifecycle-states.md) - [Run commands & processes](/working/commands/): Run commands in a microVM and choose the right command surface. (markdown: /working/commands.md) - [Filesystem operations](/working/filesystem/): Move files across the host and guest boundary safely. (markdown: /working/filesystem.md) - [Network & exposing ports](/working/network/): Control egress and expose guest services intentionally. (markdown: /working/network.md) - [Persistence, pause & resume](/working/persistence/): Keep or discard sandbox state intentionally. (markdown: /working/persistence.md) - [Cold mode](/working/cold-mode/): How mvm presents paused, sleeping, and snapshot-restored sandboxes. (markdown: /working/cold-mode.md) - [Snapshots and cold mode](/working/snapshots/): Pause a microVM into sealed state, create checkpoints, and restore later with explicit integrity checks. (markdown: /working/snapshots.md) ## Tutorials - [Tutorials](/tutorials/): Practical mvm workflows for agent sandboxes, code execution, file transfer, LLM tools, browser automation, services, and cold-mode recovery. (markdown: /tutorials.md) - [Agent sandbox](/tutorials/agent-sandbox/): Run generated or third-party agent code in a microVM with explicit build, network, file, and snapshot boundaries. (markdown: /tutorials/agent-sandbox.md) - [Coding agent](/tutorials/coding-agent/): Run coding-agent tasks in a microVM with explicit filesystem, network, and persistence boundaries. (markdown: /tutorials/coding-agent.md) - [Code execution](/tutorials/code-execution/): Execute commands and scripts inside an mvm microVM while keeping host state and secrets out of the default path. (markdown: /tutorials/code-execution.md) - [File transfer](/tutorials/file-transfer/): Move files in and out of a microVM without turning the whole host filesystem into the sandbox interface. (markdown: /tutorials/file-transfer.md) - [LLM tool integration](/tutorials/llm-tool-integration/): Use mvm as the execution backend for an LLM tool while keeping egress, secrets, and logs explicit. (markdown: /tutorials/llm-tool-integration.md) - [Browser automation](/tutorials/browser-automation/): Run browser automation inside a microVM with explicit credential, download, network, and persistence boundaries. (markdown: /tutorials/browser-automation.md) - [Desktop automation](/tutorials/desktop-automation/): Model desktop-style automation as a controlled sandbox workload. (markdown: /tutorials/desktop-automation.md) - [Interactive terminal](/tutorials/interactive-terminal/): Attach to a sandbox intentionally without making SSH the default control path. (markdown: /tutorials/interactive-terminal.md) - [Any language](/tutorials/any-language/): Run non-Python and non-Node workloads with Nix packages and command entrypoints. (markdown: /tutorials/any-language.md) - [Services and ports](/tutorials/services-and-ports/): Start a service inside a microVM and expose only the ports you intend to reach from the host. (markdown: /tutorials/services-and-ports.md) - [Long-running services](/tutorials/long-running-services/): Run services with readiness, ports, logs, lifecycle, and policy. (markdown: /tutorials/long-running-services.md) - [Error handling](/tutorials/error-handling/): Interpret build, admission, runtime, and restore failures. (markdown: /tutorials/error-handling.md) - [Cold-mode recovery](/tutorials/cold-mode-recovery/): Pause, save, restore, and wake sandboxes from backend-specific snapshot state. (markdown: /tutorials/cold-mode-recovery.md) ## Console - [Console](/console/): Interactive shell access to a running mvm microVM. (markdown: /console.md) - [Attach to a microVM](/console/attach/): Open an interactive shell to a running microVM. (markdown: /console/attach.md) - [Transparent rebuilds](/console/transparent-rebuild/): Rebuild a development image while preserving intentional workspace state. (markdown: /console/transparent-rebuild.md) ## Templates - [Templates](/templates/): Reusable mvm project blueprints built from manifests and Nix flakes. (markdown: /templates.md) - [Create a template](/templates/create/): Scaffold a reusable mvm project from a manifest and Nix flake. (markdown: /templates/create.md) - [Build & list](/templates/build/): Build manifest-backed templates and inspect the local mvm registry. (markdown: /templates/build.md) - [Template lifecycle](/templates/lifecycle/): Rebuild, verify, prune, and remove manifest-backed mvm templates. (markdown: /templates/lifecycle.md) ## Guides - [Guides](/guides/): Conceptual and operational guides for building, securing, and operating mvm sandboxes. (markdown: /guides.md) - [Writing Nix Flakes](/guides/nix-flakes/): Create custom Nix flakes that build microVM images for mvm. (markdown: /guides/nix-flakes.md) - [Nix and OCI](/guides/nix-and-oci/): How mvm positions Nix-built microVM artifacts and OCI image compatibility. (markdown: /guides/nix-and-oci.md) - [From dev loop to attested image](/guides/develop-to-attested/): Start from an OCI image or a Nix flake, capture what your workload actually needs, and end with a sealed, hashed, recorded artifact. (markdown: /guides/develop-to-attested.md) - [From Workload IR to MicroVM Image](/guides/ir-to-image/): How mvm lowers an SDK-emitted Workload IR through Nix factories into a bootable microVM rootfs. (markdown: /guides/ir-to-image.md) - [Building MicroVM Images](/guides/building-microvm-images/): How to build mvm microVM images from your own project — the mvm repository is a library, not a place to put your code. (markdown: /guides/building-microvm-images.md) - [Building from source](/guides/building-from-source/): Build mvm and docs from the repository. (markdown: /guides/building-from-source.md) - [Builder VM](/guides/builder-vm/): How mvm builds Linux microVM images from the host without requiring you to enter a dev shell or install host-side Nix. (markdown: /guides/builder-vm.md) - [Custom microVM kernels](/guides/kernels/): Build or download the slim builder/workload kernels mvm boots, with mvmctl build kernel build. (markdown: /guides/kernels.md) - [Sandboxed Exec](/guides/exec/): Run a single command inside a fresh microVM and tear it down on exit. (markdown: /guides/exec.md) - [Machine use cases](/guides/machine-use-cases/): Scenario-led guide for the mvmctl machine workflow. (markdown: /guides/machine-use-cases.md) - [Machine limitations](/guides/machine-limitations/): Explicit limits for the mvmctl machine workflow. (markdown: /guides/machine-limitations.md) - [Policy profiles](/guides/policy-profiles/): Choose the right run profile, host-share mode, and environment policy for a sandboxed workload. (markdown: /guides/policy-profiles.md) - [Config & Secrets Injection](/guides/config-secrets/): Inject custom config files and tightly scoped secret files onto microVM drives at boot time. (markdown: /guides/config-secrets.md) - [Secrets and credentials](/guides/secrets-and-credentials/): Use secret references, grants, redaction, and narrow delivery paths for sandboxed workloads. (markdown: /guides/secrets-and-credentials.md) - [Persistent workspaces](/guides/persistent-workspaces/): Use encrypted volumes, copy workflows, snapshots, and cleanup policies for stateful sandboxes. (markdown: /guides/persistent-workspaces.md) - [Audit and receipts](/guides/audit-and-receipts/): Use signed run receipts, audit chain entries, metrics, and boot reports without exposing payload data. (markdown: /guides/audit-and-receipts.md) - [Workload output streaming](/guides/workload-output-streaming/): Follow a microVM's stdout and stderr while it runs and after it exits, verify what you read, and understand what a truncation or gap notice means. (markdown: /guides/workload-output-streaming.md) - [Workload input](/guides/workload-input/): The host-to-guest stdin channel — how to stream into a workload with `machine run --entrypoint --stdin -`, the grant it needs in the signed plan, the single-writer lease, the secret scan, explicit EOF, and why a sealed production run refuses a shell entrypoint. (markdown: /guides/workload-input.md) - [Stream edges between workloads](/guides/fleet-stream-edges/): How one workload's output feeds another's stdin, what redaction does to data in flight, and what happens when a consumer falls behind. (markdown: /guides/fleet-stream-edges.md) - [Observability and results](/guides/observability-and-results/): Correlate command results, logs, receipts, audit IDs, boot reports, and metrics without exposing payload data. (markdown: /guides/observability-and-results.md) - [Manifests](/guides/manifests/): How mvmctl turns an mvm.toml into a built image or a named machine. (markdown: /guides/manifests.md) - [Networking](/guides/networking/): Network layout and connectivity in mvmctl microVMs. (markdown: /guides/networking.md) - [Network egress policy](/guides/network-egress-policy/): Apply deny-first outbound network rules for agents, services, package installs, and browser automation. (markdown: /guides/network-egress-policy.md) - [AI agent integration](/guides/ai-agent-integration/): Connect agents to mvm sandboxes with explicit policy and audit boundaries. (markdown: /guides/ai-agent-integration.md) - [Agent tool contract](/guides/agent-tool-contract/): A secure contract for using mvm sandboxes as LLM and coding-agent tools. (markdown: /guides/agent-tool-contract.md) - [Image registry configuration](/guides/image-registry-configuration/): OCI registry use as a compatibility path. (markdown: /guides/image-registry-configuration.md) - [macOS sandbox debugging](/guides/macos-sandbox-debugging/): Debug local macOS workflows while keeping Linux runtime work in the builder VM. (markdown: /guides/macos-sandbox-debugging.md) - [Dev Image](/guides/dev-image/): How to boot a development microVM with an interactive shell, the fastest zero-config path to one, and how to write your own. (markdown: /guides/dev-image.md) - [Verifying Release Artifacts](/guides/verify-release/): How to verify that an mvmctl release binary was built by the official CI pipeline using cosign keyless signing. (markdown: /guides/verify-release.md) - [Air-gapped Bootstrap](/guides/airgapped-bootstrap/): How to run mvmctl in environments that can't reach github.com without disabling supply-chain verification. (markdown: /guides/airgapped-bootstrap.md) - [Troubleshooting](/guides/troubleshooting/): Common issues and their solutions. (markdown: /guides/troubleshooting.md) - [WSL2 notes for mvm](/guides/windows-wsl2/): WSL2 workload-host notes for mvm. WSL2 with nested KVM is supported for the libkrun-backed workload path. (markdown: /guides/windows-wsl2.md) - [Windows troubleshooting](/guides/windows-troubleshooting/): Windows-specific notes for mvm. Native Windows is unsupported; WSL2 with nested KVM is the supported libkrun-backed workload path. (markdown: /guides/windows-troubleshooting.md) ## Examples - [Examples](/examples/): Practical mvm patterns for agents, CI builders, development VMs, and code execution. (markdown: /examples.md) - [AI agent sandbox](/examples/ai-agent-sandbox/): Run agent tool code in an mvm microVM with explicit policy. (markdown: /examples/ai-agent-sandbox.md) - [CI/CD ephemeral builder](/examples/ci-cd-ephemeral-builder/): Use mvm in CI without preserving accidental runtime state. (markdown: /examples/ci-cd-ephemeral-builder.md) - [Reproducible dev VM from a flake](/examples/dev-vm-from-flake/): Build a repeatable local development microVM from Nix. (markdown: /examples/dev-vm-from-flake.md) - [Code interpreter pattern](/examples/code-interpreter/): Run user-provided code in a bounded mvm sandbox. (markdown: /examples/code-interpreter.md) ## Security - [Capability status](/security/capability-status/): The single authoritative table of what mvm ships today, what is in preview, and what is roadmap. Every marketing surface inherits from this page. (markdown: /security/capability-status.md) - [CVE demonstrations](/security/cve-demonstrations/): Public, reproducible exploit demonstrations with explicit evidence limits. (markdown: /security/cve-demonstrations.md) - [The security review](/security/security-review/): The questions an enterprise security team asks before approving an agent deployment, and the mvm mechanism that answers each one. (markdown: /security/security-review.md) - [The Matryoshka model: how mvm isolates untrusted code](/security/matryoshka/): mvm runs untrusted Linux workloads in microVMs. This page explains the five trust layers, the CI-enforced security claims, and which claims hold for each backend. (markdown: /security/matryoshka.md) - [Security claim ledger](/security/claim-ledger/): The public index of security and DX claims, their status, and the evidence needed before docs may rely on them. (markdown: /security/claim-ledger.md) - [Threat model](/security/threat-model/): What mvm is designed to protect, and what remains outside the boundary. (markdown: /security/threat-model.md) - [CI-enforced security claims](/security/ci-claims/): The security claims that must stay backed by tests and documentation. (markdown: /security/ci-claims.md) - [Verified boot](/security/verified-boot/): Rootfs integrity posture and backend-specific verification limits. (markdown: /security/verified-boot.md) - [Sandbox parity status](/security/sandbox-parity-status/): Which sandbox-parity claims mvm makes today, and which are Preview, Planned, or deliberately Not claimed. Backed by the cargo xtask check-doc-claims lint. (markdown: /security/sandbox-parity-status.md) ## Architecture - [Architecture overview](/architecture/overview/): How mvm builds and runs secure local microVM workloads. (markdown: /architecture/overview.md) - [Core components](/architecture/core-components/): The moving parts that make up the secure sandbox product. (markdown: /architecture/core-components.md) - [Boot flow](/architecture/boot-flow/): How a microVM boots the universal initramfs, receives its environment over vsock, and starts the workload. (markdown: /architecture/boot-flow.md) - [Control surfaces](/architecture/control-surfaces/): The supported local ways to control mvm sandboxes, plus the surfaces that are partial or not claimed. (markdown: /architecture/control-surfaces.md) - [Security and isolation](/architecture/security-isolation/): Security-first architecture boundaries for mvm. (markdown: /architecture/security-isolation.md) - [Networking and storage](/architecture/networking-storage/): How egress, ports, files, volumes, and snapshots fit the mvm model. (markdown: /architecture/networking-storage.md) ## Resources - [Docs for agents](/llms-index/): Where an LLM or coding agent should start — the generated documentation index, plain-markdown page twins, and a single-page orientation. (markdown: /llms-index.md) - [FAQ](/resources/faq/): Common questions about mvm, SDKs, Nix, OCI, and platform support. (markdown: /resources/faq.md) - [Changelog](/resources/changelog/): Product documentation changelog. (markdown: /resources/changelog.md) ## SDK - [SDK overview](/sdk/): The two SDK surfaces mvm exposes: runtime lifecycle APIs and decorator-style workload declarations. (markdown: /sdk.md) - [Runtime SDK](/sdk/runtime/): Current and planned lifecycle APIs for creating, executing, inspecting, snapshotting, and stopping mvm sandboxes from application code. (markdown: /sdk/runtime.md) - [Runtime modes](/sdk/runtime-modes/): Understand record, plan, and live SDK execution modes and when host-side user code is executed. (markdown: /sdk/runtime-modes.md) - [SDK security model](/sdk/security-model/): Host execution, guest execution, secrets, network, audit, and state-retention rules for SDK workflows. (markdown: /sdk/security-model.md) - [SDK operations cookbook](/sdk/operations-cookbook/): Current Python and TypeScript SDK calls, secure defaults, target helpers, and CLI fallbacks for common sandbox operations. (markdown: /sdk/operations-cookbook.md) - [Decorator SDK](/sdk/decorator/): Declare reproducible mvm workloads in Python or TypeScript and compile them into Workload IR without running untrusted code. (markdown: /sdk/decorator.md) - [Declaration workflow](/sdk/declaration-workflow/): Compile Python and TypeScript workload declarations into Workload IR and staged build artifacts without importing user modules. (markdown: /sdk/declaration-workflow.md) - [Declaration cookbook](/sdk/declaration-cookbook/): Practical Python and TypeScript decorator-style declarations for secure Nix-first microVM workloads. (markdown: /sdk/declaration-cookbook.md) - [Sandbox types](/sdk/sandbox-types/): Product-level sandbox patterns and their current mvm implementation status. (markdown: /sdk/sandbox-types.md) - [Lifecycle matrix](/sdk/lifecycle-matrix/): Current CLI and SDK support for sandbox create, command, file, log, network, snapshot, cold, and cleanup operations. (markdown: /sdk/lifecycle-matrix.md) - [Errors & metrics](/sdk/errors-metrics/): Error classes, exit results, metrics, and audit identifiers expected from mvm SDK surfaces. (markdown: /sdk/errors-metrics.md) - [SDK reference](/sdk/reference/): Current and planned language SDK surfaces for mvm. (markdown: /sdk/reference.md) - [Python SDK](/sdk/python/): Python runtime and decorator SDK status. (markdown: /sdk/python.md) - [Node.js SDK](/sdk/nodejs/): TypeScript and Node.js runtime and decorator SDK status. (markdown: /sdk/nodejs.md) - [Rust SDK](/sdk/rust/): Rust build-time SDK and Workload IR contract. (markdown: /sdk/rust.md) ## Reference - [CLI Commands](/reference/cli-commands/): Complete command reference for mvmctl. (markdown: /reference/cli-commands.md) - [Evidence Archive Format](/reference/mvmev-format/): Normative .mvmev member layout, canonicalization, and offline verification rules. (markdown: /reference/mvmev-format.md) - [Programmatic use](/reference/programmatic-use/): Drive mvmctl from scripts, CI jobs, and local automation. (markdown: /reference/programmatic-use.md) - [Architecture](/reference/architecture/): Workspace structure, backend layering, dependency graph, and canonical trait seams. (markdown: /reference/architecture.md) - [Isolation tiers](/reference/isolation-tiers/): How mvm's full-OS microVM isolation compares to the no-OS / no-kernel function-sandbox tier on workload compatibility, security posture, and startup latency. (markdown: /reference/isolation-tiers.md) - [Platform support](/reference/platform-support/): Current host, architecture, backend, and support-status matrix for mvm. (markdown: /reference/platform-support.md) - [Filesystem & Drives](/reference/filesystem/): Drive model, mount points, and filesystem layout inside microVMs. (markdown: /reference/filesystem.md) - [Guest Agent](/reference/guest-agent/): The mvm guest agent provides host visibility and control over microVMs via vsock. (markdown: /reference/guest-agent.md) - [Limits & resources](/reference/limits/): CPU, memory, disk, network, and backend limits for local mvm workloads. (markdown: /reference/limits.md) - [Launch performance](/reference/performance/): The dispatch-window budgets mvm gates every launch against, the lanes they are measured in, and how to reproduce a measurement. (markdown: /reference/performance.md) - [Releases & downloads](/reference/releases/): How mvm's v* release tags publish binaries, kernels, and images — and how each install path consumes them. (markdown: /reference/releases.md) ## Contributing - [Development Guide](/contributing/development/): Getting started as a contributor to mvm. (markdown: /contributing/development.md) ## Other pages - [Adding an architecture or backend](/contributing/adding-an-arch-or-backend/): How to extend the architecture-aware artifact model with a new CPU architecture or microVM backend. (markdown: /contributing/adding-an-arch-or-backend.md) - [Capturing a Project Environment](/guides/capture/): Inspect a Linux project, resolve its environment, and render a reviewable MVM definition. (markdown: /guides/capture.md) - [FlowMux networking](/guides/flowmux-networking/): Policy-enforced workload networking through one authenticated vsock path. (markdown: /guides/flowmux-networking.md) - [Migrating from mvmforge](/guides/mvmforge-migration/): mvmforge has been merged into mvm. Workloads previously authored against ../mvmforge import from `mvm` instead; the surface is otherwise unchanged. (markdown: /guides/mvmforge-migration.md) - [SDK — Python and TypeScript](/guides/sdk/): Declare microVM workloads with the mvm Python and TypeScript SDKs. Decorator-style author surface; mvmctl build compile / deploy compiles the same source statically without executing it. (markdown: /guides/sdk.md) - [mvm](/): A secure execution layer for code you can't fully trust — built security-first for AI agents. ## Claim rules - Strong claims need Shipped, Preview, Planned, or Not claimed status. - Runtime SDK lifecycle APIs are partial until shared SDK tests cover the full lifecycle. - Persistent builder DX is Preview until top-level `dev up` and `build` behavior is proven. - OCI examples should use digest-pinned or clearly local/dev references. - Secret examples should use references or redacted example values, not plaintext credentials.