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. An organization can have at most 50 public templates; publishing one more returns PUBLIC_TEMPLATE_LIMIT_REACHED.

Image

Field	Accepts	Notes
Image	required, up to 500 characters	The repository reference without a tag, for example superheat-cn-registry.cn-shanghai.cr.aliyuncs.com/superheat/base. A first segment containing a dot or a colon is treated as the registry host. The reference you enter is pulled verbatim, so name a registry that mainland hosts can pull from.
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. It only sets the link on the card and has nothing to do with where the image is pulled from. A bare owner/name links to Docker Hub, which is unreachable from mainland hosts, so prefer a full URL; 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 images in the superheat/ namespace, because it resolves to one of the cuda-<minor> tags those images publish; for any other image it pulls latest. Pin a real tag for anything else. See Base image.

Which images ACR carries, and which registries mainland hosts cannot pull from, is covered in Images on Superheat CN.

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: "SSH & Jupyter modes require a Superheat base-derived image (sshd + JupyterLab preinstalled). Plain upstream images should use Args."

On Superheat CN that means the Image must be a reference in the superheat/ namespace on ACR, for example superheat-cn-registry.cn-shanghai.cr.aliyuncs.com/superheat/base. superheat/base without the ACR host fails to deploy; an image in any other repository, even one built on the base image, runs its own entrypoint and belongs in args mode. See Images on Superheat CN.

Environment

Each row is a key, a value and a secret switch. A template takes at most 100 rows.

Field	Accepts	Notes
Key	up to 256 characters	Rows with an empty key are dropped on save.
Value	up to 4,096 characters, 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, GPU_COUNT or SUPERHEAT_ACCESS_TOKEN — the platform overlay always wins over template and renter values.

Ports

Each row is a container port, a protocol, a label, a public switch and an access menu. A template takes at most 32 ports.

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.
Access	Open, Access proxy, App checks token	Whether the port requires the instance access token, and who checks it. Warnings under the list flag a choice that will not work on this image or template.

Details and the reserved labels are in Ports. A port left Open is open to anyone who finds the machine's address — see Requiring the access token.

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-cn-registry.cn-shanghai.cr.aliyuncs.com/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.