> ## 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>;
  }
};

<SandboxBetaVersionWarning />

## 名词定义

* **提交（Commit）**：提交操作是指将沙箱当前状态保存成模板的操作，提交后将会产生新的模板（类型为快照模板）。
* **原始沙箱（Origin Sandbox）**：被提交的沙箱实例。
* **快照模板（Snapshot Template）**：提交操作后生成的模板。

## 功能描述

### 提交运行中（Running）状态的沙箱

**提交过程中：**

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

**提交完成后：**

**原始沙箱：**

* 原有的暂停记录会被清除，但是随即以当前状态生成一条新的暂停记录；
* 原始沙箱继续运行；
* 产生一个新的模板记录。

### 提交已暂停（Paused）状态的沙箱

**提交过程中：**

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

**提交完成后：**

**原始沙箱：**

* 原有的暂停记录不会被清除；
* 产生一个新的模板记录。

## 参数说明

| 参数           | 类型       | 必填 | 说明           |
| ------------ | -------- | -- | ------------ |
| `sandbox_id` | `string` | 是  | 要提交的沙箱实例 ID  |
| `alias`      | `string` | 否  | 为生成的模板设置一个别名 |

## 返回值说明

提交操作成功后返回 `Template` 对象信息

## 代码示例

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

  # Commit an existing sandbox by ID to create a template snapshot
  # sandbox_id: str - Required. The ID of the sandbox to commit
  # alias: Optional[str] - Optional alias name for the created template
  # Note: Default timeout is 10 minutes for commit operation
  template = Sandbox.commit(
      sandbox_id="existing-sandbox-id",
      alias="my-template-alias"
  )
  print(f"Template ID: {template.template_id}")
  print(f"Build ID: {template.build_id}")
  ```

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

  // Commit an existing sandbox by ID to create a template snapshot
  // sandboxId: string - Required. The ID of the sandbox to commit
  // opts?: { alias?: string } - Optional commit options
  const template = await Sandbox.commit('existing-sandbox-id', {
    alias: 'my-template-alias'
  })
  console.log(`Template ID: ${template.templateId}`)
  console.log(`Build ID: ${template.buildId}`)
  ```
</CodeGroup>

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

```bash Bash icon="terminal" theme={null}
# Basic commit - creates a template snapshot from a sandbox
ppio-sandbox-cli sandbox commit <sandboxID>

# Commit with alias - assign a friendly name to the template
ppio-sandbox-cli sandbox commit <sandboxID> --alias my-template-alias

```