Base image

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")

// Note: the TypeScript builder does not expose fromBunImage yet.
client.templates.builder().fromUbuntuImage("22.04");
client.templates.builder().fromDebianImage();
client.templates.builder().fromPythonImage("3.12");
client.templates.builder().fromNodeImage("20");

nullspace template build --from-ubuntu-image 22.04 --name demo
nullspace template build --from-debian-image --name demo
nullspace template build --from-python-image 3.12 --name demo
nullspace template build --from-node-image 20 --name demo
nullspace template build --from-bun-image 1.2 --name demo

# Predefined helpers resolve to a base_image OCI ref server-side. Builds stream
# over SSE — see the API reference for the full request schema.
curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "demo", "base_image": "python:3.12"}'

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")

client.templates.builder().fromTemplateRef("base");
client.templates.builder().fromImage("registry.example.com/team/app:1.0");
client.templates.builder().fromImage("ubuntu:22.04");

nullspace template build --from-template base --name demo
nullspace template build --from-image registry.example.com/team/app:1.0 --name demo
nullspace template build --from-base-image ubuntu:22.04 --name demo

# Custom and base images both populate base_image. Builds stream over SSE —
# see the API reference for the full request schema.
curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "demo", "base_image": "registry.example.com/team/app:1.0"}'

Dockerfile

Build from a Dockerfile on disk:

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

nullspace template build --from-dockerfile ./Dockerfile --name demo-from-dockerfile

# The HTTP API takes inline Dockerfile content via the "dockerfile" field
# (the SDK/CLI read the file for you). Builds stream over SSE — see the
# API reference for the full request schema.
curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "demo-from-dockerfile", "dockerfile": "FROM ubuntu:22.04\nRUN apt-get update && apt-get install -y jq"}'

The TypeScript SDK builds Dockerfiles from inline content with fromDockerfileContent(...); it does not read a Dockerfile path for you.

Build from inline Dockerfile content:

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

builder = Template().from_dockerfile_content(dockerfile)

const dockerfile = `FROM ubuntu:22.04
RUN apt-get update && apt-get install -y jq`;

const builder = client.templates.builder().fromDockerfileContent(dockerfile);

# Inline Dockerfile content goes in the "dockerfile" field. Builds stream over
# SSE — see the API reference for the full request schema.
curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "demo", "dockerfile": "FROM ubuntu:22.04\nRUN apt-get update && apt-get install -y jq"}'

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.

Feature	BuildKit behavior
Multi-stage builds and `COPY --from`	Handled by BuildKit.
Heredocs	Supported when the configured BuildKit Dockerfile frontend supports them.
`RUN --mount`	BuildKit cache, bind, tmpfs, secret, and SSH mounts require matching Nullspace request support and policy.
Named contexts	Require BuildKit build-context support.
`.dockerignore` parity	Uses the uploaded BuildKit context path.
`LABEL`	Retained as template/build OCI metadata.
`EXPOSE`	Retained as metadata and UI/API hints; it does not automatically publish a port.
`VOLUME`	Retained as metadata only; it does not create persistent Nullspace volumes.
`HEALTHCHECK`	Retained 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 data	Import behavior
`Env`	`KEY=VALUE` entries become runtime env defaults; malformed entries are skipped.
`User`	Trimmed non-empty values become the default user. Supported Linux forms include names, numeric ids, and user/group combinations.
`WorkingDir`	Trimmed non-empty values become the default workdir.
`Entrypoint` and `Cmd`	Arrays are concatenated and shell-escaped into one start command.
Labels	Retained as template/build OCI metadata.
Exposed ports	Retained as metadata and hints; they do not publish traffic by themselves.
Volumes	Retained as metadata only; no persistent Nullspace volume is created automatically.
Healthcheck	Retained as metadata and mapped to command readiness when semantics are safe.
Layers	Raw tar, gzip, Docker tar/gzip, nondistributable variants, and zstd OCI layers are supported.
Filesystem entries	Regular 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.
Platform	Linux 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")
)

nullspace template build \
  --from-image registry.example.com/team/app:1.0 \
  --registry-username robot \
  --registry-password token \
  --name demo

# base_image_auth carries request-time credentials (kind=basic for
# username/password). Builds stream over SSE — see the API reference.
curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo",
    "base_image": "registry.example.com/team/app:1.0",
    "base_image_auth": {"kind": "basic", "username": "robot", "password": "token"}
  }'

The TypeScript SDK does not expose private registry auth yet; use the Python SDK, CLI, or HTTP API for authenticated base-image pulls.

Helpers also exist for GCP Artifact Registry and AWS ECR.

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Predefined image helpers

Existing templates and custom images

Dockerfile

Compatibility

OCI import

Private registries

​Predefined image helpers

​Existing templates and custom images

​Dockerfile

​Compatibility

​OCI import

​Private registries

​Related

Predefined image helpers

Existing templates and custom images

Dockerfile

Compatibility

OCI import

Private registries

Related