DockerRootfsBuilder

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.

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

Constructor

ensure

Cache behavior

Context safety

​Constructor

​ensure

​Cache behavior

​Context safety

Constructor

ensure

Cache behavior

Context safety