Local CLI Quick Start

Use the smolvm CLI to run Linux workloads in local microVMs. Each workload gets its own guest kernel. No Docker daemon is required.

Install

macOS and Linux

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

The same release is also published as brew install smol-machines/tap/smolvm on macOS, through the apt, yum and pacman repositories at smol-machines.github.io/smolvm, which list the commands for each, and can be built from source with nix profile install github:smol-machines/smolvm/v1.32.3.

The smol CLI drives the same engine and smol cloud from one command line; see the smol CLI Reference for its install line.

On macOS, the supported release path is Apple Silicon with macOS 11 or later. On Linux, the host architecture can be x86_64 or aarch64 and must expose KVM at /dev/kvm.

Windows

  1. Enable Windows Hypervisor Platform (WHP).
  2. Download the windows-x86_64 zip from the latest smolvm release.
  3. Extract the full archive so smolvm.exe, krun.dll, and libkrunfw.dll remain together.
  4. Run smolvm.exe --help from PowerShell.

Native Windows runs x86_64 Linux guests. WSL2 is an alternative on Windows 11 only when nested virtualization and KVM are available.

Shell completion

smolvm completion prints a completion script for bash, zsh, fish, powershell or elvish to stdout and installs nothing. Load it from the shell’s startup file:

echo 'source <(smolvm completion zsh)' >> ~/.zshrc
echo 'eval "$(smolvm completion bash)"' >> ~/.bashrc

Run an ephemeral machine

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

The machine exists only for this command and is cleaned up when the command exits.

  • machine run selects the ephemeral lifecycle
  • --image alpine pulls and boots the Alpine OCI image
  • --net enables networking. Networking is off by default
  • -- separates smolvm flags from the command that runs in the guest

For an interactive shell:

smolvm machine run --net -it --image alpine -- /bin/sh

Create a persistent machine

smolvm machine create --net --image alpine --name dev
smolvm machine start --name dev
smolvm machine exec --name dev -- apk add git
smolvm machine exec --name dev -- git --version
smolvm machine stop --name dev

This machine keeps filesystem changes across exec sessions and stop/start cycles.

  • machine create records the machine and its configuration
  • machine start boots it
  • machine exec runs a command in the existing machine
  • machine stop stops the VM without deleting its disk state

Delete the machine when you no longer need it:

smolvm machine delete --name dev

See Machine Lifecycle and CLI Reference for the selected command reference and Examples for more local workflows.