Skip to main content
Build a sandbox template from a Dockerfile or public OCI image as an immutable private version. Each reservation creates a new version; rebuilding does not overwrite an existing template ID.

​
Reserve a version

Keep the returned templateID and buildID. The API is POST /v3/templates; it also accepts runtime cpuCount and memoryMB.

​
Start the build

Save this as build.json:
Replace TEMPLATE_ID and BUILD_ID with the reservation values:
Choose exactly one of fromImage or dockerfile. Dockerfile inputs use Dockerfile text plus context, a byte array containing a tar archive. Context is bounded to 32 MiB compressed and 256 MiB expanded; entries must be regular files or directories with relative paths. Custom images require a Debian bookworm-compatible userland. Private registry credentials and fromTemplate are rejected. Build secrets are unsupported: keep credentials out of Dockerfiles, context, and startup commands.

​
Configure startup

Optional startCmd and readyCmd are shell commands. The app starts before the prepared checkpoint; readiness must succeed within 60 seconds. Use these fields for your application rather than relying on OCI ENTRYPOINT to replace the machine’s init. defaultKind selects the default machine kind. Optional buildResources selects builder CPU and memory independently of the published runtime shape. timeoutSeconds accepts 1–3600 seconds; omission defaults to 720.

​
Wait for readiness

Status is waiting, building, ready, or error. Continue logs with --offset. A ready template can be used for new machines:

​
Retire a version

Retirement prevents new creates. Existing machine references keep their immutable version. Reserve a new version for changes; names do not implicitly switch a mutable alias.