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

# 概述

<Note>
  PPIO Sandbox 提供为 AI Agent 设计的隔离、有状态的执行环境。它支持运行代码、安装依赖、访问文件、使用浏览器,并能跨会话保留状态,而无需管理基础设施。
</Note>

# 简介

PPIO Sandbox 是一个面向 AI Agent 的托管执行环境,适用于需要运行代码、使用浏览器、处理文件并跨会话保留状态的场景。它为每个 Agent 提供隔离的运行时,而无需你管理基础设施。

***

# 核心概念

## Sandbox

供 Agent 执行任务的隔离执行环境。每个 Sandbox 都拥有自己的文件系统和运行时,Agent 可以在其中运行命令、管理文件、安装依赖,并处理基于浏览器的工作流。

### 生命周期

<img src="https://mintcdn.com/ppinfra/nkBi88UBzmHnrrPQ/images/sandbox/sandbox-lifecycle.png?fit=max&auto=format&n=nkBi88UBzmHnrrPQ&q=85&s=f846317c81a233f73b010dd8bb804e8e" alt="Sandbox 生命周期状态转换图" width="1280" height="556" data-path="images/sandbox/sandbox-lifecycle.png" />

Sandbox 会经历三种状态:Running、Paused 和 Killed。

* **Running** — Sandbox 处于活跃状态,可以执行命令并对外提供连接。
* **Paused** — Sandbox 被挂起;其文件系统和内存状态会被保留,计算资源停止计费。它可以恢复回 Running 状态(通常约 1 秒)。
* **Killed** — Sandbox 被终止,其资源被释放。已终止的 Sandbox 无法恢复。

有两项设置决定 Sandbox 如何从 Running 状态转出:

* **超时(Timeout)** — Sandbox 的最长生命周期。它从创建时开始倒计时,与活动无关;到期后 Sandbox 默认会被停止,也可以通过相应的生命周期配置改为暂停。参见[超时处理](/docs/sandbox/sandbox-timeout)。
* **空闲超时(Idle timeout)** — 仅当在配置的时长内没有任何客户端连接时触发,自动终止或暂停 Sandbox。参见[空闲超时处理](/docs/sandbox/sandbox-idle-timeout)。

在超时或空闲超时发生时,你可以选择**暂停(pause)**而不是**终止(kill)**,这样 Sandbox 之后还可以恢复(并可选自动恢复)。处于暂停状态时,恢复操作会将 Sandbox 连同其状态一起还原为 Running;而一旦被终止,Sandbox 及其数据都会丢失。

## Template

定义 Sandbox 的初始环境。Template 通过预定义的依赖、配置和设置步骤,确保多个 Sandbox 之间环境的一致性。

## Snapshot

Snapshot 将 Sandbox 的当前状态保存为可复用的环境。当你已经配置好 Sandbox、安装了依赖或生成了需要复用的文件时,Snapshot 非常有用。新的 Sandbox 可以基于 Snapshot 创建,无需重复相同的设置步骤。

## Secret

Secret 是在 PPIO Sandbox 中安全存储和使用敏感值（如 API 密钥、令牌和密码）的方式。它在当前团队范围内加密管理，让 Sandbox 中运行的代码无需在源代码、Snapshot 或环境变量中硬编码凭证，即可向外部服务进行身份验证。

***

# 何时使用 PPIO Sandbox

适用于需要隔离环境来执行任务、维护状态或复用已准备好的环境的工作负载。常见使用场景包括:

* 运行代码、安装软件包并执行测试的编码 Agent
* 自动化 Web 工作流的浏览器 Agent
* 处理文件并生成报告的数据分析 Agent
* 需要大量隔离环境的研究或 RL 工作负载

***

# 区域

PPIO 目前提供两个区域的访问方式:

| 名称 | 版本 | 域名 | 说明 |
| - | - | - | - |
| cn-shanghai-1 | v1 | `sandbox.ppio.cn` | 默认区域 |
| cn-beijing-1 | v2 | `cn-beijing-1.sandbox.ppio.com` | 需通过环境变量指定 |

v2 区域在 v1 的基础上新增了 [Secret 密钥](/docs/sandbox/secret-overview)、[Snapshot 快照](/docs/sandbox/snapshot-overview)等能力，功能更加完善。**推荐优先使用 v2 区域**。

本文档的 SDK 和 CLI 同时兼容 v1 和 v2 区域。如果想使用 v2 区域,需要配置环境变量 `PPIO_DOMAIN`:

```bash theme={null}
export PPIO_DOMAIN=cn-beijing-1.sandbox.ppio.com
```

***

# 定价

CPU 和 RAM 按秒计费。存储(包括 Template、已暂停的 Sandbox 和 Snapshot)按天收费。更多详情请参阅[定价页面](/docs/sandbox/pricing)。

***

# 快速开始

可以通过 SDK 或 CLI 启动和管理 Sandbox。[快速开始](/docs/sandbox/get-start)页面提供了进一步的指引。


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