Share and duplicate

A template has two identifiers, and they answer different questions.

Identifier	Shape	Changes when	Answers
id	a UUID	never	"which template row is this?"
hash_id	th_ followed by a hex digest	the launch recipe changes	"which exact recipe is this?"

id is the row. hash_id is a content hash of the fields that decide what actually launches, so two templates with identical recipes still get different hashes — the row identity is folded in — while the same row keeps its hash across cosmetic edits.

What the hash covers

In the hash	Not in the hash
image, tag, repo	name, description
launch_mode, args_str, onstart	readme, link
env, ports, constraints	visibility, sort order
jupyter_dir, use_jupyter_lab	the private registry password
registry_user	use_count, timestamps

Rename a template, rewrite its readme, flip it from private to public: the hash stays put. Change a port, an environment entry, the on-start script or the image: the hash is re-minted on the spot.

A re-minted hash breaks links you already shared

The old hash no longer belongs to any template, so a pinned link built from it returns TEMPLATE_NOT_FOUND. After a recipe edit, re-copy the pinned link and re-send it.

Sharing

Share on a template card or detail offers two links.

Link	Shape	Behavior
Referral	/templates?t=<id>	Follows the template. Recipients always see your latest edits.
Pinned	/templates?h=<hash_id>	Names one exact recipe, and stops resolving if you change it.

Both open the template detail in the recipient's gallery, from where they can launch or duplicate it. Neither grants access on its own: the recipient must be able to see the template already. That means a system template, a public template, or a template owned by an organization they belong to. Sending a private template's link to someone outside your organization gets them a 404.

Looking a template up by hash

The pinned link is a wrapper around one endpoint:

curl "$SUPERHEAT_API/v1/templates/by-hash/th_9f2c…" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

It returns the same object as GET /v1/templates/{id}, with the same visibility rules and the same secret masking, and 404 TEMPLATE_NOT_FOUND when the hash matches nothing you can see.

This is the reproducibility tool. Record the hash_id alongside a training run, and the lookup either returns the exact recipe you used or tells you it has since changed — which is more useful than silently handing you a different environment.

Duplicating

Duplicating is how you build on a template you cannot edit: a curated system template, or another organization's public one.

curl -X POST "$SUPERHEAT_API/v1/templates/$TEMPLATE_ID/duplicate" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

The copy is created immediately and:

• belongs to your current organization, with you recorded as its creator
• is always private, whatever the source was
• is named <source name> (copy), or (copy 2), (copy 3) and so on if that name is taken
• carries a new id and a new hash_id, and starts at zero launches
• copies the image, launch mode, arguments, on-start script, ports and constraints unchanged

Two things are deliberately not copied when the source is not yours:

Not copied	Why
Secret environment values	You never had read access to them; the copy's values arrive blank with the secret flag intact.
Private registry username and password	Same reason. Re-enter your own credentials on the copy.

Duplicating a template your organization already owns keeps both, because nothing new is being revealed.

The usual workflow

1. Find a curated template that is close to what you want.
2. Duplicate it.
3. Edit the copy — change the image tag, add ports, write an on-start script.
4. Launch it, confirm it works, then share the pinned link with your team.
5. When you change the recipe, re-share the link.

Deleting a template does not affect instances already deployed from it, and does not invalidate anything except the gallery entry and its links.