Choosing a template
A template is the recipe your instance boots from: the image and tag, the launch mode, environment variables, ports, an optional on-start script, and the machine constraints the recipe needs. You pick one on the deploy page, right after you pick hardware.
System templates and your own
| Curated (system) | Private | Public | |
|---|---|---|---|
| Who maintains it | Superheat | Your organization | Its owning organization |
| Who can see it | Everyone | Your organization only | Everyone |
| Who can edit it | Nobody — immutable through the API | Its owning organization | Its owning organization |
| Badge on the card | Curated | A lock icon | Public |
Start with a curated template. They are the ones the deploy picker offers by default, and most carry an [Automatic] tag — shown as an Automatic badge — which resolves at launch to an image tag matching the CUDA version of the machine you picked.
Build your own when you need a specific image, your own environment variables, extra ports, or an on-start script. Duplicate on any template copies it into your organization as a private template you can edit — secret values and private registry credentials are not copied across organizations, so you re-enter your own. See Create a template.
The tabs
The Templates page splits the gallery into five tabs.
| Tab | What it lists | Ordering |
|---|---|---|
| Recommended | Curated Superheat templates | The curated order, then name |
| My Templates | Templates your organization owns, private and public | Most recently edited first |
| My Recent | Templates your organization has already deployed from | Most recently launched first |
| Popular | Curated and public templates | Launch count, highest first |
| Serverless | Nothing yet — a placeholder for auto-scaling, pay-per-request endpoints | — |
Below the tabs sit a search box, which matches on name, description and image, and a row of facet chips: SSH, Jupyter, args and VM for launch mode, ARM for architecture, and CUDA floors 11.8, 12.1 and 12.4. Chips toggle; clicking an active chip clears it. The Serverless tab hides them, since there is nothing to filter.
Each card carries the template's name, its image reference, a launch-mode badge, derived badges such as CUDA 12.4, Automatic or ARM, and a launch count. Opening a card shows the full recipe — image, Jupyter settings, environment, ports, arguments, on-start script, machine constraints and readme. Environment values marked secret stay masked unless your organization owns the template.
Getting a template onto the deploy page
The deploy page's picker lists the curated templates, so a private template of your own will not appear there on its own. Launch it from the gallery instead: press Launch on the card or in its detail dialog, pick hardware in the marketplace, and the template travels with you. It is pinned to the front of the picker and preselected, as long as it fits the machine you chose.
How the compatibility check works
Once an offer is chosen, every template in the picker is checked against that machine. Incompatible ones are dimmed and cannot be clicked; hovering one shows the reason. The page preselects the template you launched from the gallery if it passes, otherwise the first template that does.
If nothing in the picker fits the machine, an error panel appears next to the deploy button reading "Template won't run on this machine", with the reason and the advice to pick a compatible template or a different GPU. The deploy button stays disabled until you do.
The checks run in this order, and the first failure is the reason you see.
| Check | Fails when | What you are told |
|---|---|---|
| Availability | The template is flagged coming soon | This template isn't available to launch yet |
| Architecture | The template declares an architecture other than amd64/x86_64 | Needs ARM (arm64) hardware; Superheat hosts are x86_64 |
| Virtualization | Launch mode is vm, or the template requires a VM-capable host, and the offer is not one | This machine is not VM-capable |
| CUDA (too old) | The template's cuda_min is above the machine's Max CUDA | Needs CUDA ≥ 12.4; this machine has 12.1 |
| CUDA (too new) | The template's cuda_max is below the machine's Max CUDA | Pins an older CUDA stack (supports up to 12.4); this machine has 12.8 |
| VRAM | The template's minimum VRAM is above the offer's VRAM per card | Needs ≥ 48 GB VRAM; this machine has 24 GB |
Two details worth knowing:
- The VRAM check is against VRAM per card, not the slice total. A 4× slice of 24 GB cards does not satisfy a 48 GB requirement.
- A template's recommended disk size is a suggestion, not a constraint. It appears among the machine constraints on the template as "N GB disk suggested", the compatibility check ignores it, and the deploy page's disk slider does not adopt it — the slider starts at its own default.
The check is a convenience, not the enforcement point. The API applies the same rule for VM templates and rejects a VM template on a non-VM-capable machine with a 422, whether the request came from the console or from your own code.
The ssh and jupyter launch modes carry one further requirement that is not part of this check: the image has to derive from the Superheat base image, because a stock image has no SSH server and no JupyterLab to start. args and vm run any image. See Launch modes and Base image.
What "coming soon" means
Some templates are published before their execution path exists. They carry a Coming soon badge, and the compatibility check refuses them on every machine, so they can never reach a deploy. On the card the Launch button is disabled with the tooltip "Execution ships in a later release."; in the detail dialog the same button is disabled and reads Coming soon.
The Serverless tab is the same idea at gallery scale: it is a placeholder for a feature still being built and always comes back empty. Nothing about it is filterable or launchable yet.
Coming-soon templates are still readable — open one to inspect its image, environment and ports — and you can duplicate one into your organization. A duplicate keeps the flag, so the copy will not launch either.