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

# 克隆沙箱

export const SandboxBetaVersionWarning = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Warning>注意以下功能需要 <Link href="/sandbox/sandbox-sdk-and-cli#安装-beta-版-sdk" target="self">安装 Beta SDK & CLI</Link> 才能使用。另外 Beta 版功能在合并到稳定版前，可能会经历多次迭代，因此可能存在不稳定性。如果您在使用过程中遇到任何问题，欢迎 <Link href="https://ppio.com/contact" target="_blank">联系我们</Link>。</Warning>;
  }
};

现阶段的 AI Agent 在执行复杂任务时面临着一个根本性的限制："n of 1"问题——AI 和开发者被限制在单一工作环境中进行串行推理。这种模式导致了以下几个关键问题：

1. **实验冲突与环境污染**。当 AI Agent 尝试多种解决方案时，实验性的代码变更可能会干扰开发者的主要工作流程，或者污染当前的运行环境。一旦实验出错，往往只能通过回滚来恢复，无法保留有价值的探索路径。

2. **无法并行探索多个方案**。受限于单一环境，AI Agent 只能按顺序测试不同的解决思路。这种串行模式不仅效率低下，更重要的是限制了 AI 的探索广度——无法同时验证多个并行的假设或实现方案。

3. **计算能力扩展受限**。当面对需要 "广度并行探索" (Wide-Research) 的任务时（例如同时比较 100 个解决方案、批量生成多个实现版本），单一环境的架构从根本上制约了任务的并行化处理能力。

**"沙箱克隆"** 功能实现了从 "深度单线探索"（Deep-Research）到 "广度并行探索" (Wide-Research)的转变：

1. **多时间线探索架构**：就像决策树一样，AI Agent 可以从同一个基准状态出发，创建多个独立的沙箱副本，每个副本探索一条不同的解决路径，互不干扰。
2. **真正的并行计算能力**：通过将大任务拆分成批量子任务，AI Agent 能够将计算能力扩展数十倍甚至上百倍，同时处理数十个、上百个探索分支。
3. **零风险实验环境**：克隆出的沙箱完全隔离，AI 可以在其中自由实验、测试各种可能性，而不会影响原始环境或开发者的主工作流程。
4. **高效的资源利用**：虽然可能同时启动多个沙箱实例，但通过动态管理和及时终止不再有价值的分支（沙箱实例），总体计算资源消耗可以保持在合理范围内。

这种能力使 AI Agent 能够突破当前的性能瓶颈，从提供理论建议转变为交付经过并行验证、实际测试的可靠方案，真正实现自主探索、迭代和解决复杂问题的能力。

<SandboxBetaVersionWarning />

## 名词定义

* **原始沙箱（Origin Sandbox）**：被克隆的原始沙箱实例。
* **新沙箱（New Sandbox）**：通过克隆操作创建的新沙箱实例。

## 功能概述

当前沙箱克隆功能支持以下两种场景：

* 克隆运行中（Running）状态的沙箱
* 克隆已暂停（Paused）状态的沙箱

### 克隆运行中（Running）状态的沙箱

**克隆过程中：**

* 在克隆执行期间，原始沙箱会被短暂挂起；
* 挂起期间该沙箱实例不可用；
* 挂起时长接近一次暂停（pause）操作所需的时间。

**克隆完成后：**

**原始沙箱：**

* 状态恢复为运行中（running）；
* 原有的暂停记录会被清除，但是随即以当前状态生成一条新的暂停记录；
* 生成一条新的快照模板记录（如果想要删除该快照模板，需要先终止原始沙箱和克隆出来的沙箱）；

**新沙箱：**

* 状态为运行中（running）；
* 可立即使用。

### 克隆已暂停（Paused）状态的沙箱

**克隆过程中：**

当原始沙箱处于已暂停（paused）状态时：

* 克隆过程不会触发原始沙箱的启动；
* 原始沙箱保持暂停状态。

**克隆完成后：**

**原始沙箱：**

* 原有的暂停记录不会被清除；
* 生成一条新的快照模板记录（如果想要删除该快照模板，需要先终止原始沙箱和克隆出来的沙箱）；

**新沙箱：**

* 状态为运行中（running）；
* 可立即使用。

### 新沙箱的属性继承规则

| 属性          | 是否继承 |
| ----------- | ---- |
| auto resume | 是    |
| auto pause  | 否    |

## 参数说明

* `count`：要克隆的沙箱实例数量。最小值为 1，最大值不超过平台限制的并发运行的沙箱实例数（参考：[沙箱并发限制](/sandbox/quota-limits)）；
* `strict`：是否严格按照 count 参数中指定的数量进行克隆，默认为 false。
  * `true`：若成功克隆的实例数量小于 count，则返回克隆失败；已创建成功的沙箱会被自动释放。
  * `false`：返回实际成功克隆的沙箱实例数量。
* `timeout`(`timeoutMs`)：克隆沙箱实例的超时时间。
  * 若未指定：
    * 当原始沙箱为运行中（running）状态时，继承其超时时间配置；
    * 当原始沙箱为已暂停（paused）状态时，使用默认值 5 分钟。

## 返回值说明

克隆操作成功后返回一个对象，包含以下属性：

| 属性                     | 说明              |
| ---------------------- | --------------- |
| `sandboxes`            | 克隆成功的沙箱实例列表     |
| `count`                | 成功克隆的沙箱数量       |
| `snapshot_template_id` | 克隆过程中产生的快照模板 ID |

## 代码示例

<CodeGroup>
  ```python Python icon="python" theme={null}
  from ppio_sandbox.core import Sandbox

  # Create a sandbox
  sandbox = Sandbox.create(template="base")
  # clone
  clones = Sandbox.clone(sandbox.sandbox_id, 2)

  print("snapshot:", clones.snapshot_template_id)
  for sbx in clones:
      print("clone sandbox:", sbx.sandbox_id)
  ```

  ```js JavaScript & TypeScript icon="js" theme={null}
  import { Sandbox } from '@ppio-sandbox/core'

  // Create a sandbox
  const sandbox = await Sandbox.create('base')

  // clone
  const sbxClones = await Sandbox.clone(sandbox.sandboxId, { count: 2 })

  console.log("snapshot：", sbxClones.snapshotTemplateId)
  for (const idx in sbxClones.sandboxes) {
      console.log("clone sandboxID[" + idx + "]：", sbxClones.sandboxes[idx].sandboxId)
  }
  ```
</CodeGroup>

同时，您还可以使用 PPIO 沙箱命令行工具来克隆指定的沙箱实例：

```bash Bash icon="terminal" theme={null}
# ppio-sandbox-cli sandbox clone [sandboxID] -c [count] -s [strict] -t [timeout]
ppio-sandbox-cli sandbox clone 0r0efkbfwzfp9p7qpc1c -c 2
```