# smolvm

> Ship and run software with isolation by default — sub-second Linux microVMs from one CLI

- Category: Agents & Automation / Code Sandboxes & Isolation
- Language: Rust
- Licence: Apache-2.0
- Repository: https://github.com/smol-machines/smolvm
- Website: https://smolmachines.com
- Canonical page: https://ai-tldr.dev/tools/smolvm/
- Updated: 2026-08-19

## In short

smolvm is a command-line tool for running custom Linux virtual machines locally with sub-second cold start, elastic memory use and cross-platform support on macOS, Linux and Windows. It sits in the Code Sandboxes & Isolation category of the Agents & Automation tools and is open-source, written in Rust and licensed Apache-2.0.

## Overview

smolvm is a command-line tool for running custom Linux virtual machines locally with sub-second cold start, elastic memory use and cross-platform support on macOS, Linux and Windows. Built in Rust on libkrun, it does two things: it manages microVMs on your machine, and it packs a stateful virtual machine into a single .smolmachine file that can be rehydrated on any supported platform or pushed to an OCI registry like any other artifact.

The isolation boundary is a hypervisor, not a namespace, which is why it shows up as a sandbox for agent-generated and untrusted code. Networking is off by default so a program cannot phone home, and when you do enable it you can restrict egress to an explicit allow-list of hosts. A machine is declared in a Smolfile — a TOML file that is to a whole VM what a Dockerfile is to a container image — covering image, CPU, memory, ports, volumes, mounts, network policy and setup commands. Unknown keys are rejected rather than ignored, so a typo fails at create time instead of silently doing nothing.

Beyond one-shot sandboxing, smolvm can branch a running machine: start it as branchable, then create independent copy-on-write children from its live RAM and disk state, including a whole batch in parallel — useful when many agent attempts should start from the same prepared environment. Machines can also be snapshotted into a reusable image without writing a Dockerfile, or packed into a self-contained executable that boots in under 200 ms with no install step. Local container images are supported directly: feed --image a docker save archive, a piped stream, or an unpacked rootfs directory.

## What it does

- Sub-second cold start microVMs with elastic memory, on macOS, Linux and Windows (via the Windows Hypervisor Platform)
- Hardware isolation for untrusted code: network off by default, and per-host egress allow-lists when it is on
- Smolfile, a TOML declaration of a whole VM — image, cpus, memory, ports, volumes, env, init commands and network/auth/health tables — that rejects unknown keys
- Branch a running machine into copy-on-write children from its live RAM and disk state, sequentially or in parallel batches
- Pack a stopped machine into a portable .smolmachine artifact and push or pull it from any OCI registry
- Pack a workload into a self-contained executable with dependencies pre-baked and no runtime downloads
- Boot from local container images: a docker save / podman save archive, a piped stream, or an unpacked rootfs directory

## Getting started

Install the CLI, then run a command in a throwaway VM to check the setup. On Windows, download the windows-x86_64 release and enable the Windows Hypervisor Platform feature first.

1. Install on macOS or Linux

   A single install script; releases are also downloadable from GitHub.

```bash
curl -sSL https://smolmachines.com/install.sh | bash
```

2. Run something in an ephemeral VM

   The machine is cleaned up when the command exits. Drop --net to keep the VM off the network entirely.

```bash
smolvm machine run --net --image alpine -- sh -c "echo 'Hello world from a microVM' && uname -a"
```

3. Lock down egress for untrusted code

   With --net and one or more --allow-host flags, only the named hosts are reachable; everything else fails.

```bash
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://registry.npmjs.org
```

4. Declare a machine in a Smolfile

   Check the TOML into your repository, then create and start the machine from it.

```text
image = "python:3.12-alpine"
net = true
cpus = 4
memory = 4096
ports = ["8000:8000"]
volumes = ["./src:/app"]
init = ["pip install -r /app/requirements.txt"]

[network]
allow_hosts = ["api.stripe.com", "pypi.org"]
```

5. Create, start and branch it

   A branchable machine can be forked into independent copy-on-write children from its live state — for example eight parallel workers off one prepared environment.

```bash
smolvm machine create --name myvm -s Smolfile
smolvm machine start --name myvm --branchable
smolvm machine branch --from myvm --count 8 --name-prefix worker --parallel 8
```

6. Pack it into a portable artifact

   Stop the machine, pack it into a .smolmachine file, and push it to any OCI registry so others can pull and boot the identical machine.

```bash
smolvm machine stop --name myvm
smolvm pack create --from-vm myvm -o myvm
smolvm pack push --file myvm.smolmachine ghcr.io/you/myvm:v1
```

## When to use it

- Give a coding agent a hardware-isolated place to execute the code it just wrote, with the host filesystem, network and credentials behind a hypervisor boundary
- Fan out many attempts at a task from one prepared environment by branching a running machine instead of rebuilding it each time
- Ship a reproducible development or CI environment as a single file that boots the same way on macOS, Linux and Windows
- Run a workload air-gapped or on a locked-down host by booting from a local container archive with no registry access

## Version history

- 2026-08-19: Simon Willison tested smolvm 1.8.3 as a sandbox for untrusted Python and JavaScript data transformations, reporting cold starts of 0.6–1.5 seconds and warm executions of roughly 50 ms.