Skip to main content
Agent Sandbox runs agent workloads in isolated cloud sandboxes. Each sandbox has its own filesystem and runtime, so an agent can install dependencies, run commands, drive a browser and keep state across sessions without infrastructure to manage. This page covers the core concepts, the lifecycle, isolation and billing.

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.
A snapshot is useful after configuring a sandbox, installing dependencies or generating files that should be reused. New sandboxes start from the saved state without repeating those setup steps.

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.
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.

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 and allowPublicTraffic are fixed while a sandbox is running. To change either one, start a new sandbox.

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.
Last modified on November 19, 2026