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.

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.

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

Sandboxes already running from the template keep running. New sandboxes cannot use it. The name is free again at once.

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

client.templates.delete("tpl_01K…")

pt template rm tpl_01K…

# template delete route: see /docs/api