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

# 沙箱模板

通过沙箱模板可以自定义您的沙箱环境。

<Tip>
  PPIO Agent 沙箱服务已经内置一些公共模板方便您开箱即用，您可以在 <Link href="https://ppio.com/sandbox/console/template" target="_blank">控制台</Link> 找到这些公共模板。
</Tip>

我们通过您定义的 `ppio.Dockerfile` 来创建一个新的沙箱模板，并返回模板 ID 用于创建沙箱。详见下方教程。

## 如何创建自定义沙箱

### 1. 安装 PPIO 沙箱命令行工具

请参考 <Link href="/sandbox/cli">教程</Link> 来进行安装，并完成 <Link href="/sandbox/cli-auth">认证</Link>。

### 2. 初始化沙箱模板

以下命令将在当前目录下创建一个基础 `ppio.Dockerfile` 文件。

<CodeGroup isTerminalCommand>
  ```bash Bash icon="terminal" theme={null}
  ppio-sandbox-cli template init
  ```
</CodeGroup>

### 3. 自定义`ppio.Dockerfile`

现在您可以通过编辑 `ppio.Dockerfile` 文件来自定义您的沙箱模板。

<CodeGroup title="ppio.Dockerfile">
  ```dockerfile ppio.Dockerfile icon="docker" theme={null}
  # 本文档示例使用这个基础镜像，请保持不变
  FROM image.ppinfra.com/sandbox/code-interpreter:latest
  # 安装一些 python 包
  RUN pip install cowsay
  ```
</CodeGroup>

### 4. 构建沙箱模板

现在您可以开始构建沙箱模板。下面命令会调用本地 Docker 工具来构建镜像，然后将其推送到 PPIO 的远程镜像仓库。

我们会在云端将 Docker 镜像转换为 firecracker 的 microVM 镜像，后续会基于该镜像来启动沙箱实例。

<Tip>
  下面通过 `-c` 参数指定了启动命令，有关启动命令的用法请参考[这里](/sandbox/sandbox-template-start-cmd)。
</Tip>

<CodeGroup isTerminalCommand>
  ```bash Bash icon="terminal" theme={null}
  ppio-sandbox-cli template build -c "/root/.jupyter/start-up.sh"
  ```
</CodeGroup>

这个过程需要一些时间。最后，您会得到模板 ID，后面我们使用它通过 SDK 创建沙箱。

### 5. 启动您的自定义沙箱

现在您可以使用上一步获得的模板 ID 来创建沙箱。

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  import { Sandbox } from 'ppio-sandbox/code-interpreter'

  // 在上一步创建的模板 ID 
  const templateID = 'id-of-your-template'

  // 将模板 ID 传递给 `Sandbox.create` 方法
  const sandbox = await Sandbox.create(templateID)

  // 模板已安装 cowsay，可以直接使用它
  const result = await sandbox.runCode(`
  import cowsay
  cowsay.say('Hello!')
  `)

  console.log(result)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox

  # 在上一步创建的模板 ID 
  template_id = 'id-of-your-template'

  # 将模板 ID 传递给 `Sandbox.create` 方法
  sandbox = Sandbox.create(template_id)

  # 模板已安装 cowsay，可以直接使用它
  result = sandbox.run_code("""
  import cowsay
  cowsay.say('Hello!')""")

  print(result)

  sandbox.kill()
  ```
</CodeGroup>

## 工作原理

每次构建一个沙箱模板时，我们都会基于 [`ppio.Dockerfile`](#3-自定义ppio-dockerfile) 文件创建一个容器。我们会提取容器的文件系统，进行配置（例如安装所需依赖项等），然后启动一个沙箱实例。

接下来我们会：

1. 获取正在运行的沙箱实例。
2. 执行 <Link href="/sandbox/sandbox-template-start-cmd">启动命令</Link>。仅当您指定了 “启动命令” 则会执行该步骤，否则跳过。
3. 等待就绪（如果指定了 “启动命令”，则默认等待 20 秒，否则立即就绪）。
4. 对当前正在运行的沙箱进行快照并使其准备好供后续创建沙箱时使用。

我们将最后产生的 “沙箱快照” 称为**沙箱模板**。

<Note title="沙箱快照">
  我们将整个沙箱的文件系统连同所有正在运行的进程以一种 “稍后可快速加载” 的方式进行序列化和保存。

  这使我们能够在稍后的任何时候在几百毫秒内加载沙箱，加载后，所有进程处于运行状态，并且文件系统完全保持原样。
</Note>