Skip to main content
Use nullspace template ... when you want to create reusable sandbox 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 sandbox 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 sandbox 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.