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 thefrom* 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, usefrom_image / fromImage with a user name and password. Dedicated helpers exist for AWS ECR, Google Container Registry, Oracle Cloud (OCI) and Huawei Cloud SWR.
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.
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 withpip 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.
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.- Python
- Node.js
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 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.