Templates

Templates capture setup once so future machines start from a prepared environment.

Template Builders

Surface	Use
`Template.from_python_image(...)`	Start from a Python base image and add packages, files, env defaults, user, workdir, and start-ready checks.
`Template.from_dockerfile(...)`	Build from Dockerfile content or a Dockerfile path.
`Template.from_image(...)`	Build from an existing base image, including private registry auth.

Builds

Method	Use
`Template.build(builder, name, ...)`	Build a template and wait for completion.
`Template.build_in_background(builder, name, ...)`	Start a build and reconnect later.
`Template.inspect_build_context(builder, ...)`	Inspect the local build context, warnings, unsupported entries, and request payload without starting a build.
`Template.list_builds(ref, ...)`	List build history, including failed and untagged attempts.
`Template.validate(builder, ...)`	Validate a build request without starting an executor.
`Template.plan(builder, ...)`	Return the normalized build plan without starting an executor.
`TemplateBuild.connect(id)`	Reconnect to a build by ID.
`build.get_status(offset=...)`	Poll status and incremental logs.
`build.logs(offset=..., follow=True)`	Replay durable build logs and optionally follow live entries.
`build.cancel(reason=...)`	Cancel a queued or running build and record a durable cancelled entry.
`build.retry(tags=...)`	Start a new attempt from the sanitized persisted build definition.
`build.promote(tag=...)`	Move a tag to this retained ready build artifact.
`build.wait_until_terminal(...)`	Wait for success or failure, optionally streaming logs.

Build handles and history rows expose cache and artifact fields when the API has them: cache_summary, artifact_availability, promotability, and retention_expires_at.

from nullspace import Template, default_build_logger

builder = Template.from_dockerfile_content(
    "FROM python:3.12-slim\nRUN pip install pytest"
)
build = Template.build(
    builder,
    name="pytest-template",
    tags=["stable"],
    on_log_entry=default_build_logger(),
)
print(build.status)

Dockerfile builds use BuildKit. build_backend="native" remains valid for non-Dockerfile declarative/OCI inputs and historical build filters, but is rejected for Dockerfile input. BuildKit secrets can be attached fluently or passed at request time:

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

Retry does not persist secret values from the original request. Supply private base image credentials and BuildKit secrets again when the original build required them, for example build.retry(build_secrets=[...]).

Refs And Versioning

Method	Use
`Template.get(ref)` / `Template.list(...)`	Inspect templates with optional fields.
`Template.assign_tags(ref, tags)` / `Template.remove_tag(ref, tag)`	Manage version tags.
`Template.list_aliases(ref)` / `Template.remove_alias(ref, alias)`	Manage aliases.
`Template.reserve_name(...)` / `Template.rename(...)`	Manage names and namespaces.
`Template.set_visibility(ref, visibility)`	Set private/public visibility where supported.
`Template.delete(ref)`	Delete a template ref.

Template Warm Pools

Surface	Use
`TemplateWarmPool.create(template, name=..., min_ready=..., max_ready=...)`	Create tenant-owned ready capacity for a template.
`TemplateWarmPool.get(id)` / `TemplateWarmPool.list(...)`	Inspect pools and status counts.
`pool.wait_until_ready(min_ready=...)`	Wait for ready inventory before a burst.
`pool.update(...)` / `pool.enable()` / `pool.disable()` / `pool.drain()` / `pool.delete()`	Operate pool lifecycle and scale targets.
`Template.create_warm_pool(...)`	Convenience helper from a template object.

Machine create accepts warm_pool, warm_pool_mode, and warm_pool_wait_ms; MachineInfo.warm_pool_checkout reports hit, fallback, or bypass results.

Python SDK

Python SDK objects

TypeScript SDK

CLI

Platform reference

Template Builders

Builds

Refs And Versioning

Template Warm Pools

​Template Builders

​Builds

​Refs And Versioning

​Template Warm Pools

​Related

Template Builders

Builds

Refs And Versioning

Template Warm Pools

Related