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.
Template build and logging are machine-runtime beta surfaces.

​
When To Build A Template

NeedTemplate Strategy
Faster machine startupMove repeated package installs into a template.
Consistent runtime dependenciesPin apt, pip, npm, files, and env defaults in the builder.
A service should be ready after createUse start commands and readiness checks.
You already have an image or DockerfileBuild from an image, Dockerfile, or standard base.
You need traceable versionsBuild with names and tags, then launch by canonical ref.

​
Quick Example

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)

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

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

# 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"}}
  }'
See the API reference for the full template build request schema, streaming log events, and background-build polling.

​
Build Model

ConceptMeaning
BuilderThe SDK object or Dockerfile/image source that describes the environment.
BuildThe operation that turns the builder into a reusable template artifact.
Template refThe name, tag, or canonical ref used by Machine.create(template=...).
Runtime envsEnvironment defaults present when machines start from the template.
Build envs and secretsValues available only while the template is built.

​
Template Tasks

Quickstart

Build and launch your first reusable machine template.

How it works

Understand how template builds turn setup steps into machine snapshots.

Base image

Start from standard images, existing templates, custom images, or Dockerfiles.

Defining template

Install packages, copy files, clone repos, run commands, and set envs.

Start and ready commands

Start services automatically and wait for ports, URLs, files, or commands.

Warm pools

Keep ready capacity for a template and choose fallback behavior at create time.

Build

Build, wait, tune resources, and control cache behavior.

Logging

Stream build logs, reconnect, and inspect cache events.