Skip to main content
Sandbox persistence pauses a sandbox and resumes it later with the same filesystem and memory state. Use it for long-running agent tasks, interactive apps, and workflows that survive idle periods without keeping compute resources active.
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.

Pause and resume a sandbox

When a sandbox is paused:
  • Files created in the sandbox are preserved.
  • In-memory state is preserved, including running processes and variables.
  • Network connections are interrupted until the sandbox resumes.
  • The sandbox remains stored until it is resumed and killed, or killed while it is paused.
1

Pause the sandbox

Write a file so the state is visible after the resume, then pause.
2

Resume the sandbox

Resume with ppio.sandbox.connect(), then read the file back.

Full example

In the CLI example, <sandbox-id> is the sandbox ID.

Set the timeout when resuming

Resuming a sandbox with connect() resets its timeout to the SDK default listed on Sandbox lifecycle and states. To set a different timeout, pass it to connect(): timeout in seconds in Python, timeoutMs in milliseconds in Node.js.

Pause and resume automatically

Use lifecycle settings to pause the sandbox automatically after its timeout, and optionally resume it when activity is detected.

Use auto-resume with a web server

Auto-resume works well for preview environments and web servers.

Common questions

Paused sandboxes stop CPU and RAM billing. While paused, the filesystem and memory stay in persistent storage. See How Agent Sandbox billing works.
Read usage from the quota API to see how many sandboxes currently count toward the concurrency limit.
Last modified on November 19, 2026