Manage Templates

Use nullspace template ... when you want to create reusable machine environments without writing Python builder code. The CLI mirrors the SDK builder: choose one base image, add build steps, set runtime defaults, then publish a named template.

Inspect Templates

nullspace template list
nullspace template list --fields id,canonical_ref,visibility
nullspace template get team/agent-template:stable
nullspace template get team/agent-template:stable --fields id,canonical_ref,visibility
nullspace template exists team/agent-template:stable

--fields returns compact metadata for scripts and dashboards. Build commands take a single-segment --name; use --tag for version tags and template refs such as team/agent-template:stable for lookup and management.

Build From An Image

nullspace template build \
  --from-python-image 3.12 \
  --name fastapi-agent \
  --tag stable \
  --apt-install git,curl,rg \
  --pip-install fastapi,uvicorn \
  --copy-src ./app.py \
  --copy-dst /workspace/app.py \
  --set-workdir /workspace \
  --start-cmd "uvicorn app:app --host 0.0.0.0 --port 8080" \
  --ready-port 8080

Base selectors include:

nullspace template build --from-ubuntu-image 22.04 --name ubuntu-tools
nullspace template build --from-debian-image bookworm --name debian-tools
nullspace template build --from-python-image 3.12 --name python-tools
nullspace template build --from-node-image 20 --name node-tools
nullspace template build --from-bun-image 1.2 --name bun-tools
nullspace template build --from-image registry.example.com/team/app:1.0 --name app
nullspace template build --from-template base --name base-plus-tools

Package install helpers accept comma-separated package lists. Add --npm-global immediately after --npm-install, --bun-global immediately after --bun-install, or --pip-user-install immediately after --pip-install to change install scope.

Dockerfiles And Local Context

nullspace template build \
  --from-dockerfile ./Dockerfile \
  --name dockerfile-template \
  --file-context . \
  --file-ignore node_modules \
  --file-ignore .git

Inline Dockerfile content is also supported:

nullspace template build \
  --from-dockerfile-content @Dockerfile.generated \
  --dockerfile-path-hint Dockerfile \
  --name generated-template

Unsupported Dockerfile instructions are emitted as structured warning log entries. Use render commands to inspect the generated request before building:

nullspace template render json --from-python-image 3.12 --name demo --apt-install git
nullspace template render dockerfile --from-python-image 3.12 --name demo --apt-install git

Build Resources, Cache, And Logs

nullspace template build \
  --from-python-image 3.12 \
  --name python-large \
  --cpu-count 4 \
  --memory-mb 2048 \
  --skip-cache \
  --log-format text

Start a background build when CI should poll later:

nullspace template build --from-python-image 3.12 --name python-next --tag next --background
nullspace template builds python-next
nullspace template build-status tb_123 --offset 0
nullspace template logs tb_123
nullspace template logs tb_123 --offset 10 --follow
nullspace template cancel tb_123 --reason superseded
nullspace template retry tb_123 --tag next
nullspace template promote tb_123 --tag stable
nullspace template wait tb_123 --poll-interval-ms 500 --log-format jsonl

Save next_offset from build-status output and pass it back as --offset to fetch only new build log entries. template logs --follow uses the canonical reconnectable log stream and keeps reading live entries until the build stream closes. template cancel is idempotent for terminal builds and records a durable cancelled log entry. template retry starts a new attempt from the sanitized persisted definition; supply any private base image credentials again through the SDK/API when the original build required them. template promote moves a tag to a retained ready build artifact. Use template validate and template plan to check the server-side request normalization without starting an executor:

nullspace template validate --from-python-image 3.12 --apt-install git
nullspace template plan --from-python-image 3.12 --apt-install git --cpu-count 2 --memory-mb 1024

Files, Repos, And Build Steps

nullspace template build \
  --from-ubuntu-image 22.04 \
  --name tools \
  --git-clone https://github.com/acme/repo.git \
  --git-path /workspace/repo \
  --git-branch main \
  --run-cmd "python3 -m compileall /workspace/repo" \
  --make-dir /workspace/logs \
  --make-dir-mode 0755 \
  --make-symlink-target /workspace/repo/bin/tool \
  --make-symlink-path /usr/local/bin/tool

Use --copy-items @copy.json for many copy operations, or combine --copy-src and --copy-dst for one copy step. --remove, --rename-src, and related flags are available for cleanup and final filesystem shaping.

Names, Tags, Aliases, And Visibility

nullspace template reserve team/agent-template
nullspace template namespace get team
nullspace template rename team/agent-template agent-template-renamed
nullspace template tag assign team/agent-template stable prod
nullspace template tag list team/agent-template
nullspace template tag remove team/agent-template old
nullspace template alias list team/agent-template
nullspace template alias remove team/agent-template old-alias
nullspace template visibility set team/agent-template private
nullspace template delete team/agent-template:old

template rename takes a template ref and a new name, not a full destination ref. Existing aliases are preserved by the API.

Use A Template

nullspace machine create --template team/agent-template:stable

Manage Template Warm Pools

Template warm pools keep ready capacity for a template:

nullspace template warm-pool create team/agent-template:stable \
  --name agent-template-small \
  --min-ready 2 \
  --max-ready 4 \
  --json
nullspace template warm-pool wait twp_agent_template_small --min-ready 2 --json
nullspace machine create --template team/agent-template:stable --warm-pool twp_agent_template_small --warm-pool-mode prefer --json
nullspace template warm-pool drain twp_agent_template_small --json

Use nullspace template warm-pool list, get, scale, enable, disable, reconcile, and delete to operate pools. See Template Warm Pools for checkout modes and troubleshooting.

Python SDK

Python SDK objects

TypeScript SDK

CLI

Platform reference

Inspect Templates

Build From An Image

Dockerfiles And Local Context

Build Resources, Cache, And Logs

Files, Repos, And Build Steps

Names, Tags, Aliases, And Visibility

Use A Template

Manage Template Warm Pools

​Inspect Templates

​Build From An Image

​Dockerfiles And Local Context

​Build Resources, Cache, And Logs

​Files, Repos, And Build Steps

​Names, Tags, Aliases, And Visibility

​Use A Template

​Manage Template Warm Pools

​Related

Inspect Templates

Build From An Image

Dockerfiles And Local Context

Build Resources, Cache, And Logs

Files, Repos, And Build Steps

Names, Tags, Aliases, And Visibility

Use A Template

Manage Template Warm Pools

Related