Skip to content

沙盒 ​

沙盒是一台独立的虚拟机,通过 API 来操作:在里面执行命令、读写文件。外部连不进来。从可用开始按秒计费,到删除为止,最低 60 秒。

key 的「用途」里要有「沙盒」。你也可以在控制台的「沙盒」页创建和使用沙盒。

创建沙盒 ​

先请求 GET https://cloud.theyilabs.com/v1/compute/classes,从 classes 中选择可用规格。列表为空时,算力暂不可创建,请先使用模型 API。以下创建示例需要可用规格和足够的可用余额。

sh
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、内存、磁盘和每小时价格。
archamd64(默认)或 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,也可以自己选地区和具体机型。

  1. GET https://cloud.theyilabs.com/v1/compute/regions 列出开放的地区(新加坡、东京、美国(爱荷华)、伦敦、瑞典、斯德哥尔摩)和每个地区的机型系列及其架构。
  2. GET https://cloud.theyilabs.com/v1/compute/machine-types?region=tokyo&family=n2 列出该地区这个系列的机型:vCPU、内存、磁盘、每小时价格和停机保留费用。
  3. 创建时传 machine_type 和 region,不传 class:
sh
-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。

执行命令 ​

sh
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 一致:

text
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 发送:

sh
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.txt
  • path:文件放在哪里。相对路径从 /workspace 算起。目录必须已经存在,否则返回 400 并写明是哪个目录(先用 mkdir -p 建好)。
  • offset:这一块从文件的第几个字节开始写。
  • truncate=true:先清空文件。第一块用它,后面的块用 truncate=false 加上正确的 offset。

返回 204。

下载用 GET,带一个不超过 64 KiB 的 Range 请求头:

sh
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。

沙盒的磁盘随沙盒一起销毁。需要保留的文件,在它结束之前下载下来。

删除 ​

sh
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 个沙盒,最新的在前,包括已删除的。