# smol-machines/smolvm architecture

> Architecture diagram of the GitHub repository smol-machines/smolvm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smol-machines/smolvm
- Repository: https://github.com/smol-machines/smolvm

## Overview

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: [`src/vm`](https://github.com/smol-machines/smolvm/tree/main/src/vm) (VM core), [`src/cli`](https://github.com/smol-machines/smolvm/tree/main/src/cli) (CLI commands), [`src/api`](https://github.com/smol-machines/smolvm/tree/main/src/api) (API server), [`crates/smolvm-agent`](https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-agent) (Guest agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_control["Control plane"]
  node_src_main(("CLI entry<br/>binary<br/>[main.rs]"))
  node_src_cli["CLI commands"]
  node_src_api["API server<br/>handlers"]
  node_src_embedded["Embedded runtime"]
  node_src_config["Config<br/>settings<br/>[config.rs]"]
  node_src_db[("State DB<br/>persistence<br/>[db.rs]")]
end

subgraph group_grp_vm["VM runtime"]
  node_src_storage[("Storage<br/>[storage.rs]")]
  node_src_vm["VM core<br/>lifecycle"]
  node_src_vm_backend["libkrun backend<br/>[libkrun.rs]"]
  node_src_platform["Platform layer<br/>host-os"]
  node_src_agent_host["Host agent<br/>orchestration"]
  node_src_network["Host networking<br/>policy+launch"]
  node_src_dns_filter["DNS filter<br/>policy<br/>[dns_filter.rs]"]
end

subgraph group_grp_guest["Guest agent"]
  node_crates_agent["Guest agent<br/>guest runtime"]
end

subgraph group_grp_pack["Packaging & registry"]
  node_src_registry["Registry client<br/>oci<br/>[registry.rs]"]
  node_src_smolfile["Smolfile<br/>pack spec<br/>[smolfile.rs]"]
  node_crates_pack["Pack crate<br/>packaging"]
  node_crates_registry["Registry crate<br/>oci client"]
end

subgraph group_grp_sdk["SDKs"]
  node_crates_napi["Native binding<br/>n-api"]
  node_sdks_node["Node SDK<br/>javascript sdk"]
end

subgraph group_grp_libs["Shared crates"]
  node_crates_protocol["Protocol crate"]
  node_crates_network["Network crate<br/>net stack"]
end

node_src_main -->|"dispatches"| node_src_cli
node_src_main -->|"serves"| node_src_api
node_src_main -->|"embeds"| node_src_embedded
node_src_cli -->|"manages"| node_src_vm
node_src_cli -->|"uses"| node_src_registry
node_src_cli -->|"packs"| node_src_smolfile
node_src_api -->|"controls"| node_src_vm
node_src_api -->|"stores"| node_src_db
node_src_api -->|"persists"| node_src_storage
node_src_embedded -->|"binds"| node_crates_napi
node_src_vm -->|"runs on"| node_src_vm_backend
node_src_vm -->|"abstracts"| node_src_platform
node_src_vm -->|"coordinates"| node_src_agent_host
node_src_vm -->|"uses"| node_src_storage
node_src_vm -->|"records"| node_src_db
node_src_agent_host -->|"launches"| node_crates_agent
node_src_agent_host -->|"speaks"| node_crates_protocol
node_src_network -->|"builds on"| node_crates_network
node_src_network -->|"enforces"| node_src_dns_filter
node_src_registry -->|"delegates"| node_crates_registry
node_src_smolfile -->|"formats"| node_crates_protocol
node_crates_agent -->|"uses"| node_crates_protocol
node_crates_agent -->|"relays"| node_crates_network
node_crates_agent -->|"pulls"| node_src_registry
node_crates_pack -->|"pulls/pushes"| node_crates_registry
node_crates_pack -->|"packages"| node_crates_protocol
node_crates_napi -->|"exposes"| node_src_vm
node_sdks_node -->|"wraps"| node_crates_napi
node_sdks_node -->|"embeds"| node_src_vm

click node_src_main "https://github.com/smol-machines/smolvm/blob/main/src/main.rs"
click node_src_cli "https://github.com/smol-machines/smolvm/tree/main/src/cli"
click node_src_api "https://github.com/smol-machines/smolvm/tree/main/src/api"
click node_src_embedded "https://github.com/smol-machines/smolvm/tree/main/src/embedded"
click node_src_config "https://github.com/smol-machines/smolvm/blob/main/src/config.rs"
click node_src_db "https://github.com/smol-machines/smolvm/blob/main/src/db.rs"
click node_src_storage "https://github.com/smol-machines/smolvm/blob/main/src/storage.rs"
click node_src_vm "https://github.com/smol-machines/smolvm/tree/main/src/vm"
click node_src_vm_backend "https://github.com/smol-machines/smolvm/blob/main/src/vm/backend/libkrun.rs"
click node_src_platform "https://github.com/smol-machines/smolvm/tree/main/src/platform"
click node_src_agent_host "https://github.com/smol-machines/smolvm/tree/main/src/agent"
click node_src_network "https://github.com/smol-machines/smolvm/tree/main/src/network"
click node_src_dns_filter "https://github.com/smol-machines/smolvm/blob/main/src/dns_filter.rs"
click node_src_registry "https://github.com/smol-machines/smolvm/blob/main/src/registry.rs"
click node_src_smolfile "https://github.com/smol-machines/smolvm/blob/main/src/smolfile.rs"
click node_crates_pack "https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-pack"
click node_crates_registry "https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-registry"
click node_crates_protocol "https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-protocol"
click node_crates_network "https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-network"
click node_crates_agent "https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-agent"
click node_crates_napi "https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-napi"
click node_sdks_node "https://github.com/smol-machines/smolvm/tree/main/sdks/node/smolvm-embedded"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_main,node_src_cli,node_src_api,node_src_embedded,node_src_config,node_src_db toneBlue
class node_src_storage,node_src_vm,node_src_vm_backend,node_src_platform,node_src_agent_host,node_src_network,node_src_dns_filter toneAmber
class node_crates_agent toneMint
class node_src_registry,node_src_smolfile,node_crates_pack,node_crates_registry toneRose
class node_crates_napi,node_sdks_node toneIndigo
class node_crates_protocol,node_crates_network toneTeal
```

## Components

### Control plane

Host-side CLI, API, embedded runtime, and shared app services.

- [CLI entry](https://github.com/smol-machines/smolvm/blob/main/src/main.rs): binary · Top-level executable that wires the host application together. · `src/main.rs`
- [CLI commands](https://github.com/smol-machines/smolvm/tree/main/src/cli): commands · User-facing commands for lifecycle, pack, serve, smolfile, and cleanup. · `src/cli`
- [API server](https://github.com/smol-machines/smolvm/tree/main/src/api): handlers · Structured machine, image, exec, file, and health endpoints. · `src/api`
- [Embedded runtime](https://github.com/smol-machines/smolvm/tree/main/src/embedded): embed · In-process control/runtime entry for embedding smolvm in another app. · `src/embedded`
- [Config](https://github.com/smol-machines/smolvm/blob/main/src/config.rs): settings · Process and machine configuration wiring. · `src/config.rs`
- [State DB](https://github.com/smol-machines/smolvm/blob/main/src/db.rs): persistence · Local machine metadata and durable state store. · `src/db.rs`

### VM runtime

Machine lifecycle, VM backend, platform abstraction, and host/guest boundary.

- [Storage](https://github.com/smol-machines/smolvm/blob/main/src/storage.rs): storage · Host-side persistent storage management. · `src/storage.rs`
- [VM core](https://github.com/smol-machines/smolvm/tree/main/src/vm): lifecycle · Machine state, config, and backend coordination. · `src/vm`
- [libkrun backend](https://github.com/smol-machines/smolvm/blob/main/src/vm/backend/libkrun.rs): backend · Primary VM backend implementation using libkrun. · `src/vm/backend/libkrun.rs`
- [Platform layer](https://github.com/smol-machines/smolvm/tree/main/src/platform): host-os · Linux and macOS host-specific abstractions and traits. · `src/platform`
- [Host agent](https://github.com/smol-machines/smolvm/tree/main/src/agent): orchestration · Host-side launcher, manager, terminal, and boot coordination. · `src/agent`
- [Host networking](https://github.com/smol-machines/smolvm/tree/main/src/network): policy+launch · Guest networking policy and launch integration on the host. · `src/network`
- [DNS filter](https://github.com/smol-machines/smolvm/blob/main/src/dns_filter.rs): policy · 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](https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-agent): guest runtime · 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](https://github.com/smol-machines/smolvm/blob/main/src/registry.rs): oci · OCI registry cache, pull, and push integration. · `src/registry.rs`
- [Smolfile](https://github.com/smol-machines/smolvm/blob/main/src/smolfile.rs): pack spec · Portable machine specification and pack entrypoint support. · `src/smolfile.rs`
- [Pack crate](https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-pack): packaging · Detection, extraction, asset assembly, format, and signing. · `crates/smolvm-pack`
- [Registry crate](https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-registry): oci client · Reusable registry client, cache, pull, and push logic. · `crates/smolvm-registry`

### SDKs

Native binding and Node.js embedding surface.

- [Native binding](https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-napi): n-api · Rust-to-N-API bridge for embedding the core runtime. · `crates/smolvm-napi`
- [Node SDK](https://github.com/smol-machines/smolvm/tree/main/sdks/node/smolvm-embedded): javascript 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](https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-protocol): protocol · Shared guest environment and retry types. · `crates/smolvm-protocol`
- [Network crate](https://github.com/smol-machines/smolvm/tree/main/crates/smolvm-network): net stack · Reusable device, frame stream, queues, stack, and TCP relay. · `crates/smolvm-network`

## Connections

- 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.
