Skip to main content
Create a sandbox with one SDK call or one ppio sandbox create command. The call takes a template name or ID and options such as the timeout, environment variables and . Metadata set at creation is what list filters match later.
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.

Create from the default template

Call create() without arguments to start a sandbox from the default base template.

Create from a template

Pass the name or ID of an existing template as the first argument to create the sandbox from that template instead of base.

Use a context manager in Python

Use a context manager for automatic cleanup.
Python

Create options

The options below are the ones this page uses. Pass them as arguments in Python and as one options object in Node.js.
string
default:"base"
First argument: template name or ID.
number
Sandbox timeout in seconds. Optional.
object
Key-value pairs stored with the sandbox, such as an ID from the calling application.
object
Environment variables available to commands in the sandbox.

Set sandbox environment variables

Set environment variables when creating the sandbox. A single command can override or append them.

Attach metadata

Metadata attaches custom key-value information to a sandbox. Common uses:
  • Connecting a sandbox to a user session.
  • Saving custom user-related data for a sandbox, such as API keys.
  • Linking a sandbox to a user ID so it can be reconnected later.
Metadata is set when the sandbox is created. Listing active sandboxes with ppio.sandbox.list() returns it later. Listing accepts a metadata filter and a state filter. Multiple conditions are combined with AND.
Last modified on November 19, 2026