Create a template

Open Templates → New template. The form is eight sections; only Name and Image are required, and every other field has a working default — Mode starts on Args. This page walks them in order.

Basics

Field	Accepts	Notes
Name	required, up to 80 characters	Unique within your organization, compared case-insensitively. A clash returns TEMPLATE_NAME_TAKEN. Two different organizations may both use the same name.
Description	up to 4,000 characters	The one-liner shown on the card.
Visibility	Private or Public	Private is visible to your organization only. Public makes the recipe world-readable but still editable only by you.

Image

Field	Accepts	Notes
Image	required, up to 500 characters	The repository reference without a tag, for example superheat/base or pytorch/pytorch. A first segment containing a dot or a colon is treated as the registry host.
Tag	up to 200 characters, defaults to [Automatic]	[Automatic] is resolved at launch to the newest Superheat base tag the chosen machine's CUDA supports. Any other value is used verbatim.
Repo	up to 500 characters	Optional. A bare owner/name links to Docker Hub; a full URL is used as-is.
Link	up to 1,000 characters	Optional URL — a model card or a repository — surfaced on the card.

[Automatic] only makes sense for the Superheat base image and images derived from it, because it resolves to a cuda-<minor> tag. Pin a real tag for anything else. See Base image.

Launch

Field	Accepts	Notes
Mode	Args, SSH, Jupyter or VM	Decides what starts inside the container and which ports are published. See Launch modes.
Arguments	up to 8,000 characters, args mode only	Split with shell word rules into the container command.
Jupyter working dir	up to 1,000 characters, jupyter mode only	Defaults to /workspace.
JupyterLab	switch, jupyter mode only	On serves JupyterLab, off serves the classic notebook.
On-start script	up to 65,536 characters	Bash, run once at first start. See On-start scripts.

Choosing SSH or Jupyter shows a reminder that both modes need an image derived from the Superheat base image. A plain upstream image has no sshd and no Jupyter, so it belongs in args mode.

Environment

Each row is a key, a value and a secret switch.

Field	Accepts	Notes
Key	up to 256 characters	Rows with an empty key are dropped on save.
Value	any string, or empty	An empty value is stored as unset and is not injected at launch, which makes it a useful placeholder for a value the renter must supply.
Secret	switch	Masks the value for everyone outside the owning organization.

Read Environment variables before you add anything named JUPYTER_TOKEN or GPU_COUNT — the platform overlay always wins over template and renter values.

Ports

Each row is a container port, a protocol, a label and a public switch.

Field	Accepts	Notes
Container port	1 to 65535	The port inside the container, not the host port. The host port is assigned at launch.
Protocol	tcp, udp, http or https	http and https travel over TCP; the choice records what the port serves.
Label	up to 64 characters	Shown on the template detail. A label of open makes this port the console Open button target.
Public	switch, on by default	Recorded on the port entry.

Details and the reserved labels are in Ports.

Machine constraints

Constraints filter which offers a template can launch on. Leave a field blank for no requirement. The deploy page checks them before you submit and explains any mismatch.

Field	Accepts	Meaning
Minimum CUDA	version string, for example 12.4	The machine's CUDA must be at least this.
Minimum VRAM (MB)	integer, 0 or more	Compared against the offer's VRAM per GPU.
Architecture	string, for example amd64	Superheat hosts are x86_64; anything else makes the template unlaunchable today.
Recommended disk (GB)	integer, 0 or more	Advisory — it does not block a deploy.
Requires a VM-capable host	switch	Restricts the template to offers whose host can run full KVM virtual machines.

Private registry

Fill these in only if your image lives in a private registry. Username accepts up to 256 characters, password or token up to 1,000. The password is stored encrypted and never returned by the API. See Private registries.

Readme

Free-form notes, up to 100,000 characters, shown on the template detail below the recipe. This is where usage instructions belong — not in the description, which is a single line on the card.

Save

Create template posts the form and returns the new template with its id and its freshly minted hash_id. It lands at the top of My Templates.

The same call over the API, with SUPERHEAT_API and SUPERHEAT_KEY set as in the API overview:

curl -X POST "$SUPERHEAT_API/v1/templates" \
  -H "Authorization: Bearer $SUPERHEAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PyTorch 2.4 notebook",
    "description": "JupyterLab on the CUDA 12.4 base",
    "image": "superheat/base",
    "tag": "[Automatic]",
    "launch_mode": "jupyter",
    "jupyter_dir": "/workspace",
    "use_jupyter_lab": true,
    "onstart": "pip install torch torchvision",
    "env": [{"key": "HF_TOKEN", "value": "hf_...", "secret": true}],
    "ports": [{"container_port": 7860, "protocol": "http", "label": "open", "public": true}],
    "constraints": {"cuda_min": "12.4", "min_vram_mb": 16384},
    "visibility": "private"
  }'

Edit and delete

Edit on a template you own opens the same form; the API equivalent is PATCH /v1/templates/{id} and it accepts a partial body. Editing any launch field re-mints the hash_id, so links you shared as a pinned hash stop resolving — see Share and duplicate.

Delete removes the template from the gallery. Instances already deployed from it are unaffected and keep running.

System templates are read-only. To change one, duplicate it first.