Skip to main content

​
Predefined image helpers

Template().from_ubuntu_image("22.04")
Template().from_debian_image()
Template().from_python_image("3.12")
Template().from_node_image("20")
Template().from_bun_image("1.2")
from_bun_image() requires an explicit Bun version and maps to oven/bun:<version>.

​
Existing templates and custom images

Template().from_template("base")
Template().from_image("registry.example.com/team/app:1.0")
Template().from_base_image("ubuntu:22.04")

​
Dockerfile

builder = Template().from_dockerfile("./Dockerfile")
build = Template.build(builder, name="demo-from-dockerfile")

dockerfile = """
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y jq
"""

builder = Template().from_dockerfile_content(dockerfile)
Dockerfile builds use BuildKit. BuildKit-backed builds evaluate the Dockerfile, then import the resulting OCI image into a Nullspace rootfs and snapshot. build_backend="native" remains valid for non-Dockerfile declarative/OCI requests and historical build filters, but Dockerfile input with the native backend is rejected.

​
Compatibility

BuildKit-backed Dockerfile builds use BuildKit for upstream Dockerfile evaluation and then retain the resulting OCI runtime metadata during import.
FeatureBuildKit behavior
Multi-stage builds and COPY --fromHandled by BuildKit.
HeredocsSupported when the configured BuildKit Dockerfile frontend supports them.
RUN --mountBuildKit cache, bind, tmpfs, secret, and SSH mounts require matching Nullspace request support and policy.
Named contextsRequire BuildKit build-context support.
.dockerignore parityUses the uploaded BuildKit context path.
LABELRetained as template/build OCI metadata.
EXPOSERetained as metadata and UI/API hints; it does not automatically publish a port.
VOLUMERetained as metadata only; it does not create persistent Nullspace volumes.
HEALTHCHECKRetained as metadata. Shell/exec healthchecks map to command readiness when safe; unsupported forms remain metadata only.
Docker’s BuildKit and Dockerfile references define the upstream behavior: BuildKit, Dockerfile reference, and build contexts.

​
OCI import

When a custom image or external Dockerfile FROM imports an OCI image, Nullspace imports these runtime defaults:
OCI dataImport behavior
EnvKEY=VALUE entries become runtime env defaults; malformed entries are skipped.
UserTrimmed non-empty values become the default user. Supported Linux forms include names, numeric ids, and user/group combinations.
WorkingDirTrimmed non-empty values become the default workdir.
Entrypoint and CmdArrays are concatenated and shell-escaped into one start command.
LabelsRetained as template/build OCI metadata.
Exposed portsRetained as metadata and hints; they do not publish traffic by themselves.
VolumesRetained as metadata only; no persistent Nullspace volume is created automatically.
HealthcheckRetained as metadata and mapped to command readiness when semantics are safe.
LayersRaw tar, gzip, Docker tar/gzip, nondistributable variants, and zstd OCI layers are supported.
Filesystem entriesRegular files, directories, symlinks, hard links, and OCI whiteouts are applied when paths stay inside the rootfs. Mode bits and uid/gid ownership are preserved in the generated ext4 rootfs.
PlatformLinux manifests are selected for the microVM host architecture. Manifests with os.version or os.features are rejected.
Nullspace does not import stop signal, shell metadata, or arbitrary annotations into runtime config today. Special files such as sockets, FIFOs, block devices, character devices, sparse tar entries, and unknown tar entries are rejected.

​
Private registries

builder = (
    Template()
    .from_image("registry.example.com/team/app:1.0")
    .set_base_image_auth(username="robot", password="token")
)
Helpers also exist for GCP Artifact Registry and AWS ECR.