Templates

A template is a reusable image with your packages, files, and default CPU/RAM/disk baked in. Every sandbox boots from a template; the create call defaults to pt-base, a minimal template. Sandboxes boot fresh copies — the template itself never changes.

Builds run in the background: building → ready or failed. You can also manage templates in the dashboard.

While a build is building, build_phase says where it is. queued means it waits for a free build slot: each build host runs a fixed number of builds at once, and Platinum starts a queued build on the first host in its region that frees a slot. Once it starts, build_phase follows the build's progress.

Build from an image

This turns an existing Docker image into a named template.

import { Platinum, Template } from "@platinum-dev/sdk";

const client = new Platinum({ url: process.env.PT_API_URL!, token: process.env.PT_TOKEN! });
const tpl = await Template.fromImage("python:3.13-slim")
  .build(client, { name: "py3-data", default_ram_mb: 1024 });

import os
from platinum import Platinum, Template

client = Platinum(token=os.environ["PT_TOKEN"], api_url=os.environ["PT_API_URL"])
tpl = Template.from_image("python:3.13-slim").build(client, "py3-data", default_ram_mb=1024)

pt template build py3-data --image python:3.13-slim --cpu 2 --ram 1024 --wait

curl -X POST "$PT_API_URL/v1/templates/from-image" \
  -H "Authorization: Bearer $PT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"py3-data","image":"python:3.13-slim","default_cpu":2,"default_ram_mb":1024}'

The build pins and pulls the image. The rootfs grows to fit it. build() waits until the template is ready (up to 5 min). Pass wait_ms: 0 to skip the wait and poll templates.get(id) yourself.

If you omit entrypoint, the image's own CMD/ENTRYPOINT runs at boot, supervised. Set "none" for a pure code-runner that launches nothing. Bake environment variables with the builder's .env() step, or pass env at sandbox create.

When the template is ready, create sandboxes with "template": "py3-data". See Sandboxes.

Prepare the first boot

For another region, prepare the exact ready template before creating sandboxes:

curl -X POST "$PT_API_URL/v1/templates/tpl_01K…/prepare" \
  -H "Authorization: Bearer $PT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"region":"us-east"}'

The target region's control plane verifies its own image residency. A home-region copy is not proof that another region is ready. 200 returns { "template_id": "...", "region": "us-east", "state": "ready", "status": "ready" }. 202 means the copy is queued, copying, or cooling down after failure; poll the same request using retry_after_ms. Repeated requests reuse the existing copy queue. 503 template_prepare_unavailable means that region cannot prepare the image; it must not be treated as ready. Copies claim the target region's shared SQL row atomically. A concurrent control plane cannot start a second copy or reset a ready copy, and delayed attempts cannot overwrite the current attempt's progress, success, or failure.

You do not always need to call prepare. When your org created a sandbox in a region within the last 7 days, that region copies each new template built in the last 24 hours as soon as it is ready. Prepare is still the proof that the copy has finished.

Preparation requires ownership, template-write permission, regional access, and a ready chunked template. Foreign, tenant-inaccessible global, missing, and deleted templates return 404; unsupported regions or invalid bodies return 400. Preparation copies image data only: no VM starts and no running-sandbox quota is consumed. It does not certify host capacity or guest-runtime readiness.

Use exact-template materialization after regional preparation when host-side first-boot latency matters. This assembles the immutable rootfs on one eligible host. It does not start a VM or consume running-sandbox quota.

curl -X POST "$PT_API_URL/v1/templates/tpl_01K…/materialize" \
  -H "Authorization: Bearer $PT_TOKEN"

The route waits up to 15 seconds. It returns 200 when the rootfs is ready. It returns 202 when assembly continues in the background. Repeating the request reuses the same in-flight command.

Build with code

Template also defines an image as a chain of steps in code — pipInstall, aptInstall, copy, workdir, and more. The declarative builder page owns the full step reference and examples, including inline builds at sandbox create.

Build from git

When the apps feature is enabled for your org, POST /v1/templates/from-git builds a template from a repo's Dockerfile. The CLI form is pt template build <name> --repo <url>. Request bodies: API reference.

List and get

get returns the template's current state and, after a build finishes, its buildLogs.

const all = await client.templates.list();
const tpl = await client.templates.get("tpl_01K…");

all = client.templates.list()
tpl = client.templates.get("tpl_01K…")

pt template list
pt template get tpl_01K…

curl -H "Authorization: Bearer $PT_TOKEN" "$PT_API_URL/v1/templates?name=py3-data"
# template detail routes: see /docs/api

Update a template

The image and rootfs are baked in. To change them, rebuild. PATCH updates the version, default CPU/RAM/disk, and entrypoint.

// no typed method — use client.request("PATCH", "/v1/templates/tpl_01K…", { version: "1.1.0", default_ram_mb: 2048 })

# no typed method — use client.request("PATCH", "/v1/templates/tpl_01K…", ...)

pt template update tpl_01K… --version 1.1.0 --ram 2048

curl -X PATCH -H "Authorization: Bearer $PT_TOKEN" "$PT_API_URL/v1/templates/tpl_01K…" \
  -d '{ "version": "1.1.0", "default_ram_mb": 2048 }'

Delete a template

Delete sandboxes using the template before deleting it. An active build must finish or be cancelled first.

Deletion removes the template from lists and frees its name. Historical records remain available for audit.

await client.templates.delete("tpl_01K…");

client.templates.delete("tpl_01K…")

pt template rm tpl_01K…

# template delete route: see /docs/api