smol-machines/smolvm

smol‑machines / smolvm – Branchable micro‑VMs for AI agents

What it is – smolvm is an open‑source runtime that lets you spin up tiny hardware‑virtualised machines (micro‑VMs) from any OCI container image. It is built on the libkrun VMM and a custom guest kernel (libkrunfw) and runs on macOS (Hypervisor.framework), Linux (KVM) and Windows (Hypervisor Platform). The key selling point for AI developers is that each agent can be isolated in its own VM, with fast <200 ms boot, elastic memory, and the ability to checkpoint, rewind and branch a running VM – useful for reproducible experiments, sandboxing untrusted code, or persisting an agent’s state.

How you use it

• Install via Homebrew, a script, or a Windows zip.
• The CLI (smolvm machine …) creates, starts, executes commands in, and packs VMs. Example: smolvm machine run --net --image alpine -- uname -a.
• Define a VM declaratively in a Smolfile (image, resources, ports, mounts, network policy).
• Embed the runtime in your own code through SDKs for Node/TS, Python, and Rust – a single Machine object lets you create a VM, run commands, and delete it, all without a background daemon.

Key features

Feature	Why it matters for AI/ML workloads
Branchable / checkpointable	Freeze a running agent, copy‑on‑write branches, or rewind to a previous state – ideal for debugging or reproducing a model’s inference path.
Portable .smolmachine artifacts	Pack a VM (including its state) into a single file, push to an OCI registry, or run as a self‑contained executable on another host.
Hardware isolation	Each VM has its own kernel; networking is off by default, and you can whitelist hosts or forward credentials safely.
Fast boot & elastic memory	Boots in <200 ms; memory is allocated on demand via virtio balloon, so many agents can coexist on a laptop.
Embeddable SDKs	Direct API access from Python, Node, or Rust without a separate daemon, making it easy to integrate into agent frameworks or orchestration tools.
Kubernetes RuntimeClass	Run pods as micro‑VMs for cloud‑native AI workloads.
GPU support roadmap	Vulkan via virtio‑gpu and CUDA remoting are documented, though not yet production‑ready.

Typical workflow for an AI agent

1. Create a VM from a Python or CUDA image: smolvm machine create --name agent --image python:3.12-alpine.
2. Start it branchable: smolvm machine start --name agent --branchable.
3. Run inference code inside: smolvm machine exec --name agent -- python infer.py.
4. Checkpoint after a critical step: smolvm machine checkpoint --name agent -o step1.chk.
5. Branch to try alternative prompts without re‑initialising the whole environment.
6. Pack the final state for distribution: smolvm pack create --from-vm agent -o agent.smolmachine.

Safety model – The VM isolates the workload; you explicitly grant host folder mounts, network hosts, or credential forwarding. Untrusted code never touches the host filesystem unless you allow it, reducing supply‑chain risk for third‑party models or tools.

Limitations – No GPU acceleration yet on Windows, and the runtime depends on platform‑specific hypervisors. It is not a container runtime; you need OCI images but no Docker daemon.

Where to learn more – Docs at https://smolmachines.com/docs, the SDK reference, and example projects (Python, Node, Docker‑in‑VM, local‑LLM, headless‑browser, Doom). The source lives in the smol-machines/smol repo; this repo contains the runtime itself.

---

License: Apache‑2.0