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

# How it works

> Understand template builders, builds, snapshots, and machine startup.

A template is a reusable machine environment. You define a builder, run a build,
and then create machines from the resulting template ref.

## Build Flow

1. Select a base image, existing template, or Dockerfile.
2. Add setup steps such as package installs, file copies, repository clones, and
   build commands.
3. Configure runtime defaults such as environment variables, user, workdir, start
   command, and readiness probe.
4. Build the template. Nullspace prepares the environment and stores a snapshot.
5. Create machines with `Machine.create(template="name:tag")`.

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  builder = (
      Template()
      .from_node_image("24")
      .npm_install(["typescript"], g=True)
      .set_runtime_envs({"NODE_ENV": "production"})
  )

  build = Template.build(builder, name="node-agent", tags=["stable"])
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  const template = await client.templates
    .builder()
    .fromNodeImage("24")
    .npmInstall(["typescript"], { global: true })
    .build({ name: "node-agent", tags: ["stable"] });
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace template build \
    --from-node-image 24 \
    --npm-install typescript --npm-global \
    --set-runtime-env NODE_ENV=production \
    --name node-agent \
    --tag stable
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # Builds stream over SSE; see the API reference for the full request schema.
  curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "node-agent",
      "tags": ["stable"],
      "base_image": "node:24",
      "steps": [{"action": "npm_install", "packages": ["typescript"], "g": true}],
      "runtime_config": {"default_envs": {"NODE_ENV": "production"}}
    }'
  ```
</CodeGroup>

See the [API reference](../api-reference) for the full template build request
schema.

Build envs only apply while the template is being built. Runtime envs are
persisted into machines launched from the template.

## Template Refs

Template refs can be names, tags, aliases, canonical refs, or IDs depending on
the operation. For launch paths, prefer stable refs such as `my-template:stable`.

## Related

* [Base image](./base-images)
* [Build](./build)
* [Names](./names)