Skip to main content
Templates capture setup once so future sandboxes start from a prepared environment.

​
Template Builders

SurfaceUse
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

MethodUse
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

MethodUse
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

SurfaceUse
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.
Sandbox create accepts warm_pool, warm_pool_mode, and warm_pool_wait_ms; SandboxInfo.warm_pool_checkout reports hit, fallback, or bypass results.