smolvm image command group is a Docker-style toolbelt for the images that sandboxes boot from. Use it to:
- Pre-download an image so the first
smolvm sandbox createfinishes instantly (CI warm-up, air-gapped setup, flaky network). - Keep the cache tidy — see what is on disk, inspect a single entry, remove a specific image, or drop stale caches left behind by older releases.
- Move images between machines — pack an image into a single archive on one host and unpack it on another.
- Build your own custom rootfs from a Dockerfile without writing Python.
~/.smolvm/images/. Everything in this group operates on that directory.
Synopsis
--image-dir PATH— override the cache location for this invocation.--json— emit a machine-readable envelope instead of the formatted output.
Where images live
Resolution order for the cache directory (first match wins):--image-dir PATHon the command you are running.- The
SMOLVM_IMAGE_DIRenvironment variable. - The default:
~/.smolvm/images/.
Sandboxes read only
SMOLVM_IMAGE_DIR — the --image-dir flag is a per-command override for smolvm image ... itself. If you pull to a non-default directory and want smolvm sandbox create to boot from that same directory, export SMOLVM_IMAGE_DIR before starting the sandbox:Subcommands
pull
Download a published image (kernel + rootfs, verified and decompressed) ahead of time.string
Preset to fetch (for example
codex, claude-code, openclaw). Required unless --all is set. claude is accepted as an alias for claude-code.flag
Download every image published for this machine’s architecture and VMM. Failures for individual images are isolated so one bad download doesn’t cancel the batch. Combine with
--os to limit to a single operating system."amd64" | "arm64"
Processor architecture. Defaults to this machine’s.
"firecracker" | "qemu" | "libkrun"
Virtual machine engine the image targets. Defaults to what this host uses.
"ubuntu" | "alpine"
Operating system inside the image. For a single pull the default is
ubuntu; with --all, this limits the batch to one OS.path
Cache location for this pull. Overrides
SMOLVM_IMAGE_DIR and the default.flag
Emit a JSON envelope with the resolved target, output path, and cache-hit flag.
list / ls / images
Show every entry in the cache with preset, platform, version-staleness, size, and age.smolvm images and smolvm image ls are aliases of smolvm image list — same output, same JSON envelope.
inspect
Print a Docker-style JSON array describing one image: parsed fields, per-file sizes (both apparent and on-disk), the rootfs sidecar, and — for current-version published entries — the manifest URLs, SHAs, and release tag.string
required
Preset name (matches every entry for that preset), full cache directory name (as shown by
image list), or a custom image’s custom/<name> handle. Absolute paths that image list prints are also accepted.rm
Remove a downloaded image to free space. Deletion is confined to direct children of the resolved image directory — symlinks are unlinked in place and never followed.string
required
Preset name, full cache directory name, or
custom/<name>[/<fingerprint>] handle. Fingerprints accept Docker-style unique prefixes.flag
List what would be removed without deleting.
build
Build a custom rootfs from a Dockerfile, exposing the same pipeline asDockerRootfsBuilder as a CLI. Requires Docker on the host. The built image lands in the cache as custom/<name>/<fingerprint> and shows up in image list alongside published images.
path
default:"."
Docker build context. Defaults to the current directory. A missing context is a clean error.
string
required
Name for the built image. Written under
custom/<name>/... in the cache.path
Path to the Dockerfile. Defaults to
Dockerfile in the context.integer
default:"512"
Virtual disk size of the built rootfs, in MiB.
KEY=VALUE
Value forwarded to the Dockerfile’s
ARG lines. Repeat for multiple args."amd64" | "arm64"
Target processor architecture. Defaults to this machine’s.
"auto" | "firecracker" | "qemu" | "libkrun"
default:"auto"
Boot backend the resulting image will target.
string
default:"/init"
First program the guest starts.
Because the CLI cannot boot local Linux images directly yet, a successful
image build prints a ready-to-run SmolVM.from_image(...) snippet you can drop into Python.save / load
Move an image between hosts without going through the network.save packs a cached entry into a tar archive; load unpacks the archive back into a target cache. Useful for air-gapped installs, on-call laptops, or copying a custom/<name> build to a peer’s machine.
manifest.json describing every member. Load stages into a hidden .partial directory and renames atomically; malicious archives (traversal, absolute paths, undeclared members, unsupported schema versions) are rejected before anything reaches the cache. Use --force on load to replace an existing entry.
prune
Remove image caches left behind by older SmolVM releases. This is the canonical home for prune;smolvm prune at the top level is kept as an alias with the same implementation and flags. See smolvm prune for the full reference and dry-run examples.
Choosing SMOLVM_IMAGE_DIR vs. --image-dir
- Set
SMOLVM_IMAGE_DIRwhen the whole host — including sandboxes started later — should read and write from a shared directory (a large data volume, a shared NFS mount for a fleet, or a per-user override on a multi-tenant box). This is the only variable sandboxes themselves consult. - Pass
--image-dirwhen you only want the currentsmolvm image ...command to touch a specific directory (inspecting a peer’s cache, saving from a scratch location, loading into a test directory) without changing what future sandboxes see.
pull into a directory that isn’t reachable via SMOLVM_IMAGE_DIR, the command warns you — the sandbox that boots afterward will fall back to the default location.
Exit codes
Related
smolvm prune— top-level alias ofsmolvm image prune.ImageBuilderandDockerRootfsBuilder— the Python builders behindsmolvm image build.ImageManager— the loader sandboxes use to resolve entries in the cache.