Templates

A template binds a name to a digest-pinned image, per tenant: build and register once, create sessions by name forever after.

barista template build cc --repo ghcr.io/you/tpls --context .   # once
barista create agent1 --template cc -- sleep 3600               # every time

Why they exist

Sessions require a digest-pinned image — a sha256:… that names one exact artifact. Resolving that by hand is error-prone in a specific way: most tags are multi-arch, and tools happily hand you the index digest (the digest of the whole architecture family) when the node needs a platform manifest digest. template build resolves the platform digest explicitly and refuses ambiguity, listing the per-platform digests when the one you asked for doesn't exist.

Semantics worth knowing

• Resolution is server-side, at create. The gateway turns the template name into its pinned image+digest before admission; the stored session spec is indistinguishable from an explicit --image/--digest create. Nodes never see the concept.
• Re-registering replaces. Rebuild under the same name and future creates get the new digest. Running sessions keep the digest their spec captured — rebuilds can't change a live workload.
• Deleting a template never touches its sessions, for the same reason.
• Every create surface takes them: CLI (--template), REST and the Python SDK (template=), and MCP session_create ("template": "<name>"). The console lists and deletes them under Templates.

Registry reality

The node pulls the image, so the reference must be reachable from the node's network: public repos work with zero configuration; private ones work once the operator places registry credentials on the node (a standard Docker config.json — one step per node, fleet-wide). When the fleet declares which registries it can reach, template registration checks your image against that list and refuses early — naming the allowed registries — instead of leaving you with a create that never becomes ready.

Full walkthrough: tutorial 7.