Skip to main content
The CLI builds a Dockerfile directly into a reusable sandbox template. It reads the Dockerfile, builds the image, applies the sandbox settings for the start command, ready command, CPU and memory, and registers the result under the template name. Sandboxes are then created from that name with sandbox.create(...).
Authentication is required. Sign in with ppio auth login, or set PPIO_API_KEY in the environment.

Build a template

1

Write the Dockerfile

Create ppio.Dockerfile in the root directory. Without --dockerfile, the CLI looks for ppio.Dockerfile first and falls back to Dockerfile.
ppio.Dockerfile
2

Run the build

Pass the template name. The name must be lowercase and contain only letters, numbers, dashes and underscores.
CLI
3

Create a sandbox from the template

Once the build finishes, create sandboxes from the template by name.
CLI

Files read by the build

The minimal build reads these two files from the current directory.
my-python-template
app.py
ppio.Dockerfile

Usage

CLI
string
required
Template name to create or rebuild. The name must be lowercase and contain only letters, numbers, dashes and underscores, matching ^[a-z0-9-_]+$.

Options

string
Root directory where the command runs. Defaults to the current directory. Dockerfile lookup and the build file context resolve relative to it.
string
Path to the Dockerfile, relative to the root directory. Without this option, the CLI looks for ppio.Dockerfile first and falls back to Dockerfile.
string
Command that runs when the sandbox starts. Must be used together with --ready-cmd.
string
Command that must exit with code 0 for the template to be considered ready. Can be used on its own.
number
default:"2"
Number of CPUs used to run the sandbox.
number
default:"1024"
Memory in megabytes used to run the sandbox. Must be an even number.
boolean
Skips the build cache when building the template.
string
Command that patches an incompatible base image at the end of the provision phase.

Behavior and validation

  • --cmd and --ready-cmd must be provided together. A build that passes --cmd without --ready-cmd fails. --ready-cmd alone is allowed.
  • An invalid template name, or an odd value for --memory-mb, aborts the build before anything is sent to the server.
  • Build logs stream to the terminal. On success, the CLI prints Python and Node.js snippets that show how to create a sandbox from the new template.

Examples

Reads ./ppio.Dockerfile, or ./Dockerfile, in the current directory:
CLI
Points the build at a specific Dockerfile relative to the root directory:
CLI
A custom root directory, resources, start and ready commands, and no cache:
CLI

Create a sandbox from the template

Create sandboxes from the template by name with the SDK:
Node.js
Last modified on November 19, 2026