Skip to main content
A sandbox moves through three states, and two settings decide when it leaves the first one. This page is the reference for the state model, the settings that drive the transitions, and the defaults the SDK applies when a setting is not passed.
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.
On timeout or idle timeout, pause can be chosen instead of kill, so the sandbox can be resumed later, optionally with auto-resume. When paused, resuming restores the sandbox to Running with its state intact. When killed, the sandbox and its data are gone. The timeout of a running sandbox can be extended at any time. Pausing a sandbox keeps its state without a running clock.

Timeout and auto-resume settings

Both settings live in the lifecycle object at creation. If lifecycle is not passed, the sandbox is killed when the timeout expires.
SandboxLifecycle
What happens 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 timeout is passed.
  • A sandbox resumed with connect() gets a new timeout of 5 minutes unless a timeout is passed to connect().
  • The sandbox is killed, not paused, when the timeout expires.
  • Long-running mode is off, so timeout is 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.
Long-running mode does not disable the idle timeout. A sandbox with an idle timeout is still paused or killed when it has no active connections.

Scope and inheritance

  • Only create accepts long_running.
  • resume, including auto-resume, keeps the behavior: a sandbox created with long_running keeps it after being resumed from a snapshot.
  • clone inherits the parameter, and the sandbox keeps it when it continues running after a reset.

Cost and quota

The team’s cap is returned by the quota API as limit.max_length_hours in Python and limit.maxLengthHours in Node.js.
A long-running sandbox keeps running until its timeout, an idle timeout, or kill(), and bills per second the whole time. Set an explicit timeout, and an idle timeout for services that can sleep.
Last modified on November 19, 2026