Skip to main content
The SDK defines a template with a chainable builder, starting from a base image and adding build steps. Building the definition stores it under a template name and returns a build whose template ID creates sandboxes. Use the PPIO client as the entry point: start with ppio.template.new() in both Python and Node.js.
Install the SDK, or the CLI for ppio commands, and set the PPIO_API_KEY and PPIO_DOMAIN environment variables before running these examples. See Quickstart and Install and authenticate.

Build a template

1

Define the template

Start from a base image and add the steps the build runs.
2

Build the template

Pass the definition and a template name. CPU and memory apply to the sandboxes created from the template.
3

Create a sandbox from the template

Pass the template ID from the build. The sandbox starts from the built image.

Full example

The CLI block builds the template from a Dockerfile instead of builder calls.

Names

Every build needs a template name. Keep names stable for a logical template family. The returned template ID is the immutable build output used at runtime.

Builder methods

Each method returns the builder, so calls chain. Pass options as keyword arguments in Python and as a trailing options object in Node.js.

Choose a base image

A template definition starts by choosing a base image, or an existing template, with one of the from* methods.

Build from a private registry

To build from an image hosted in a private or cloud registry, pass credentials when selecting the base image. For a generic registry, use from_image / fromImage with a user name and password. Dedicated helpers exist for AWS ECR, Google Container Registry, Oracle Cloud (OCI) and Huawei Cloud SWR.
Pass registry credentials and Git tokens from environment variables, never in a repository URL.

Set the user and workdir

After choosing a base image, control which user the following build steps run as and which directory they run in.

Run a command

run_cmd / runCmd runs a shell command during the build. It accepts a single command string or a list of commands joined with &&, and an optional user to run as.

Copy files

copy includes local files or directories in the image. The source may be a single path or a list of paths, and the destination is a path in the template. Options control ownership, permissions and upload behavior.

Set environment variables

set_envs / setEnvs sets environment variables from a key and value mapping.
Environment variables set with set_envs / setEnvs are available only during the template build, not at sandbox runtime.

Install packages

Dedicated helpers wrap common package managers. Each accepts a single package name or a list. When packages are omitted, the language helpers install from the working directory with pip install . or package.json.

Clone a repository

git_clone / gitClone clones a repository into the image. Only the URL is required. A destination path and clone options are optional.
git_clone / gitClone has no authentication parameters. For a private repository, set up access in an earlier run_cmd / runCmd or set_envs / setEnvs step, with the token taken from an environment variable rather than written into the URL.

Set CPU and memory

CPU and memory are set when the template is built. Set the size at build time, then create sandboxes from the template.
number
vCPU is a whole number. Must stay within the team’s maximums.
number
Memory is set in fixed increments and scales with the vCPU count, within a fixed range per vCPU. Must stay within the team’s maximums.
Current maximums are on Quotas and limits.

Control build caching

Template builds cache completed layers, so a repeated build does not rerun every instruction, which speeds up iteration. Caching is enabled by default and needs no configuration. Skip the cache only when a fresh build is required: a build without the cache is significantly slower. The SDK and the CLI offer three levels of control.
The chained skip_cache() / skipCache() method does not skip a single instruction. It applies to every subsequent layer from the point where it is called, so the earlier the call, the more of the cache is invalidated.
The example skips the cache in the definition and forces a full rebuild. The two approaches can be combined.

Tag builds

Tags label builds for release management without changing the underlying template name. Pass tags when the template is built, or assign them later.

Read build logs

Build logs show provisioning progress and help diagnose a failed build.
Template builds fail for these common reasons: invalid credentials for a private registry, a package install failure inside run_cmd / runCmd, a start command that exits unexpectedly, a ready command that never succeeds, or CPU and memory settings outside the platform limits. See Errors.
Last modified on November 19, 2026