Building templates

A template is the frozen image a sandbox boots from. On your own install, register the default template once, then build any others from container images.

Know the default

A create with no template, or with pt-base, uses the template named pt-base (PT_DEFAULT_TEMPLATE). Until one exists, each organization builds PT_DEFAULT_IMAGE on its first such create. Compose sets that image to alpine:3.20.

Register pt-base for everyone

A template with "global": true is visible to every organization. Only platform admins and the ADMIN_TOKEN can create one.

curl -s -X POST https://api.example.com/v1/templates/from-image \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'content-type: application/json' \
  -d '{"name":"pt-base","image":"python:3.12-slim","global":true}'

A host pulls the image and builds the root filesystem. Poll GET /v1/templates/<id> until state is ready. A failed build ends in failed.

Anyone else asking for global gets 403 global_template_forbidden.

Build your own

An API key builds a template for its own organization.

curl -s -X POST https://api.example.com/v1/templates/from-image \
  -H "Authorization: Bearer $PT_TOKEN" -H 'content-type: application/json' \
  -d '{"name":"py313","image":"python:3.13-slim","default_cpu":2,"default_ram_mb":1024}'

To build from the SDKs, the CLI or a spec, see Templates and Declarative builder.

Follow the image rules

• Pin the tag. latest, lts, stable, main, master, edge and rolling return 400 floating_tag_rejected. A version or an @sha256: digest works.
• A name with no registry resolves to Docker Hub.
• Without object storage, a template exists only on the host that built it, and all its sandboxes land there.

Size it

The template sets defaults. A create can override CPU, RAM and disk.

size_mb is the starting root filesystem size. RAM usually decides how many sandboxes fit on a host: see Hardware.