# 快速开始
<subtitle>开始使用自定义沙箱模板</subtitle>

UCloud Sandbox 模板允许您定义自定义沙箱环境。您可以定义基础镜像、环境变量、复制文件、运行命令，以及设置 [启动命令](/docs/agent-sandbox/template/start-ready-command.md#启动命令)，该启动命令会在模板构建期间运行并被捕获到快照中——这样当您从该模板创建沙箱时，进程**已经在运行**。这为您的用户提供了完全配置好的沙箱，运行中的进程随时可用，启动时间为零。

创建新模板有两种方式：
- 使用 CLI
- 使用 SDK 手动定义

## 使用 CLI

您可以使用 UCloud Sandbox CLI 创建新模板。

### 安装 UCloud Sandbox CLI

```bash
curl -sS https://raw.githubusercontent.com/ucloud/ucloud-sandbox-cli/main/install.sh | sh
```

### 初始化新模板

```bash
ucloud-sandbox-cli template init
```

### 按照提示操作

按照提示创建新模板。

### 完成

检查生成的 `template.dockerfile` 和 `ucloud-template.json` 文件，编辑 Dockerfile 定义您的环境，然后使用以下命令构建：

```bash
ucloud-sandbox-cli template build <模板名称>
```

## 使用 SDK 手动定义

### 安装 Python SDK

```bash
pip install ucloud-sandbox
```

创建 `.env` 文件

```bash
UCLOUD_SANDBOX_API_KEY=your_api_key
```

### 创建新的模板定义文件

创建一个模板文件，内容如下：

```python
# template.py
from ucloud_sandbox import Template, wait_for_timeout

template = (
    Template()
    .from_base_image()
    .set_envs(
        {
            "HELLO": "Hello, World!",
        }
    )
    .set_start_cmd("echo $HELLO", wait_for_timeout(5_000)))
```

### 创建构建脚本

```python
# build.py
from dotenv import load_dotenv
from ucloud_sandbox import Template, default_build_logger
from template import template

load_dotenv()

if __name__ == '__main__':
    Template.build(
        template,
        'my-template',
        cpu_count=1,
        memory_mb=1024,
        on_build_logs=default_build_logger(),
    )
```

### 构建模板

```bash
python build.py
```

## 从模板创建新沙箱

```python
from ucloud_sandbox import Sandbox

# 从模板创建沙箱
sandbox = Sandbox.create("my-template")
```

> 模板名称是可以用来创建新沙箱的标识符。

## 构建限制

模板构建受以下限制：

- **最大构建时长**：构建最多可运行 **1 小时**。如果构建超过此时间，将被终止。
- **每次构建的最大 vCPU 数**：默认为 8 vCPU，企业版可定制。
- **每次构建的最大内存**：默认为 8 GB，企业版可定制。
- **每次构建的最大磁盘大小**：默认为 10 GB，企业版可定制。
- **并发构建数**：默认为 20，企业版可定制。

如需更高限制，请联系客服。

## 计费说明

模板构建和存储会产生费用。每个用户享有 **60GB 免费存储额度**，超出部分按实际使用量计费。

> 详细计费规则请参阅 [计费说明](/docs/agent-sandbox/product/fee.md)。