Core concepts
Sandbox
An isolated environment for commands, files and dependencies.
Template
A reusable blueprint that every sandbox starts from.
Snapshot
A saved state that new sandboxes start from.
The sandbox lifecycle
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.
Timeout
The maximum lifetime, counting down from creation regardless of activity.
Idle timeout
Fires only when no client is connected for the configured duration.
Isolation and security
Each sandbox is a separate runtime with its own filesystem, processes and network, so code in one sandbox cannot see another sandbox or the machine that started it. SDK access is protected by a per-sandbox access token by default. Service URLs can be made private, and outbound traffic can be restricted.Secure access to sandbox services
Control internet access and expose ports
When to use Agent Sandbox
Agent Sandbox is intended for workloads that need isolated environments to execute tasks, keep state or reuse prepared setups. Common use cases:Coding agents
Run code, install packages and execute tests.
Browser agents
Automate web workflows.
Data analysis agents
Process files and generate reports.
Research or reinforcement-learning workloads
Need many isolated environments.
Billing
Billing is per second for CPU and memory while a sandbox runs. Storage, which covers templates, paused sandboxes and snapshots, is charged daily.Pricing
How Agent Sandbox billing works
Next steps
Sandboxes are created and managed with the SDK or the CLI.Quickstart
Go from an API key to a running sandbox in Python or Node.js.
Sandbox lifecycle and states
See how timeout, idle timeout, pause and auto-resume move a sandbox between states.
What is a sandbox template?
Start every sandbox from a prepared environment.
Install and sign in to the PPIO CLI
Work with sandboxes from the terminal.