Skip to main content
A template is the blueprint a sandbox is created from. It defines the base image, the installed packages, the files, the environment and the commands that run at startup. Every sandbox is spawned from a template, so building a template produces a reusable, ready-to-run environment.

Template and Dockerfile

Templates are close to container images. A template is built from a Docker image, and the build is similar to writing a Dockerfile: start from a base image and layer instructions on top. The difference is where and how those instructions are expressed. In short, a template starts from a Docker image. Building one feels similar to authoring a Dockerfile, but the steps are SDK calls (fromImage, runCmd, copy, setEnvs) instead of a Dockerfile. The output is a templateId that PPIO uses to launch sandboxes quickly.

Template and snapshot

A snapshot is a reusable saved state of a sandbox. It captures the sandbox filesystem and memory state, so new sandboxes can start from that point later. Templates and snapshots both spawn a new sandbox from a predefined starting point. They differ in how that point is produced and in what it captures.
Snapshots are available only in some regions.
Use a snapshot to:
  • Prepare dependencies once and reuse them in later sandboxes.
  • Save a known-good state before running risky or expensive work.
  • Start multiple sandboxes from the same captured environment.
  • Keep a reusable state after the original sandbox is no longer needed.

Public templates

On the AGENT SANDBOX › Templates page of the console, a template provided by PPIO carries the badge. Every team can use such a template by default. Publishing and unpublishing a team’s own template are described in Manage templates.

Next steps

Build with the SDK

Define a template with builder calls, then build it.

Build with the CLI

Build a Dockerfile into a template with ppio template create.

Manage templates

List templates, assign tags, publish or unpublish, and delete a template.
Last modified on November 19, 2026