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

Linux 和 macOS 使用：

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

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

Windows 在 PowerShell 中使用：

Invoke-RestMethod https://raw.githubusercontent.com/ucloud/ucloud-sandbox-cli/main/install.ps1 | Invoke-Expression

Windows 安装脚本会自动选择 amd64 或 arm64 版本，默认安装到%LOCALAPPDATA%\Programs\ucloud-sandbox-cli，并将该目录加入用户PATH。

更新 CLI

从v1.3.4开始，CLI 可以自我更新，不需要重新执行安装脚本：

ucloud-sandbox-cli update

该命令会查询 GitHub 上的最新 Release，打印当前版本、最新版本和安装路径，等您输入y确认后，再下载与当前系统和架构匹配的二进制，校验 SHA256 并替换当前程序。

如果只想检查是否有新版本，不做任何改动，使用--dry-run：

ucloud-sandbox-cli update --dry-run

在脚本或 CI 中可以用-y跳过确认：

ucloud-sandbox-cli update -y

几点说明：

如果 CLI 安装在/usr/local/bin等需要管理员权限的目录，请使用sudo ucloud-sandbox-cli update。
v1.3.3及以前的版本没有update命令，请重新执行上面的安装脚本来升级。
该命令使用 GitHub 的匿名 API 查询版本，如果遇到限流报错，可以设置GITHUB_TOKEN环境变量后重试。

身份认证与配置

认证与配置相关的命令都在 auth 下面。

环境注入

CLI 会优先读取环境变量中的 API Key、地域和其他配置。

export UCLOUD_SANDBOX_API_KEY=your_api_key
export UCLOUD_SANDBOX_REGION=region

如需使用 HTTP 而不是 HTTPS 连接控制面和沙箱，可通过环境变量启用 insecure_http：

export UCLOUD_SANDBOX_INSECURE_HTTP=true

也可以在 ~/.ucloud-sandbox-cli/config.json 中持久化该配置：

{
  "insecure_http": true
}

查看当前生效的配置（API Key 和镜像仓库密码会自动脱敏）：

ucloud-sandbox-cli auth config

直接用编辑器打开配置文件，编辑器取自 $EDITOR，未设置时用 vim，也可以在 -e 后面指定：

ucloud-sandbox-cli auth config -e
ucloud-sandbox-cli auth config -e nano

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

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

持久化认证

配置持久化认证：

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

删除持久化认证：

ucloud-sandbox-cli auth logout

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

切换地域

快速选择并切换地域：

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

镜像仓库凭据

构建模板时如果 base image 来自私有仓库，需要先登录该仓库。凭据按仓库域名保存，可以同时配置多个仓库：

# 省略域名时使用 docker.io
ucloud-sandbox-cli auth registry login
ucloud-sandbox-cli auth registry login uhub.service.ucloud.cn

命令会提示输入用户名和密码（密码输入时不回显）。删除某个仓库的凭据：

ucloud-sandbox-cli auth registry logout uhub.service.ucloud.cn

template build 会解析 Dockerfile 里 FROM 的镜像，按其仓库域名自动选用对应凭据；没有匹配条目时不带鉴权，公共镜像无需配置。

凭据在配置文件中的形状如下，也可以通过 UCLOUD_SANDBOX_REGISTRIES 环境变量以同样的 JSON 传入：

{
  "registries": {
    "uhub.service.ucloud.cn": {
      "username": "<username>",
      "password": "<password>"
    }
  }
}

沙箱运行管理

创建与连接

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

# 使用内置模板创建沙箱
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

创建沙箱时可以按 Volume 名称挂载一个或多个持久化 Volume：

ucloud-sandbox-cli sandbox create base --mount <volume-name>:/data
ucloud-sandbox-cli sandbox create base \
  --mount <volume-name-1>:/data \
  --mount <volume-name-2>:/cache

开启自动暂停/自动恢复后，沙箱在超时被暂停后，下次访问时会自动恢复运行：

ucloud-sandbox-cli sandbox create base --auto-pause --auto-resume --detach

创建成功后，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

执行命令

不进入交互终端，直接在沙箱里跑一条命令：

ucloud-sandbox-cli sandbox exec <sandbox-id> "python --version"

# CLI 自己的参数要写在沙箱 ID 前面
ucloud-sandbox-cli sandbox exec -u root <sandbox-id> "ls -la /root"

端口地址

拿到沙箱内某个端口对外的访问地址：

ucloud-sandbox-cli sandbox host <sandbox-id> 3000

# 输出完整 URL 而不是 host:port
ucloud-sandbox-cli sandbox host <sandbox-id> 3000 --url

暂停与复制

暂停沙箱并保留状态，下次连接时恢复：

ucloud-sandbox-cli sandbox pause <sandbox-id>

# 只保留文件系统、不保留内存（恢复时冷启动）
ucloud-sandbox-cli sandbox pause <sandbox-id> --memory=false

从一个运行中的沙箱复制出若干个副本，所有副本共用一次快照：

ucloud-sandbox-cli sandbox fork <sandbox-id>
ucloud-sandbox-cli sandbox fork <sandbox-id> --count 3 --timeout 3600

强制关停 (Kill)

立即释放沙箱资源：

# 关停特定 ID
ucloud-sandbox-cli sandbox kill <sandbox-id>

# 关停所有活跃沙箱，会先要求确认
ucloud-sandbox-cli sandbox kill --all

# 按状态过滤，并限制本次最多关停多少个
ucloud-sandbox-cli sandbox kill --all --state running --limit 10 -y

监控与日志

实时洞察沙箱运行状态：

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

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

# 指定时间区间，参数是 Unix 时间戳（秒）
ucloud-sandbox-cli sandbox metrics <sandbox-id> --start $(date -d '1 hour ago' +%s)

查看沙箱日志：

ucloud-sandbox-cli sandbox logs <sandbox-id>
ucloud-sandbox-cli sandbox logs <sandbox-id> --level warn
ucloud-sandbox-cli sandbox logs <sandbox-id> -f

文件管理

文件相关命令在 sandbox fs 下面，每个命令都支持 -u/--user 指定以哪个用户执行：

# 浏览
ucloud-sandbox-cli sandbox fs ls <sandbox-id> /home/user
ucloud-sandbox-cli sandbox fs ls <sandbox-id> /home/user -d 2 -f json

# 读取
ucloud-sandbox-cli sandbox fs cat <sandbox-id> /home/user/app.py

# 创建目录、移动、删除
ucloud-sandbox-cli sandbox fs mkdir <sandbox-id> /home/user/app
ucloud-sandbox-cli sandbox fs mv <sandbox-id> /home/user/old.txt /home/user/new.txt
ucloud-sandbox-cli sandbox fs rm <sandbox-id> /home/user/obsolete.txt

上传和下载使用 fs cp，远端一侧写成 <sandbox-id>:<path>，源和目标里必须恰好有一个远端：

# 上传
ucloud-sandbox-cli sandbox fs cp ./index.html <sandbox-id>:/home/user/app/index.html

# 上传到目录并保留文件名（远端路径以 / 结尾）
ucloud-sandbox-cli sandbox fs cp ./index.html <sandbox-id>:/home/user/app/

# 下载
ucloud-sandbox-cli sandbox fs cp <sandbox-id>:/home/user/app/out.txt ./out.txt

Snapshot 管理

把沙箱当前状态保存为快照：

ucloud-sandbox-cli snapshot create <sandbox-id>

# 指定名称；名称已存在时会作为新的一次构建挂到该快照下
ucloud-sandbox-cli snapshot create <sandbox-id> -n nightly

列出和删除快照：

ucloud-sandbox-cli snapshot list
ucloud-sandbox-cli snapshot list -s <sandbox-id>
ucloud-sandbox-cli snapshot delete <snapshot-id...>

快照 ID 可以直接当作模板传给 sandbox create，从快照启动新沙箱：

ucloud-sandbox-cli sandbox create <snapshot-id>

Secret 管理

Secret 的值是只写的，创建后不会再被返回：

# 不带 --value 时会提示输入，输入过程不回显
ucloud-sandbox-cli secret create openai-key
ucloud-sandbox-cli secret create openai-key --value "<value>"

# 从标准输入读取，适合多行内容
cat private.pem | ucloud-sandbox-cli secret create deploy-key --value-stdin

更新、查看和删除：

ucloud-sandbox-cli secret update openai-key
ucloud-sandbox-cli secret get openai-key
ucloud-sandbox-cli secret list
ucloud-sandbox-cli secret delete openai-key

在创建沙箱时通过 --network-rules 引用 Secret，平台会在出站请求中替换为真实值：

ucloud-sandbox-cli sandbox create base \
  --network-rules '{"api.example.com": {"X-API-KEY": "${openai-key}"}}'

Volume 管理

创建持久化 Volume：

ucloud-sandbox-cli vol create <name>

列出 Volume：

ucloud-sandbox-cli vol list
ucloud-sandbox-cli vol list --format json

查看单个 Volume：

ucloud-sandbox-cli vol get <volume-id>

删除一个或多个 Volume：

ucloud-sandbox-cli vol delete <volume-id...>

模板构建管理

初始化模板项目

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

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

生成的 ucloud-template.json 记录模板名、CPU、内存和 Dockerfile 文件名，template build 在命令行没给对应参数时会从这里取值。

构建模板

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

构建模板：

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

常用构建参数：

# 指定资源；内存必须是偶数 MB
ucloud-sandbox-cli tpl build my-custom-env --cpu-count 2 --memory-mb 2048

# 跳过缓存，强制重跑每一步
ucloud-sandbox-cli tpl build my-custom-env --no-cache

# 打标签，并在构建完成后直接公开
ucloud-sandbox-cli tpl build my-custom-env -t v1 -t latest --publish

# 指定启动命令和就绪探针，两者必须一起给
ucloud-sandbox-cli tpl build my-custom-env \
  --cmd "python app.py" \
  --ready-cmd "curl -f http://localhost:8000/health"

可使用 --level 控制构建日志的最低等级（debug、info、warn 或 error），默认为 info：

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

构建上下文就是 Dockerfile 所在的目录，COPY 的源路径相对于该目录解析。--dockerfile 指向该目录之外时命令会直接报错，而不是用错误的文件构建。

查看模板与构建日志

ucloud-sandbox-cli tpl list
ucloud-sandbox-cli tpl get <template-id>
ucloud-sandbox-cli tpl logs <template-id> <build-id>

发布模板

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

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

取消公开：

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

模板标签

标签指向模板的某一次构建，可以用来固定版本：

ucloud-sandbox-cli tpl tag list my-custom-env
ucloud-sandbox-cli tpl tag assign my-custom-env:latest v1
ucloud-sandbox-cli tpl tag remove my-custom-env v1

删除模板

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

# 从列表中交互选择
ucloud-sandbox-cli tpl delete --select

输出格式与分页

所有列表类命令（sandbox list、volume list、secret list、snapshot list、template list、template tag list、sandbox fs ls）都支持同一组参数：

-f, --format string   输出格式，pretty 或 json（默认 pretty）
-p, --page int        页码（默认 1）
-l, --limit int       每页条数，0 表示全部

需要在脚本里解析结果时用 -f json。

典型工作流示例

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

Name		Name	Last commit message	Last commit date
.github		.github
cmd		cmd
internal		internal
skills		skills
submodules		submodules
.gitignore		.gitignore
.gitmodules		.gitmodules
CLAUDE.md		CLAUDE.md
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
install.ps1		install.ps1
install.sh		install.sh
main.go		main.go

Navigation Menu

Repository files navigation

UCloud Sandbox CLI

安装指南

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

安装 CLI

更新 CLI

身份认证与配置

环境注入

持久化认证

切换地域

镜像仓库凭据

沙箱运行管理

创建与连接

连接现有沙箱

列表查询

执行命令

端口地址

暂停与复制

强制关停 (Kill)

监控与日志

文件管理

Snapshot 管理

Secret 管理

Volume 管理

模板构建管理

初始化模板项目

构建模板

查看模板与构建日志

发布模板

模板标签

删除模板

输出格式与分页

典型工作流示例

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

UCloud Sandbox CLI

安装指南

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

安装 CLI

更新 CLI

身份认证与配置

环境注入

持久化认证

切换地域

镜像仓库凭据

沙箱运行管理

创建与连接

连接现有沙箱

列表查询

执行命令

端口地址

暂停与复制

强制关停 (Kill)

监控与日志

文件管理

Snapshot 管理

Secret 管理

Volume 管理

模板构建管理

初始化模板项目

构建模板

查看模板与构建日志

发布模板

模板标签

删除模板

输出格式与分页

典型工作流示例

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages