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

# レガシー Sandbox Clone

export const SandboxBetaVersionWarning = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Warning>The following legacy features require the legacy SDK and CLI versions listed in <Link href="/docs/ja/guides/sandbox-legacy-e2b-compatible" target="self">Legacy SDKs & CLI</Link>. Please note that legacy features may be less stable than production releases. If you encounter any issues while using these features, please <Link href="https://meetings-na2.hubspot.com/junyu" target="_blank">contact us</Link>.</Warning>;
  }
};

<Warning>
  このレガシーページは、現在も 1.x または beta SDK 系列を使用しているユーザー向けに保持されています。新しい SDK 2.x 統合では、現行の Sandbox ドキュメントに従ってください。
</Warning>

現在の段階では、AI Agent が複雑なタスクを実行する際に根本的な制約に直面しています。それは「n of 1」問題です。つまり、AI と開発者が直列的な推論のために単一の作業環境に閉じ込められているということです。このパターンは、いくつかの重要な問題を引き起こします。

1. **実験の競合と環境の汚染**。AI Agent が複数の解決策を試す際、実験的なコード変更が開発者のメインワークフローに干渉したり、現在のランタイム環境を汚染したりする可能性があります。実験が失敗すると、多くの場合ロールバックが必要になり、価値のある探索経路を保持できません。

2. **複数の解決策を並列に探索できないこと**。単一環境に制約されているため、AI Agent は異なるアプローチを順番にしかテストできません。この直列モードは非効率であるだけでなく、より重要な点として、AI の探索範囲を制限します。複数の並列仮説や実装アプローチを同時に検証できないためです。

3. **計算能力のスケーラビリティの制限**。「Wide-Research」を必要とするタスク（例: 100 個の解決策を同時に比較する、複数の実装バージョンを一括生成する）に直面した場合、単一環境アーキテクチャはタスク処理を並列化する能力を根本的に制限します。

**「Sandbox Clone」** 機能により、「Deep-Research」から「Wide-Research」への移行が可能になります。

1. **マルチタイムライン探索アーキテクチャ**: 決定木のように、AI Agent は同じベースライン状態から開始し、複数の独立した sandbox コピーを作成できます。それぞれが互いに干渉することなく異なる解決経路を探索します。
2. **真の並列計算能力**: 大きなタスクを一括サブタスクに分割することで、AI Agent は計算能力を数十倍、場合によっては数百倍まで拡張し、数十または数百の探索ブランチを同時に処理できます。
3. **リスクゼロの実験環境**: clone された sandbox は完全に分離されているため、AI は元の環境や開発者のメインワークフローに影響を与えることなく、さまざまな可能性を自由に実験・テストできます。
4. **効率的なリソース利用**: 複数の sandbox インスタンスが同時に起動される場合がありますが、価値がなくなったブランチ（sandbox インスタンス）を動的に管理し、速やかに終了することで、全体の計算リソース消費を合理的な範囲内に抑えられます。

この機能により、AI Agent は現在の性能ボトルネックを突破し、理論的な提案を提供する段階から、並列に検証され実際にテストされた信頼性の高い解決策を提供する段階へ移行できます。これにより、複雑な問題を自律的に探索、反復、解決する能力を真に実現できます。

<SandboxBetaVersionWarning />

## 用語

* **Origin Sandbox**: clone 元となる元の sandbox インスタンス。
* **New Sandbox**: clone 操作によって作成される新しい sandbox インスタンス。

## 機能概要

sandbox clone 機能は現在、次の 2 つのシナリオをサポートしています。

* Running 状態の sandbox を clone する
* Paused 状態の sandbox を clone する

### Running 状態の Sandbox を clone する

**clone プロセス中:**

* origin sandbox は clone 中に短時間サスペンドされます。
* サスペンド中、sandbox インスタンスは利用できません。
* サスペンド時間は、単一の pause 操作に必要な時間に近いです。

**clone 完了後:**

**Origin Sandbox:**

* ステータスは running に復元されます。
* 既存の pause レコードは、現在の sandbox 状態に基づいて新しい pause レコードに更新されます。
* 新しい snapshot template レコードが生成されます（この snapshot template を削除するには、まず origin sandbox と clone された sandbox の両方を terminate する必要があります）。

**New Sandbox:**

* ステータスは running です。
* すぐに使用できます。

### Paused 状態の Sandbox を clone する

**clone プロセス中:**

origin sandbox が paused 状態の場合:

* clone プロセスによって origin sandbox が start されることはありません。
* origin sandbox は paused 状態のままです。

**clone 完了後:**

**Origin Sandbox:**

* 既存の pause レコードはクリアされません。
* 新しい snapshot template レコードが生成されます（この snapshot template を削除するには、まず origin sandbox と clone された sandbox の両方を terminate する必要があります）。

**New Sandbox:**

* ステータスは running です。
* すぐに使用できます。

### New Sandbox の属性継承ルール

| 属性          | 継承  |
| ----------- | --- |
| auto resume | はい  |
| auto pause  | いいえ |

## パラメーターの説明

* `count`: clone する sandbox インスタンスの数。最小値は 1 で、最大値はプラットフォームの同時実行 sandbox インスタンス制限を超えてはなりません（参照: [Sandbox Quota Limit](/docs/ja/guides/sandbox-quota-limit)）。
* `strict`: `count` パラメーターで指定された数に厳密に従って clone するかどうか。デフォルトは false です。
  * `true`: 正常に clone されたインスタンス数が `count` より少ない場合、clone 失敗が返されます。正常に作成された sandbox は自動的に解放されます。
  * `false`: 正常に clone された sandbox インスタンスの実際の数を返します。
* `timeout`(`timeoutMs`): sandbox インスタンスの clone に対するタイムアウト。
  * 指定されていない場合:
    * origin sandbox が running 状態の場合、そのタイムアウト設定を継承します。
    * origin sandbox が paused 状態の場合、デフォルト値の 5 分が使用されます。

## 戻り値

clone 操作が成功すると、次のプロパティを含むオブジェクトが返されます。

| プロパティ                  | 説明                                     |
| ---------------------- | -------------------------------------- |
| `sandboxes`            | 正常に clone された sandbox インスタンスのリスト       |
| `count`                | 正常に clone された sandbox の数               |
| `snapshot_template_id` | clone プロセス中に生成された snapshot template ID |

## コード例

<CodeGroup>
  ```python Python icon="python" theme={"system"}
  from novita_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={"system"}
  import { Sandbox } from '@novita-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>

さらに、Novita Sandbox CLI を使用して指定した sandbox インスタンスを clone することもできます。

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