Templates
An offer decides which hardware you get. A template decides what runs on it. You need both to deploy: you pick the offer in the marketplace, and the deploy page carries it forward while you pick the template.
A template is a launch recipe
A template is a saved answer to "what should this machine boot into". It carries:
| Part | What it decides |
|---|---|
| Image and tag | The container image to pull, optionally from a private registry. |
| Launch mode | How the container is started, and which ports come with it. |
| Ports | Which container ports are published, each with a label. |
| Environment | Variables handed to the container. Values can be marked secret. |
| On-start script | Commands run inside the container the first time it starts. A later start does not re-run them. |
| Constraints | Minimum CUDA version, minimum VRAM, and other hardware floors the deploy page checks before letting you launch. |
A template never names a machine. Its constraints are floors — a minimum CUDA version, a minimum VRAM — rather than a pinned host, so the same template deploys onto a 1× RTX 4090 or an 8× H100 PCIe without editing, as long as both clear those floors. That is what makes it worth saving one instead of re-entering the same settings every time.
Launch modes
The launch mode is the one field that changes the shape of the instance rather than its contents.
| Mode | What you get |
|---|---|
ssh | An SSH server. Port 22 is added for you. |
jupyter | JupyterLab plus an SSH shell. Ports 22 and 8080 are added for you. |
args | The image's own entrypoint, run with the arguments you supply. Headless. |
vm | A full KVM virtual machine. Deployable only onto a VM-capable offer. |
ssh and jupyter need an image derived from the Superheat base image, because those modes rely on the base image's entrypoint to bring up the SSH daemon and JupyterLab. args and vm run any image. See Launch modes.
Whatever your template sets, the platform overlays its own environment on top and that overlay wins. You cannot override the JupyterLab token or the GPU count from a template. Environment variables covers what the platform controls.
Visibility
Every template has one of three visibility levels.
| Visibility | Who can see it | Who can edit it |
|---|---|---|
system | Everyone. These are the curated starting points Superheat maintains. | Nobody. System templates are immutable through the API. |
private | Only the organization that owns it. This is the default for anything you create. | That organization. |
public | Everyone. The recipe is readable by any account. | The organization that owns it. |
Secret environment values are masked for anyone outside the owning organization, so publishing a template shares the recipe without leaking the credentials baked into it.
You cannot edit a system or public template you do not own, but you can duplicate any template you can see. The copy lands in your organization as private and is yours to change. Duplicating someone else's template blanks its secret values and private registry credentials — you supply your own.
Why a template has two identities
A template has a stable id and a hash_id. The hash_id is a content hash of the launch-relevant fields — image, tag, repository, mode, arguments, on-start script, environment, ports, constraints, the Jupyter directory and JupyterLab toggle, and the private-registry username — prefixed th_.
It is re-minted whenever any of those change, and stays put when the owner edits the name, description, readme, visibility or sort order. The launch recipe has its own identity, separate from the row that holds it.
That split gives you two ways to point at a template:
| You share | Behavior |
|---|---|
| The id | Follows the template. If the owner changes what it launches, your link launches the new version. |
The hash_id | Identifies one exact recipe. If the owner changes what it launches, the old hash stops resolving. |
The second is the one to use when someone needs to reproduce your run. A stale hash link fails loudly instead of quietly launching something that is no longer what you tested. The API resolves it at GET /v1/templates/by-hash/{hash_id}.