Skip to main content
SmolVM can start from ready-made sandbox images instead of building an operating system image on your machine. This makes the first launch faster and keeps common presets consistent across hosts.

​
What SmolVM downloads

Published images are release assets on the SmolVM GitHub repository. They include:
  • A SmolVM-built Linux kernel in the format the selected backend needs
  • A compressed root filesystem for a preset or base operating system
  • SHA-256 checksums that SmolVM verifies before boot
  • A pinned Rust guest-agent binary for custom image builds from installed wheels
The image release tag uses a date-based format such as images-2026.06.24.0. This tag is separate from the Python package version, so SmolVM can publish rebuilt images without pretending the Python API changed.

​
Which presets are published

The public CLI command for claude-code is smolvm claude start.
Each manifest row is keyed by preset, CPU architecture, backend, and guest operating system. If SmolVM does not find a matching row, it uses the slower build or install path for that launch.

​
How a published launch works

1

SmolVM resolves the target image

SmolVM combines the preset, host architecture, backend, and requested guest operating system. For example, a Linux Firecracker launch and a macOS QEMU launch can use different kernel artifacts.
2

SmolVM downloads verified assets

Kernel and rootfs files come from the configured images-YYYY.MM.DD.N release tag. SmolVM verifies each file against the bundled SHA-256 checksum.
3

SmolVM decompresses the rootfs once

Compressed .zst files stay in the cache. SmolVM creates a sibling rootfs.ext4 file and stores a sidecar checksum so it knows when to refresh the decompressed copy.
4

SmolVM injects your access key at launch

Published images do not bake in your SSH key. SmolVM passes your public key at launch so the same image can be shared safely across users.

​
Kernel and rootfs formats

SmolVM builds one kernel source tree into the formats each backend expects: The rootfs is a Linux filesystem image. Published rootfs files are compressed as .ext4.zst and decompressed locally before boot.

​
Guest agent pins

Recent images include /usr/local/bin/smolvm-guest-agent. The agent starts before networking and powers the fast vsock control channel for commands, file transfer, shell streams, and guest sync. When you build images from an installed Python wheel instead of a source checkout, SmolVM downloads the pinned guest-agent binary from the same image release tag and verifies its SHA-256 checksum.
If you set SMOLVM_GUEST_AGENT_BINARY, SmolVM uses that local binary for image builds. The binary must be a static Linux binary for the guest architecture.

​
Cache layout

Published images live under ~/.smolvm/images/. The release URLs use the CalVer image tag, while the local cache directory includes the SmolVM package version.
The .from-sha256 sidecar records which compressed rootfs produced the decompressed rootfs.ext4. If the manifest checksum changes, SmolVM refreshes the decompressed file. Run smolvm prune to remove old cached images:

​
Opt out for image development

Set SMOLVM_USE_PUBLISHED=0 when you want to test a local image build or preset install script:
For everyday use, leave this unset so SmolVM can use the verified fast path.

​
Dashboard UI assets

The dashboard has its own release asset named like smolvm-dashboard-ui-<tag>.tar.gz. The smolvm ui command downloads the newest stable dashboard asset into the local SmolVM data directory when the installed package does not already include a built UI. Use beta dashboard assets only when you want prerelease UI changes:

​
Next steps

Runtime backends

See which backend uses each image format

Control channel

Learn how the guest agent speeds up commands

smolvm prune

Reclaim disk from old caches

smolvm ui

Start the dashboard
Last modified on June 24, 2026