How smol-machines/smolvm works
1. Overall shape
- This is a Rust workspace that builds a VM-oriented CLI plus a reusable core library.
- The repo also contains a Node.js SDK, a native binding layer, guest/host agent crates, and packaging/registry utilities. It is not just a single binary; it is a multi-surface platform for creating, running, packaging, and embedding microVMs.
2. Primary control plane
- The src/ tree is the main host-side application.
- src/cli/ provides the user-facing commands: machine lifecycle, pack, serve, smolfile, cleanup, and helper utilities.
- src/api/ exposes the same capabilities as structured handlers for machines, images, exec, files, and health, with a supervisor/state layer underneath.
- This suggests a split between a CLI front end and an API-driven control plane built on the same internal services.
3. Machine lifecycle and VM runtime
- src/vm/, src/agent/, src/process.rs, src/storage.rs, src/disk_utils.rs, and src/data/ form the runtime management layer.
- src/vm/backend/libkrun.rs is the key VM backend; the README says the project uses libkrun with Hypervisor.framework on macOS and KVM on Linux.
- Host platform differences are isolated behind src/platform/ and VM backend traits, so the rest of the system can manage machines without knowing the host hypervisor details.
4. Host/guest boundary
- There are two distinct “agent” concepts in the repo:
- src/agent/ appears to be host-side orchestration around launching and managing guests.
- crates/smolvm-agent/ is the guest-side agent, with code for OCI handling, networking, PTY/process handling, SSH agent forwarding, storage, DNS proxying, and vsock communication.
- The boundary between host and guest is likely vsock-based, with the guest agent handling commands and filesystem/network interactions inside the VM.
5. Networking subsystem
- src/network/, src/dns_filter.rs, src/dns_filter_listener.rs, and crates/smolvm-network/ make up the networking story.
- The system supports opt-in guest networking, allow-list style egress control, and TCP/UDP forwarding/relay behavior.
- The architecture appears to separate policy and launch on the host from lower-level packet/frame handling and listener/relay mechanics in reusable crates.
6. Image, registry, and OCI flow
- src/registry.rs and crates/smolvm-registry/ handle OCI registry access, cache, pull, and push behavior.
- crates/smolvm-pack/ is the packaging pipeline that can detect/extract images, assemble assets, and sign outputs.
- The README emphasizes OCI compatibility, so the runtime can pull standard container images and boot them as microVM workloads without a Docker daemon.
7. Portable machine packaging
- smolfile support is split across src/smolfile.rs and crates/smolvm-smolfile/.
- The CLI’s pack flow turns a workload plus its configuration into a portable .smolmachine artifact.
- This packaging path is a separate subsystem from the live VM runtime: it focuses on creating redistributable, self-contained workloads rather than managing a running machine.
8. Configuration and persistent state
- src/config.rs, src/db.rs, src/data/, and the storage/disk modules define machine metadata, persistence, and local state layout.
- The repo supports both ephemeral runs and durable machines whose state survives stop/start cycles.
- Persistent storage is a core boundary: VM disks, machine records, and runtime caches are managed separately from transient execution state.
9. Embedded SDK and language bindings
- crates/smolvm-napi/ exposes Rust functionality through N-API.
- sdks/node/smolvm-embedded/ is the Node.js SDK built on top of that binding, with platform-specific prebuilt packages under sdks/node/smolvm-embedded-*.
- This means the core VM lifecycle can be embedded into another application rather than used only as a CLI, which is an important architectural surface.
10. Guest environment and execution features
- crates/smolvm-protocol/ defines shared protocol types such as guest environment and retry semantics.
- The guest-side agent and host-side execution layers together support exec, file operations, PTY/terminal interaction, SSH agent forwarding, and process management inside the VM.
- These features are exposed through both CLI commands and API handlers, but they depend on the guest agent and VM communication channel.
11. Platform and binary distribution
- src/platform/ plus the vendored lib/ and libkrun* directories show that the project ships host-specific runtime dependencies.
- The README notes macOS signing/entitlements and bundled GPU-related libraries such as MoltenVK and virglrenderer support.
- The build and release scripts, CI workflows, and platform-package scripts exist because native binaries and embedded assets are part of the product architecture, not just build tooling.
12. Examples and validation
- examples/ demonstrates expected runtime patterns: Docker-in-VM, browsers, GPU workloads, Node, Python, local LLMs, and more.
- tests/ contains shell-based end-to-end checks for API, CLI, pack, networking, resizing, scaling, wrapper behavior, and GPU.
- This indicates the architecture is validated at the system boundary: the important contracts are CLI/API behavior, VM startup, networking, storage, and packaging.
Main entry points: vm VM core · cli CLI commands · api API server · smolvm-agent Guest agent
Components 22
Control plane
Host-side CLI, API, embedded runtime, and shared app services.
- CLI entry · Top-level executable that wires the host application together.
src/main.rs - CLI commands · User-facing commands for lifecycle, pack, serve, smolfile, and cleanup.
src/cli - API server · Structured machine, image, exec, file, and health endpoints.
src/api - Embedded runtime · In-process control/runtime entry for embedding smolvm in another app.
src/embedded - Config · Process and machine configuration wiring.
src/config.rs - State DB · Local machine metadata and durable state store.
src/db.rs
VM runtime
Machine lifecycle, VM backend, platform abstraction, and host/guest boundary.
- Storage · Host-side persistent storage management.
src/storage.rs - VM core · Machine state, config, and backend coordination.
src/vm - libkrun backend · Primary VM backend implementation using libkrun.
src/vm/backend/libkrun.rs - Platform layer · Linux and macOS host-specific abstractions and traits.
src/platform - Host agent · Host-side launcher, manager, terminal, and boot coordination.
src/agent - Host networking · Guest networking policy and launch integration on the host.
src/network - DNS filter · Allow-list style DNS filtering and listener integration.
src/dns_filter.rs
Guest agent
Code that runs inside the guest VM and handles execution, networking, and storage.
- Guest agent · Guest-side OCI, process, PTY, SSH agent, storage, vsock, and DNS proxy handling.
crates/smolvm-agent
Packaging & registry
OCI, smolfile, and pack flows for building portable machine artifacts.
- Registry client · OCI registry cache, pull, and push integration.
src/registry.rs - Smolfile · Portable machine specification and pack entrypoint support.
src/smolfile.rs - Pack crate · Detection, extraction, asset assembly, format, and signing.
crates/smolvm-pack - Registry crate · Reusable registry client, cache, pull, and push logic.
crates/smolvm-registry
SDKs
Native binding and Node.js embedding surface.
- Native binding · Rust-to-N-API bridge for embedding the core runtime.
crates/smolvm-napi - Node SDK · Node.js wrapper and platform packages built on the native binding.
sdks/node/smolvm-embedded
Shared crates
Reusable protocol and networking libraries used by host and guest components.
- Protocol crate · Shared guest environment and retry types.
crates/smolvm-protocol - Network crate · Reusable device, frame stream, queues, stack, and TCP relay.
crates/smolvm-network
Connections 29
- CLI entry → CLI commands: dispatches · Main executable routes into CLI command handling.
- CLI entry → API server: serves · Can start the API-driven control plane.
- CLI entry → Embedded runtime: embeds · Supports in-process runtime usage.
- CLI commands → VM core: manages · Lifecycle commands create, start, stop, resize, and clean up machines.
- CLI commands → Registry client: uses · CLI image flows consult registry access.
- CLI commands → Smolfile: packs · Pack and smolfile commands build portable artifacts.
- API server → VM core: controls · API handlers manipulate machine state and execution.
- API server → State DB: stores · API state is backed by local persistence.
- API server → Storage: persists · API operations read and update durable storage.
- Embedded runtime → Native binding: binds · Embedded runtime is exposed through the native binding layer.
- VM core → libkrun backend: runs on · VM core delegates to libkrun backend implementation.
- VM core → Platform layer: abstracts · Host-specific differences are isolated behind platform traits.
- VM core → Host agent: coordinates · Machine lifecycle and guest startup are orchestrated by the host agent.
- VM core → Storage: uses · VM state depends on persistent disks and storage layout.
- VM core → State DB: records · Machine metadata and state transitions are persisted.
- Host agent → Guest agent: launches · Host agent connects to the guest agent over the VM channel.
- Host agent → Protocol crate: speaks · Host and guest share protocol types and retry semantics.
- Host networking → Network crate: builds on · Host networking relies on the reusable network stack crate.
- Host networking → DNS filter: enforces · Network policy applies DNS allow-list filtering.
- Registry client → Registry crate: delegates · Host registry access is implemented by the reusable OCI client crate.
- Smolfile → Protocol crate: formats · Portable machine artifacts share protocol-level types.
- Guest agent → Protocol crate: uses · Guest agent shares protocol definitions with the host.
- Guest agent → Network crate: relays · Guest networking and TCP relay behavior depend on the shared network crate.
- Guest agent → Registry client: pulls · Guest execution can consume OCI images and registry content.
- Pack crate → Registry crate: pulls/pushes · Packaging flow can resolve and publish OCI artifacts.
- Pack crate → Protocol crate: packages · Pack output includes shared machine/runtime metadata.
- Native binding → VM core: exposes · N-API binding surfaces machine lifecycle to host applications.
- Node SDK → Native binding: wraps · Node SDK is built on top of the native binding.
- Node SDK → VM core: embeds · SDK provides a programmatic machine control surface.