沙盒
沙盒是一台独立的虚拟机,通过 API 来操作:在里面执行命令、读写文件。外部连不进来。从可用开始按秒计费,到删除为止,最低 60 秒。
key 的「用途」里要有「沙盒」。你也可以在控制台的「沙盒」页创建和使用沙盒。
创建沙盒
先请求 GET https://cloud.theyilabs.com/v1/compute/classes,从 classes 中选择可用规格。列表为空时,算力暂不可创建,请先使用模型 API。以下创建示例需要可用规格和足够的可用余额。
RETRY_KEY=$(uuidgen)
curl https://cloud.theyilabs.com/v1/sandboxes \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $RETRY_KEY" \
-d '{"class":"small","timeout_s":1800,"idle_timeout_s":300}'同一次操作重试时复用这个 RETRY_KEY 和请求体;下一次新建资源时重新生成。
| 字段 | 取值 |
|---|---|
class | 必填。GET /v1/compute/classes 里某个规格的 id。那里列出每种规格的 vCPU、内存、磁盘和每小时价格。 |
arch | amd64(默认)或 arm64。可用的架构见 GET /v1/compute/classes。 |
pool | 可选:pool-1、pool-2 或 pool-3。不填由 Yi Cloud 选。现在开放的资源池见 GET /v1/compute/classes 里的 pools。旧的 cloud 字段已删除,传了返回 400。 |
timeout_s | 沙盒可用之后最多运行多少秒。60 到 604,800,默认 3,600。你的信任档位可能限制得更短,见配额与网络。 |
idle_timeout_s | 连续这么多秒没有活动就删除沙盒。60 到 86,400,默认 300。 |
metadata | 可选。最多 20 对字符串,给你自己用。键最长 60 个字符,值最长 200 个。 |
创建时要带 Idempotency-Key 请求头。如果请求在网络上失败了,用同一个 key 和同样的请求体再发一次,拿到的是同一个沙盒,不会多建一个。见 API 参考。
返回 202 和这个沙盒,id 以 sb_ 开头。
选地区和机型
不用 class,也可以自己选地区和具体机型。
GET https://cloud.theyilabs.com/v1/compute/regions列出开放的地区(新加坡、东京、美国(爱荷华)、伦敦、瑞典、斯德哥尔摩)和每个地区的机型系列及其架构。GET https://cloud.theyilabs.com/v1/compute/machine-types?region=tokyo&family=n2列出该地区这个系列的机型:vCPU、内存、磁盘、每小时价格和停机保留费用。- 创建时传
machine_type和region,不传class:
-d '{"machine_type":"n2-standard-4","region":"tokyo","timeout_s":1800,"idle_timeout_s":300}'架构由机型系列决定,可以不传 arch;传了但不一致会返回 400。L4 系列(g2-standard-*)带一张 NVIDIA L4,需要 GPU 邀请。这样创建的资源会返回 region 和 machine_type。
状态
state | 含义 |
|---|---|
requested、provisioning、booting | 正在启动。 |
ready | 可以执行命令和读写文件。 |
busy | 至少有一条命令在运行。 |
deleting | 正在删除。 |
deleted | 已删除。如果不是你删的,error_code 会说明原因。 |
failed | 一直没有变成可用。不收费。 |
反复查询 GET /v1/sandboxes/{id},直到 state 变成 ready。10 分钟内没有变成可用的沙盒会被删除,状态为 failed。
执行命令
curl https://cloud.theyilabs.com/v1/sandboxes/$SANDBOX/exec \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cmd":"python3 --version","timeout_s":60}'| 字段 | 取值 |
|---|---|
cmd | 必填。一行 shell 命令,最长 65,536 个字符。 |
cwd | 工作目录,默认 /workspace。 |
env | 额外的环境变量,写成 {"NAME": "value"}。每个值最长 4,096 个字符,总共大约 16,000 个字符。 |
timeout_s | 命令最多运行多少秒。1 到 3,600,默认 60。 |
stream | 设为 true,用 server-sent events 返回,而不是一次性返回 JSON。 |
不用流式时返回 {"stdout": "…", "stderr": "…", "exit_code": 0}。输出超过 1 MiB 时,命令会被停止,返回 400 invalid_request。输出多的命令请用 stream: true。
用流式时,每个事件的名字和数据里的 type 一致:
event: stdout
data: {"type":"stdout","text":"Python 3…\n"}
event: exit
data: {"type":"exit","exit_code":0}stderr 事件和 stdout 一样。命令没法执行时,流会以一个带 code 的 error 事件结束。
几条规则:
- 一个沙盒同时最多跑 4 条命令,第 5 条返回
409 conflict。 - 命令不会被自动重试,所以不会意外执行两次。如果调用在网络上失败了,先查一下沙盒的状态,再决定要不要重新执行。
- 命令到了自己的
timeout_s会结束,沙盒的运行时长到了也会结束。到timeout_s被停掉的命令返回exit_code: -1和timed_out: true。 - 如果命令因为 Yi Cloud 自身的问题失败(不是你的命令出错),返回
503 upstream_unavailable,消息里写明原因。
沙盒里有什么
命令以普通用户身份运行,没有 sudo,工作目录是 /workspace。这个用户能写 /workspace、自己的主目录 /home/pwc 和 /tmp,文件系统的其余部分只读。镜像是 Ubuntu 24.04 LTS,带 git、curl、build-essential、Python 3 和 Node.js。
出站连接只允许 HTTP 和 HTTPS。外部连不进沙盒。见配额与网络。
文件
文件按最多 64 KiB 一块传输。
上传用 PUT,内容以 application/octet-stream 发送:
curl -X PUT "https://cloud.theyilabs.com/v1/sandboxes/$SANDBOX/files?path=/workspace/hello.txt&offset=0&truncate=true" \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @hello.txtpath:文件放在哪里。相对路径从/workspace算起。目录必须已经存在,否则返回400并写明是哪个目录(先用mkdir -p建好)。offset:这一块从文件的第几个字节开始写。truncate=true:先清空文件。第一块用它,后面的块用truncate=false加上正确的offset。
返回 204。
下载用 GET,带一个不超过 64 KiB 的 Range 请求头:
curl "https://cloud.theyilabs.com/v1/sandboxes/$SANDBOX/files?path=/workspace/hello.txt" \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Range: bytes=0-65535" \
-o hello.txt不带 Range 时,返回前 64 KiB。Content-Range 响应头的最后是文件的总大小,据此可以知道还要取几块。
运行时长和空闲回收
下面任何一件事先发生,沙盒就会被删除:
- 你删除了它。
- 从可用开始,已经过了
timeout_s。 - 连续
idle_timeout_s秒没有命令、文件操作或 keepalive。有命令在运行时不算空闲。 - 它超过 2 分钟没有向 Yi Cloud 报告。
想让空闲的沙盒留着,调用 POST /v1/sandboxes/{id}/keepalive。它会重新计算空闲时间,但不会延长 timeout_s。
沙盒的磁盘随沙盒一起销毁。需要保留的文件,在它结束之前下载下来。
删除
curl -X DELETE https://cloud.theyilabs.com/v1/sandboxes/$SANDBOX \
-H "Authorization: Bearer $YI_CLOUD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"返回 202,状态先变成 deleting,再变成 deleted。已经是 deleted 的沙盒,再删一次只会返回它本身。还在 deleting 时,用新的 Idempotency-Key 再删会得到 409 conflict。
费用
- 创建时,从余额里预扣「每小时价格 ×
timeout_s」。 - 结束时,从可用开始按秒计费,到确认删除为止,最低 60 秒,最多
timeout_s。预扣剩下的部分释放。 - 一直没有变成可用,不收费。
- 你发的命令全都因为 Yi Cloud 的问题失败、一条都没执行,也不收费。
timeout_s 越短,预扣越小。单个沙盒的回执在 GET /v1/sandboxes/{id}/receipt,返回 JSON,加 ?format=csv 返回 CSV。见计费与回执。
列表
GET /v1/sandboxes 返回你工作区最近的 200 个沙盒,最新的在前,包括已删除的。