UCloud Sandbox CLI

强大的命令行工具，用于本地管理沙箱生命周期、构建模板及执行运维任务。

UCloud Sandbox CLI 是开发者最常用的工具之一。它不仅可以帮助您快速初始化和构建沙箱模板，还可以实时查看沙箱监控指标以及执行批量操作。

安装指南

卸载旧的基于npm的CLI（可选）

在v1.0及以前的版本中，我们的CLI是基于npm构建和分发的，在后续版本中，我们改为了手动执行安装脚本。

如果您安装过v1.0.x的ucloud-sandbox-cli，请先使用下面的命令进行卸载：

npm uninstall -g @ucloud-sdks/ucloud-sandbox-cli

如果您之前从未安装过ucloud-sandbox-cli，或者没有使用npm安装过，可以跳过这一步。

安装CLI

使用下面的命令安装CLI：

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

安装脚本会要求您确认安装路径（默认为/usr/local/bin），直接输入回车可以确认安装，或者您也可以手动输入安装路径。注意请确保安装路径在您的$PATH下面以可以直接使用命令行。

身份认证与配置

环境注入

CLI 会优先读取环境变量中的 API Key和地域。

export UCLOUD_SANDBOX_API_KEY=your_api_key
export UCLOUD_SANDBOX_REGION=region

API key可以从星图平台的密钥管理获取。

可用地域可以参考：切换地域。

持久化认证

配置持久化认证：

# 这个命令会要求您输入API key并选择默认地域
ucloud-sandbox-cli login

删除持久化认证：

ucloud-sandbox-cli logout

在持久化认证生效的情况下，仍然可以使用环境变量来替换API key和地域。

切换地域

快速选择并切换地域：

# 会列出当前可用的地域供您选择
ucloud-sandbox-cli region

沙箱运行管理

创建与连接

快速创建沙箱并进入交互式终端：

# 使用内置模板创建沙箱
ucloud-sandbox-cli sandbox create [template]
# 简写：ucloud-sandbox-cli sbx cr [template]

内置模板：

# 代码解释器 - 预装 Python 和数据科学库
ucloud-sandbox-cli sandbox create code-interpreter-v1
 
# 桌面环境 - 支持图形化应用和浏览器
ucloud-sandbox-cli sandbox create desktop
 
# 基础环境 - 轻量级 Linux 环境
ucloud-sandbox-cli sandbox create base

创建成功后，CLI 会自动连接终端，您可以像操作本地 Shell 一样执行命令。按Ctrl+D或输入exit退出连接(沙箱继续运行)。

连接现有沙箱

重新连接到已运行的沙箱实例：

ucloud-sandbox-cli sandbox connect <sandbox-id>
# 简写：ucloud-sandbox-cli sbx connect <sandbox-id>

列表查询

查看名下所有活跃（运行或暂停）的沙箱实例：

ucloud-sandbox-cli sandbox list
# 简写：ucloud-sandbox-cli sandbox ls

强制关停 (Kill)

立即释放沙箱资源：

# 关停特定 ID
ucloud-sandbox-cli sandbox kill <sandbox-id>
 
# 关停所有活跃沙箱
ucloud-sandbox-cli sandbox kill --all

监控

实时洞察沙箱运行状态：

# 查看资源占用指标 (CPU/RAM/Disk)
ucloud-sandbox-cli sandbox metrics <sandbox-id>

# 持续查看指标
ucloud-sandbox-cli sandbox metrics <sandbox-id> -w

模板构建管理

初始化模板项目

创建一个标准化的模板开发目录：

ucloud-sandbox-cli tpl init my-custom-env --cpu <cpu> --memory <memory>
cd my-custom-env

构建模板

在上面的my-custom-env里面，您可以看到template.dockerfile文件，您需要编辑这个文件，输入RUN命令以定义构建模板需要的命令。

构建模板：

ucloud-sandbox-cli tpl build my-custom-env

发布模板

默认情况下，模板只能由您当前的项目访问，如果您需要其他人也能使用模板，需要公开：

ucloud-sandbox-cli tpl publish <template-id>

取消公开：

ucloud-sandbox-cli tpl publish --unpublish <template-id>

典型工作流示例

1. 准备环境：ucloud-sandbox-cli login
2. 创建模板：ucloud-sandbox-cli template init -> 编写 Dockerfile
3. 业务接入：在 SDK 中使用 Sandbox.create(template='my-agent-env')
4. 资源回收：ucloud-sandbox-cli sandbox kill --all