Skip to main content
Use DockerRootfsBuilder when you want a Dockerfile to be the source of truth for a custom SmolVM image. It builds a raw ext4 root filesystem, caches it by build inputs, and returns a BootImage.
DockerRootfsBuilder does not install SSH or the SmolVM guest agent. Add your own guest control service, or use ImageBuilder when you need vm.run(...) immediately.

​
Constructor

from smolvm import DockerRootfsBuilder

builder = DockerRootfsBuilder(
    name="worker-rootfs",
    dockerfile="""
        FROM alpine:3.20
        RUN apk add --no-cache python3
        COPY init /init
        RUN chmod +x /init
    """,
    context={"init": "#!/bin/sh\nwhile true; do sleep 3600; done\n"},
    rootfs_size_mb=512,
)
​
name
str
required
Cache directory name. Letters, numbers, ., _, and - are allowed.
​
dockerfile
str
required
Dockerfile text. Blank Dockerfiles are rejected.
​
context
dict[str, Path | str | bytes] | None
default:"None"
Files to copy into the temporary Docker build context. Keys must be safe relative paths.
​
rootfs_size_mb
int
default:"512"
Size of the generated raw ext4 root filesystem. Must be greater than 0.
​
cache_dir
Path | None
default:"~/.smolvm/images/"
Cache root for built custom images.
​
fingerprint_inputs
dict[str, Any] | None
default:"None"
Extra JSON-serializable values mixed into the cache key.
​
build_args
dict[str, str] | None
default:"None"
Docker build arguments passed as --build-arg.
​
docker_platform
str | None
default:"None"
Docker target platform override. When omitted, SmolVM selects linux/amd64 or linux/arm64 from the requested architecture.
​
ssh_capable
bool
default:"False"
Whether the image starts SSH and accepts the credentials you pass to SmolVM.

​
ensure

from smolvm import DirectKernelBoot, SmolVM

image = builder.ensure(
    backend="qemu",
    arch="host",
    boot=DirectKernelBoot(root="/dev/vda", init="/init"),
)

with SmolVM.from_image(image, memory_mb=1024) as vm:
    print(vm.vm_id)
​
backend
str
required
Backend to prepare the image for. Public docs focus on "firecracker" and "qemu".
​
arch
Literal["host", "amd64", "arm64", "x86_64", "aarch64"] | str
default:"host"
Guest architecture. Use "host" to match the current machine.
​
boot
DirectKernelBoot | None
default:"None"
Boot profile to render later for the selected backend.
​
boot_args
str | None
default:"None"
Explicit kernel boot arguments. Mutually exclusive with boot.
​
return
BootImage
A BootImage with rootfs_format="raw-ext4", the built rootfs path, the matching SmolVM base kernel, backend, arch, and ssh_capable flag.

​
Cache behavior

The cache key includes the Dockerfile, build context, build args, target architecture, rootfs size, Docker platform, and fingerprint_inputs. It does not include the backend or kernel identity, so Firecracker and QEMU can reuse the same rootfs when the architecture matches.

​
Context safety

DockerRootfsBuilder validates context paths before running Docker:
  • Context keys must be relative paths.
  • .. traversal is rejected.
  • A context entry named Dockerfile is reserved.
  • Missing files passed as Path values raise an error before the build starts.
Last modified on June 6, 2026