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.States
A sandbox moves through three states: Running, Paused, and Killed.- Running: the sandbox is active and can execute commands and serve connections.
- Paused: the sandbox is suspended. Its filesystem and memory state are preserved and billing for compute stops. It can be resumed back to Running, typically in about a second.
- Killed: the sandbox is terminated and its resources are released. A killed sandbox cannot be resumed.
What moves a sandbox out of Running
Two settings drive the transitions out of Running.Timeout
The maximum lifetime, counting down from creation regardless of activity.
Idle timeout
Fires only when no client is connected for the configured duration.
Timeout and auto-resume settings
Both settings live in thelifecycle object at creation. If lifecycle is not passed, the sandbox is killed when the timeout expires.
SDK defaults
The SDK applies these defaults when the call does not set them:- A new sandbox stays alive for 5 minutes unless
timeoutis passed. - A sandbox resumed with
connect()gets a new timeout of 5 minutes unless a timeout is passed toconnect(). - The sandbox is killed, not paused, when the timeout expires.
- Long-running mode is off, so
timeoutis capped by the team’s maximum session duration.
The console Playground applies different defaults. Lifecycle is Long running and On timeout is Pause, so a sandbox created there can outlive the SDK default and pauses instead of being killed. Both settings are on the Playground.
Long-running sandboxes
By default,timeout is effective for at most the team’s maximum session duration, and a larger value is capped. See Quotas and limits. Long-running mode lifts that cap, so the timeout passed at creation can exceed it. Use it for workloads that stay alive beyond a typical session, such as persistent services, long agent tasks, and background jobs.
Long-running mode is configured through the metadata field at creation. The key is long_running and the value is "true", as a string.
long_running works together with timeout: set the timeout the sandbox needs. Without long_running, timeout is effective for at most the team’s maximum session duration. If timeout is not set, it defaults to 5 minutes.
Scope and inheritance
- Only
createacceptslong_running. resume, including auto-resume, keeps the behavior: a sandbox created withlong_runningkeeps it after being resumed from a snapshot.cloneinherits the parameter, and the sandbox keeps it when it continues running after areset.
Cost and quota
The team’s cap is returned by the quota API aslimit.max_length_hours in Python and limit.maxLengthHours in Node.js.