LLM documentation index

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.

Getting Started

• Installation: install the CLI and prerequisites.
• Quick Start: first local run.
• Python quickstart: current Python SDK runtime and declaration paths.
• Node.js quickstart: current TypeScript SDK runtime and declaration paths.
• Core concepts: runtime, builder VM, Workload IR, plans, policy, and cold mode.
• Design principles: security-first DX principles.
• Builder VM: host command, Linux build boundary, persistent builder personas.
• Nix and OCI: Nix-first auditability and OCI compatibility.
• Policy profiles: restrictive, standard, dev, permissive, host-share, env, and seccomp posture.
• Secrets and credentials: reference-first credential delivery, grants, redaction, and retention rules.
• Persistent workspaces: encrypted volumes, host-backed mounts, copy workflows, snapshots, and cleanup policy.
• Audit and receipts: signed run receipts, audit chain checks, decision-provenance export (JSON and TIBET-JSON), PROV-O/Turtle export, metrics, and boot reports.
• Workload output streaming: following stdout/stderr live and after exit, the verification model, the --stream filter, retention, and the three limits.
• Observability and results: result correlation, logs, receipts, audit IDs, boot reports, metrics, and redaction rules.
• Network egress policy: deny-first outbound grants for agents, services, package installs, and browser automation.
• Agent tool contract: model-facing sandbox request/response schema, validation, redaction, and retention rules.

SDK

• SDK overview: runtime lifecycle API versus decorator declaration API.
• Runtime SDK: imperative lifecycle surface.
• Runtime modes: record, plan, live, and static declaration execution modes.
• SDK security model: host execution, guest execution, secrets, network, audit, and state retention.
• Operations cookbook: current SDK calls, target helpers, and secure CLI fallbacks.
• Decorator SDK: static workload declaration and Workload IR.
• Declaration workflow: compile declarations, IR JSON, and runtime recordings into build artifacts.
• Declaration cookbook: concrete Python and TypeScript declaration patterns for secure Nix-first workloads.
• Sandbox types: general, code, browser, desktop, and builder sandbox patterns.
• Lifecycle matrix: current CLI support, current SDK support, and runtime parity targets.
• Errors & metrics: SDK result, error, metrics, and audit correlation targets.
• SDK reference: language SDK status and parity target.
• Python SDK: current and planned Python surface.
• Node.js SDK: current and planned TypeScript surface.

Tutorials

• Tutorials overview: workflow map.
• Agent sandbox: run generated or third-party code.
• Coding agent: run coding-agent tasks with explicit filesystem, network, and persistence boundaries.
• Code execution: execute commands and scripts.
• File transfer: upload and download files.
• LLM tool integration: tool-loop sandboxing.
• Browser automation: browser sessions in microVMs.
• Desktop automation: sensitive state and credential boundaries.
• Interactive terminal: debug access without making SSH the default path.
• Any language: language-agnostic guest workloads.
• Services and ports: expose explicit ports.
• Long-running services: readiness, ports, logs, lifecycle, and policy.
• Error handling: build, admission, runtime, file, network, and restore failures.
• Cold-mode recovery: pause, save, restore, wake.

Architecture

• Architecture overview: local runtime flow.
• Lifecycle states: running, stopped, paused, cold, restoring, and cleaned sandbox states.
• Core components: CLI, SDKs, builder VM, supervisor, backend, and guest agent.
• Control surfaces: CLI, SDK, console, guest RPC, and not-claimed management surfaces.
• Security and isolation: build, launch, runtime, policy, audit, and SDK boundaries.
• Networking and storage: egress, ports, files, volumes, and snapshots.
• Architecture reference: crates, backends, builder VM, supervisor layers.
• Isolation tiers: full-OS microVM vs the no-OS / no-kernel function-sandbox tier — compatibility, security posture, and latency tradeoff.
• Platform support: host, backend, architecture, and support status matrix.
• Guest agent: guest protocol and readiness.

Security

• Security claim ledger: docs-facing claim status.
• Sandbox parity status: gated parity claims.
• Matryoshka model: isolation tier model.
• Threat model: threat boundaries.
• Verified boot: rootfs integrity posture.

Platform

• Linux execution and macOS are current local targets.
• Native Windows is future work tracked in mvm#428. WSL2 with nested /dev/kvm is the supported Windows-adjacent libkrun workload path.

Claim Rules

• Strong claims need Shipped/Preview/Planned/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.