> ## 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

> Build reusable machine environments from images, Dockerfiles, and builder steps.

Templates define the base environment for new machines. Use them when setup
should not run on every machine create: language runtimes, package managers,
browser stacks, agent tools, desktop dependencies, or services that should
start automatically.

<Warning>
  Template build and logging are microVM-runtime beta surfaces.
</Warning>

## When To Build A Template

| Need                                    | Template Strategy                                          |
| --------------------------------------- | ---------------------------------------------------------- |
| Faster machine startup                  | Move repeated package installs into a template.            |
| Consistent runtime dependencies         | Pin apt, pip, npm, files, and env defaults in the builder. |
| A service should be ready after create  | Use start commands and readiness checks.                   |
| You already have an image or Dockerfile | Build from an image, Dockerfile, or standard base.         |
| You need traceable versions             | Build with names and tags, then launch by canonical ref.   |

## Quick Example

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Machine, Template, default_build_logger

  builder = (
      Template()
      .from_python_image("3.12")
      .apt_install(["git", "curl"])
      .pip_install(["fastapi", "uvicorn"])
      .set_runtime_envs({"APP_ENV": "demo"})
  )

  build = Template.build(
      builder,
      name="fastapi-agent",
      tags=["stable"],
      on_log_entry=default_build_logger(),
  )

  with Machine.create(template=build.canonical_ref) as machine:
      print(machine.commands.run("python3 --version", shell=True).stdout)
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  import { NullspaceClient } from "@nullspace/sdk";

  const client = new NullspaceClient();

  const template = await client.templates
    .builder()
    .fromPythonImage("3.12")
    .aptInstall(["git", "curl"])
    .pipInstall(["fastapi", "uvicorn"])
    .build({
      name: "fastapi-agent",
      tags: ["stable"],
      onLogEntry: (entry) => console.log(entry.message),
    });

  await using machine = await client.machines.create({
    template: `${template.name}:stable`,
  });
  const result = await machine.commands.run("python3 --version", { shell: true });
  console.log(result.stdout);
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace template build \
    --from-python-image 3.12 \
    --apt-install git,curl \
    --pip-install fastapi,uvicorn \
    --set-runtime-env APP_ENV=demo \
    --name fastapi-agent \
    --tag stable

  nullspace machine create --template fastapi-agent:stable
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # Builds stream structured log events over SSE. The build body is large;
  # see the API reference for the full CreateTemplateRequest schema.
  curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "fastapi-agent",
      "tags": ["stable"],
      "base_image": "python:3.12",
      "steps": [
        {"action": "apt_install", "packages": ["git", "curl"]},
        {"action": "pip_install", "packages": ["fastapi", "uvicorn"]}
      ],
      "runtime_config": {"default_envs": {"APP_ENV": "demo"}}
    }'
  ```
</CodeGroup>

See the [API reference](../api-reference) for the full template build request
schema, streaming log events, and background-build polling.

## Build Model

| Concept                | Meaning                                                                   |
| ---------------------- | ------------------------------------------------------------------------- |
| Builder                | The SDK object or Dockerfile/image source that describes the environment. |
| Build                  | The operation that turns the builder into a reusable template artifact.   |
| Template ref           | The name, tag, or canonical ref used by `Machine.create(template=...)`.   |
| Runtime envs           | Environment defaults present when machines start from the template.       |
| Build envs and secrets | Values available only while the template is built.                        |

## Template Tasks

<CardGroup cols={2}>
  <Card title="Quickstart" href="./quickstart">
    Build and launch your first reusable machine template.
  </Card>

  <Card title="How it works" href="./how-it-works">
    Understand how template builds turn setup steps into machine snapshots.
  </Card>

  <Card title="Base image" href="./base-images">
    Start from standard images, existing templates, custom images, or Dockerfiles.
  </Card>

  <Card title="Defining template" href="./defining">
    Install packages, copy files, clone repos, run commands, and set envs.
  </Card>

  <Card title="Start and ready commands" href="./start-ready">
    Start services automatically and wait for ports, URLs, files, or commands.
  </Card>

  <Card title="Warm pools" href="./warm-pools">
    Keep ready capacity for a template and choose fallback behavior at create time.
  </Card>

  <Card title="Build" href="./build">
    Build, wait, tune resources, and control cache behavior.
  </Card>

  <Card title="Logging" href="./logging">
    Stream build logs, reconnect, and inspect cache events.
  </Card>
</CardGroup>

## Related

* [Machines](../machines/overview)
* [Template warm pools](./warm-pools)
* [Python SDK templates](../guides/python-sdk/templates)
* [CLI template commands](../cli/manage-templates)