> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Python SDK object reference for reusable machine templates and builds.

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`.

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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:

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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.

## Related

* [Templates guide](../../templates/overview)
* [Template warm pools](../../templates/warm-pools)
* [Build logs](../../templates/logging)
* [Tags and versioning](../../templates/tags-versioning)