> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ppio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Sandbox: secure cloud sandboxes for AI agents

> Run agent code, browsers and files in isolated cloud sandboxes through a Python or Node.js SDK, and keep state between sessions without managing infrastructure.

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

> [card] [Sandbox](https://docs.ppio.ai/sandbox/lifecycle.md)
>
> An isolated environment for commands, files and dependencies.

> [card] [Template](https://docs.ppio.ai/sandbox/templates/overview.md)
>
> A reusable blueprint that every sandbox starts from.

> [card] [Snapshot](https://docs.ppio.ai/sandbox/snapshots.md)
>
> 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.

```mermaid theme={null}
flowchart LR
  T[Template] -->|create a sandbox| S[Sandbox]
  S -->|save current state| P[Snapshot]
  P -->|create new sandboxes| N[New sandbox]
```

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

```mermaid theme={null}
stateDiagram-v2
    [*] --> Running
    Running --> Paused: pause
    Running --> Killed: kill
    Running --> Killed: timeout or idle timeout
    Running --> Paused: timeout or idle timeout with pause
    Paused --> Running: resume
    Paused --> Running: auto-resume
    Paused --> Killed: kill
```

Two settings drive the transitions out of Running:

> [card] [Timeout](https://docs.ppio.ai/sandbox/timeout.md)
>
> The maximum lifetime, counting down from creation regardless of activity.

> [card] [Idle timeout](https://docs.ppio.ai/sandbox/idle-timeout.md)
>
> 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.

| Layer | What isolates it | Default |
| - | - | - |
| Runtime | Each sandbox has its own filesystem, process space and network stack | Always on |
| SDK access (commands, files, PTY, upload and download URLs) | Per-sandbox access token, attached by the SDK automatically | On since SDK v2.0.0 (`secure`) |
| Service URLs (`https://{port}-{sandboxId}.{domain}`) | Traffic access token in the `Sandbox-Traffic-Access-Token` header | Public unless `allowPublicTraffic` is `false` |
| Outbound network | Disable internet access, or allow and deny domains and CIDRs | Internet access on |
| Data lifetime | The ephemeral disk is deleted when the sandbox is killed, including on timeout unless the lifecycle pauses it | Always on |

> [!WARNING]
>
> `secure` and `allowPublicTraffic` are fixed while a sandbox is running. To change either one, start a new sandbox.

> [card] [Secure access to sandbox services](https://docs.ppio.ai/sandbox/secured-access.md)

> [card] [Control internet access and expose ports](https://docs.ppio.ai/sandbox/internet-access.md)

## 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:

> [card] Coding agents
>
> Run code, install packages and execute tests.

> [card] Browser agents
>
> Automate web workflows.

> [card] Data analysis agents
>
> Process files and generate reports.

> [card] 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.

> [card] [Pricing](https://ppio.ai/pricing)

> [card] [How Agent Sandbox billing works](https://docs.ppio.ai/sandbox/billing.md)

## Next steps

Sandboxes are created and managed with the SDK or the CLI.

> [card] [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md)
>
> Go from an API key to a running sandbox in Python or Node.js.

> [card] [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md)
>
> See how timeout, idle timeout, pause and auto-resume move a sandbox between states.

> [card] [What is a sandbox template?](https://docs.ppio.ai/sandbox/templates/overview.md)
>
> Start every sandbox from a prepared environment.

> [card] [Install and sign in to the PPIO CLI](https://docs.ppio.ai/sandbox/cli/install.md)
>
> Work with sandboxes from the terminal.


## Related topics

- [Agent Sandbox errors](https://docs.ppio.ai/sandbox/errors.md)
- [Agent Sandbox quotas and limits](https://docs.ppio.ai/sandbox/quotas.md)
- [How Agent Sandbox billing works](https://docs.ppio.ai/sandbox/billing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.