CLI tool
smol-machines/smolvm avatar
smol-machines/smolvm

smolvm: kernel isolation per agent workload, plus live branches and packs

An embeddable, portable, branchable virtual machine to safely run Agents locally.

7,107 stars367 forksRustApache-2.0

At a glance

What is it?
smolvm is a Rust runtime that puts each agent workload in its own microVM through libkrun, with branch, checkpoint and pack treated as core commands. The trade is a real guest kernel per workload for a library you link into your own process, with no daemon to install.
Who is it for?
smolvm fits an engineer who needs a real kernel boundary per agent workload and wants that boundary as a library inside their own process. Skip it if your workloads are trusted and raw boot speed is the priority.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Rust, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • smol-machines/smolvm7,107 ★ · +806
Star history
Repository2026-09-232026-11-15
smol-machines/smolvm6.3k7.1k

806 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Four vCPUs and 8 GiB per machine, elastic through a virtio balloon

Every machine starts from the same pair of numbers: 4 vCPUs and 8 GiB of RAM. Memory is elastic, so the host only commits what the guest uses, and a set of declared 8 GiB machines need not each hold 8 GiB on the host. Two other numbers are worth reading as claims rather than as guarantees you inherit: local machines boot in under a second, and a packed machine runs as an executable that boots in under 200 ms. Machines do persist across restarts, and any OCI image boots, including one you built locally and piped in without touching a registry.

libkrun is linked into your process, so there is no daemon to install

The README says the SDKs run in your process with no daemon. libkrun is the VMM, libkrunfw supplies the guest kernel, and the host layer is Hypervisor.framework on macOS, KVM on Linux, or the Windows Hypervisor Platform on Windows. Both of those directories sit in the repository tree beside lib/, src/ and crates/, with a .gitmodules file at the root, so the VMM and the guest kernel are pinned next to the runtime rather than fetched at boot. Because there is no daemon, the SDKs run inside your own process and drive machines through one Machine API, locally or on smol cloud:

bash
npm install smolmachines     # Node / TypeScript
pip install smolmachines     # Python
cargo add smolmachines       # Rust

The cost of that choice is that there is no single control plane to point at. Each host carries its own machines, which is why the project's answer to moving one is to pack it into a file.

Networking starts off, and the older allow flag still grants subdomains

Networking is off unless you pass --net, and even then the allow list is a grant you enumerate by hand. Two flags look interchangeable and are not:

bash
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -qO- https://google.com   # blocked
smolvm machine run --net --image alpine --allow-host-pattern registry.npmjs.org -- wget -qO- https://registry.npmjs.org   # exact host only

The README states that --allow-host example.com allows both the apex and its subdomains, while a pattern of '*.example.com' allows subdomains only, so the flag you copy from an older note can hand a workload more hosts than you meant to give it. smolvm machine update adds entries with --allow-host, --allow-host-pattern and --allow-cidr and removes them with --remove-allow-host and --remove-allow-cidr, also on a running machine started with an allow list. The same paragraph that documents the flags states the limit of the whole model: safety is a shared responsibility, and every folder you mount, port you open, host you allow, and secret or SSH agent you forwarded becomes something the workload can use.

A credential the workload can use without ever reading it

Credential substitution is the feature aimed most directly at agent workloads. The README's example keeps the real value on the host side as an environment variable, names it on the command line with --credential, and binds it to a host:

bash
NOTION_API_KEY=secret_… smolvm machine run --net --image alpine \
  --credential [email protected] -- sh -c 'echo $NOTION_API_KEY'

The stated property is that code can use a credential without ever reading it. The binding carries three parts: the name the workload sees, the host variable the value comes from, and the host the value is scoped to, here api.notion.com. The README marks the echo's output as a placeholder: the workload sees a stand-in, not the real value. The boundary is stated as plainly as the feature: mounts, ports, allowed hosts and forwarded agents all become reachable by the workload, so an untrusted workload gets only what it needs. The two documents that carry the detail are docs/credential-substitution.md and docs/security-model.md, and neither is reproduced in the README itself.

Checkpoints capture RAM, CPU state and disks, and stop at the architecture

Branching is what most people come for. A machine started with --branchable can be checkpointed, and smolvm machine branch --from agent --name try-1 makes a live copy-on-write child that keeps running from the same point. A checkpoint captures RAM, CPU state and disks, so processes inside the machine survive it, and smolvm machine create --name agent2 --from agent.checkpoint resumes from that file later or elsewhere. Rewinding goes through --from with --at '~N' against a generation, and machine checkpoint-log is where the generations are listed. Pause and resume is a separate path for stopping a machine without losing execution. The portability claim has a hard edge: a checkpoint taken on an arm64 Mac resumes on arm64 Linux, and docs/mac-to-linux.md is the named route. The documented case is the same architecture on a different machine.

One .smolmachine file, and no stated way to check what is inside

Portable means a machine collapses into a single file, built either from a running VM or from an image:

bash
smolvm machine stop --name dev && smolvm pack create --from-vm dev -o dev
smolvm pack push --file dev.smolmachine ghcr.io/you/dev:v1
smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version

The result runs as a self contained executable that the README says boots in under 200 ms with nothing to install, and it pushes to any OCI registry. Checkpoints travel the same way and restore on another host or on smol cloud. Before you build distribution on top of this, treat pushing packs to a registry as a supply chain decision you own. A packed executable still needs a hypervisor underneath, which is why the Windows install notes single out the Windows Hypervisor Platform as a requirement.

Where smolvm sits against containers, Firecracker, QEMU and Kata

The README positions smolvm around a per-workload boundary: each workload gets a hardware-isolated VM with its own kernel, booting in under a second locally and in under 200 ms as a packed executable, with no Docker daemon involved.

Nineteen crates move in lockstep, and the GPU path is undocumented

The Cargo workspace has eighteen members and pins its internal crate dependencies to the same version as the root package, 1.34.0, so a bump moves checkpoints, network, credentials, protocol, pack and registry together. Alongside them sit smolvm-agent, smolvm-s3fs, smolvm-oci-layer, smolvm-shim and smolvm-smolfile, which is where a Smolfile holding image, resources, ports, mounts and network policy gets parsed. Dependencies are ordinary Rust plumbing: thiserror, clap 4 with derive, env and string, and serde. The uneven part is the GPU story. The workspace contains smolvm-cuda, smolvm-cuda-guest, smolvm-cuda-shim, smolvm-cuda-codegen, smolvm-cudart-shim and smolvm-nvml-shim, and the examples directory holds demo/dpo_train.py and demo/qlora_train.py, along with demo/H100_SETUP.md, so check those files for how a GPU reaches a guest. Version numbers moved quickly: v1.32.3, v1.32.4 and v1.33.0 were published on 2026-10-26, 2026-10-28 and 2026-11-01, and the last push landed on 2026-11-02. That cadence suits a lockstep workspace, though it makes every bump a coordinated event across all eighteen members rather than an independent crate release.

Editorial conclusion

smolvm fits an engineer who needs a real kernel boundary per agent workload and wants that boundary as a library inside their own process. Skip it if your workloads are trusted and raw boot speed is the priority. Verify three things first: that your host offers Hypervisor.framework, KVM or the Windows Hypervisor Platform, that smolvm --help matches the subcommands you assumed existed, and whether anything verifies a .smolmachine pack you plan to redistribute.

Frequently asked questions

What is smolvm and how does it isolate an agent workload?

It is an embeddable runtime that gives each workload a hardware isolated VM with its own guest kernel, using libkrun as the VMM and libkrunfw as the guest kernel. The host layer is Hypervisor.framework on macOS, KVM on Linux, or the Windows Hypervisor Platform on Windows, and images come from OCI registries with no Docker daemon involved.

How do I install the smolvm CLI?

On macOS you can use Homebrew with brew install smol-machines/tap/smolvm, or the installer script for macOS and Linux. On Windows you unzip the windows-x86_64 release and run smolvm.exe, which needs the Windows Hypervisor Platform. The repository is written in Rust and licensed Apache-2.0.

How do I let an smolvm machine reach exactly one host?

Start the machine with --net and add --allow-host-pattern for an exact host. The --allow-host form allows both the apex domain and its subdomains, and a pattern of '*.example.com' allows subdomains only. The list is changed with smolvm machine update, also on a running machine started with an allow list; it takes --allow-cidr, --remove-allow-host and --remove-allow-cidr too.

Can a workload use a credential without reading its value?

Yes, through credential substitution: the value stays in a host environment variable and you bind it with --credential name=HOST_VAR@host, as in [email protected]. The README states that code can use a credential without ever reading it, and points at docs/credential-substitution.md for the detail.

Can an smolvm checkpoint move from my Mac to a Linux server?

A checkpoint taken on an arm64 Mac resumes on arm64 Linux, and the README links docs/mac-to-linux.md for that move. The same architecture on a different machine is the documented case.

What CPU and memory defaults does smolvm give a new machine?

4 vCPUs and 8 GiB of RAM. Memory is elastic, so the host only commits what the guest uses.

Official sources

  1. License: Apache-2.0
  2. Project website
  3. README
  4. Releases
  5. smol-machines/smolvm on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/smol-machines-smolvm.svg)](https://hysenlabs.com/projects/smol-machines-smolvm)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/smol-machines-smolvm.svg)](https://hysenlabs.com/projects/smol-machines-smolvm)

Was this useful?