Skip to main content
Builds turn a template builder into a reusable template ref. 
from nullspace import Template, default_build_logger

build = Template.build(
    builder,
    name="my-template",
    tags=["stable"],
    cpu_count=4,
    memory_mb=2048,
    disk_mb=16384,
    skip_cache=False,
    on_log_entry=default_build_logger(),
)

print(build.status, build.name)
See the API reference for the full template build request schema, including build_context uploads, SSE log events, and background-build polling. cpu_count, memory_mb, disk_mb, internet_access, build_backend, build_secrets, and skip_cache are available on both Template.build() and Template.build_in_background(). disk_mb sets the minimum rootfs size (MB) baked into the template. The build VM’s rootfs is grown to this size before its snapshot is captured, so every machine created from the template — cold create, warm-pool checkout, fork, or resume — inherits the larger disk. Use it for workloads that need local scratch space (cloning large repos, build artifacts). Omit it to use the default headroom. 
build = Template.build(
    builder,
    name="offline-template",
    internet_access=False,
)

​
Background Builds

build = Template.build_in_background(builder, name="my-template", tags=["next"])
snapshot = build.get_status()
print(snapshot.build.status)

finished = build.wait_until_terminal()
print(finished.build.status)
The TypeScript SDK builds synchronously over the SSE stream; for background builds and polling, use the Python SDK, CLI, or HTTP API.

​
More CLI Examples

nullspace template build --from-python-image 3.12 --name my-template --tag stable --cpu-count 4 --memory-mb 2048
nullspace template build --from-python-image 3.12 --name offline-template --no-internet-access
nullspace template build --from-dockerfile ./Dockerfile --name docker-template
nullspace template build --from-python-image 3.12 --name my-template --tag next --background
nullspace template wait tb_... --poll-interval-ms 500
Dockerfile builds use BuildKit. --backend buildkit is optional for Dockerfile input; --backend native is rejected for Dockerfile builds. For BuildKit Dockerfile builds, internet_access=False maps to BuildKit’s network-disabled mode. Private registry pulls and package installation steps that need outbound access will fail unless their inputs are already available from an accessible cache or local build context.

​
BuildKit Secrets

BuildKit Dockerfile builds can receive request-time secrets for RUN --mount=type=secret instructions through the Python SDK, CLI, or HTTP API. Secret values are written as temporary files on the build worker, passed to buildctl with --secret, and are not stored in build definitions, cache keys, context manifests, logs, or status metadata. CLI dry-run/render/error output redacts request-time secret values. 
builder = (
    Template.from_dockerfile_content(
        "FROM node:20\nRUN --mount=type=secret,id=npm_token npm ci"
    )
    .add_build_secret_env("npm_token", "NPM_TOKEN")
)

Template.build(builder, name="private-npm")
The TypeScript SDK does not expose BuildKit build secrets yet; use the Python SDK, CLI, or HTTP API.
source is a client-side hint (value, env, or file); SDKs and CLIs resolve env/file inputs before submission. Native template builds reject build_secrets. Retries of builds that used secrets must provide fresh values for the same secret IDs, for example nullspace template retry tb_... --build-secret-env npm_token=NPM_TOKEN.