创建沙箱

沙箱可以运行命令时返回，status 为 running。如果节点还没有构建过该镜像，则立即返回，status 为 starting；需要该沙箱的调用会等待它，如果镜像无法拉取，沙箱会变为 failed。

所需权限范围：write。

POST

https://api.glac.ai/v1/sandboxes

授权

apiKeyHTTPrequired

请求头参数

X-Request-Idoptionalstring
调用方为请求自定的 id：1 到 64 个字母、数字、.、_ 和 -。节点随后以它标识该请求：出现在响应的 X-Request-Id、错误响应体和节点日志中。其他任何值都会被忽略，由节点生成 id。

pattern: ^[A-Za-z0-9._\-]{1,64}$
Idempotency-Keyoptionalstring
让请求可以安全地重发。见简介中的“Idempotency-Key”一节。

maxLength: 255 · minLength: 1

请求体JSON可选

startoptionalboolean
true：虚拟机启动时运行镜像自己的启动命令（ENTRYPOINT 和 CMD）；false：不启动任何东西，无论镜像的标签要求什么。只要给出了（start、start_command 和 ready 中的任何一个），就只以它为准：不读取镜像的标签 sbx.start 和 sbx.ready。沙箱从用这些设置和 env 构建的模板创建（同一镜像的两种设置就是两个模板；某种设置的第一个沙箱在构建期间以 starting 返回），只有其所有者的沙箱会从这个模板创建。不适用于从 snapshot 或 template 创建的沙箱 (400 invalid_start)。
start_commandoptional
启动命令，以镜像的用户身份运行，其输出由沙箱的代理程序作为命令 exe-start 的输出保留（最后 16 MiB，像任何命令一样用 GET …/exec/exe-start 和 …/exec/exe-start/output 读取；对于应用的实例，这也是应用日志中该实例的内容）：字符串由 /bin/sh -c 运行，可以有多行；列表按原样运行，不经过 shell（适用于没有 shell 的镜像）。最多 1000 个参数、64 KiB，不能含 NUL 字节，第一个参数不能为空。与 start: false 一起给出时返回 400 invalid_start。
以下之一：
string
array<string>
}
readyoptional
沙箱模板的虚拟机何时算作已启动：只有这项检查通过后，节点才会保存模板（使用这些设置的每个沙箱都从它克隆），这样每个沙箱中的服务从一开始就在运行。三者选一。tcp 和 http 由节点在宿主机上，通过预览 URL 访问沙箱所用的地址进行尝试：不需要在沙箱中运行任何东西，因此没有 shell 的镜像也能检查，但服务必须监听所有地址，而不只是 127.0.0.1。command 以镜像的用户身份在沙箱中由 sh 运行，与标签 sbx.ready 一样。每 0.2 秒尝试一次，最多 120 秒；在此期间启动命令以失败结束的，等待立即结束。无论哪种情况，沙箱都会以 failure_code boot_failed 失败，failure 会给出检查最后得到的结果以及启动命令最后打印的内容。需要 start: true 或 start_command (400 invalid_start)。不给出时：不等待，直接保存模板。
以下之一：
object
object
object
}
egressoptionalobject | null
沙箱可以访问什么、可以向某个主机请求什么，以及它的哪些请求会被加上机密。在沙箱运行任何东西之前就生效。从 snapshot 创建的沙箱，除非给出此字段，否则以快照记录的规则开始；此时 null 表示没有规则。
- defaultoptionalallow或deny或null
- allowoptionalarray | null
- denyoptionalarray | null
- httpoptionalarray | null
- injectoptionalarray | null
- deny_portsoptionalarray | null
  任何连接都到达不了的端口，TCP 或 UDP，无论规则的其他部分怎么说：最多 64 个，每个为 1 到 65535。null 或为空：没有。
}
guest_mitigationsoptionalboolean
客户机内核是否保留针对推测执行的缓解措施。它们保护客户机内核不受同一沙箱中进程的攻击：当一个沙箱运行多个互不信任的用户的代码时，请开启它们。无论如何，宿主机都会把各沙箱相互隔离。默认：节点的设置（关闭）。该设置在内核启动时确定：第一个设置与其镜像模板不同的沙箱，会像新镜像一样启动（以 starting 返回），从快照创建的沙箱沿用快照的设置（请求另一种设置会返回 400）。
tmpoptionaldisk或memory
沙箱的 /tmp 放在哪里。disk：与其他部分一样放在磁盘上。memory：最多占其内存一半的 tmpfs，在第一个命令之前挂载（对从模板或镜像创建的沙箱，覆盖在模板客户机放在那里的内容之上；从其磁盘启动时由客户机的 init 挂载）：写在那里的内容占用客户机的内存，按内存计费，休眠时保留，从磁盘重新启动时消失。如果快照所属的沙箱把它放在内存中，从该快照创建的沙箱无论这里怎么设置也都放在内存中。

default: "disk"
runtimeoptional
其虚拟机及其命令的运行时设置，与 Compose 文件中的 ulimits、sysctls、tmpfs、dns 和 shm_size 一样 (Runtime)。对从镜像创建的沙箱：会用这些设置为调用方构建一个专属模板（没有指定启动方式时，按镜像的标签启动镜像）。从快照或模板创建的沙箱会被拒绝 (400 invalid_start)，它们沿用其虚拟机已有的设置。
以下之一：
NodeRuntime
ulimitsoptionalobject | null
按 Docker 的名称（core、cpu、data、fsize、locks、memlock、msgqueue、nice、nofile、nproc、rss、rtprio、rttime、sigpending、stack）：一个数字同时作为两个限制，或者 {soft, hard}，软限制不能高于硬限制；-1 表示不限制。nofile 为 1 到 1048576（客户机的 fs.nr_open），不能为 -1。以 {soft, hard} 形式显示。

sysctlsoptionalobject | null
Docker 允许容器设置的那些，按名称：net.*、kernel.shm*、kernel.msg*、kernel.sem、fs.mqueue.*；值为单行 1 到 1024 字节。以字符串形式显示。

tmpfsoptionalarray | null
挂载时禁用 set-user 位和设备文件。

dnsoptionalobject | null
取代镜像的 /etc/resolv.conf。在节点自己回答沙箱查询的地方（在其项目网络中；出站规则可以拒绝某个名称时），节点会代替所指定的服务器回答：只有节点不代为回答的沙箱，才会直接向这些服务器查询。

serversoptionalarray | null
searchoptionalarray | null
optionsoptionalarray | null
shm_size_bytesoptionalinteger | null
maximum: 1099511627776 · minimum: 1048576
null
}
initoptional
沙箱的 PID 1 是什么。不给出或为 null：平台的 init，它会启动镜像的启动命令（如果有的话：start、start_command、镜像的标签）。systemd：完整的系统。镜像自己的 systemd 作为 PID 1，节点的代理程序是它的一个服务：用户可以安装软件包、用 systemctl 启动服务、使用 cron 和 journal，并通过 SSH 登录，就像在一台机器上一样。创建请求指定的任何东西都不会被启动（start、start_command 和 ready 会被拒绝，返回 400 invalid_start），在 systemd 报告机器已启动后保存模板。不带 image 时：使用节点的完整系统镜像（--systemd-image；带 systemd 和 OpenSSH 的 Ubuntu 24.04，sandboxd/images/ubuntu），没有这种镜像的节点会拒绝，返回 400 invalid_start。没有 systemd (/usr/lib/systemd/systemd) 的镜像会构建失败，failure_code 为 invalid_image。其模板对以同样方式请求同一镜像的任何人都可用，除非其中有调用方自己的东西（runtime、image_pull_secret）。从快照或模板创建的沙箱会被拒绝 (400 invalid_start)，它们沿用其虚拟机原来的样子。沙箱的其他一切功能都与任何沙箱一样：命令、文件、终端、SSH 网关、休眠和唤醒、快照和分叉、迁移、出站规则（sandboxd/README.md，「整个系统：systemd 当 PID 1」）。
以下之一：
string
null
}
project_networkoptionalboolean
true：沙箱在运行任何东西之前就接入其项目的私有网络，使用节点为该项目预留的第一个空余地址 (setProjectNetwork)：响应会给出是哪个地址 (project_address)。项目就是调用的所有者，所以这是供控制平面代项目发起的调用使用的；在独立运行的节点上，沙箱不属于任何人，要接入网络需要在网络中指定它。沙箱除非提出请求，否则不会接入任何项目网络：默认 false。分叉出的副本不接入任何网络，无论原沙箱在哪个网络中。
imageoptionalstring
OCI 镜像引用（python:3.12、ghcr.io/org/app@sha256:…），位于互联网上的镜像仓库：可以是对所有人开放的仓库，也可以是需要登录的仓库（配合 image_pull_secret）。某个镜像的第一个沙箱在节点拉取镜像并构建模板期间以 starting 返回；之后的沙箱从模板启动。默认：节点的基础镜像。

maxLength: 512
image_pull_secretoptionalstring
保存非公开镜像所在仓库凭据的机密 (PUT /v1/secrets/{name}) 的名称：可打印 ASCII 格式的 username:password，用户名到第一个冒号为止。只接受令牌的仓库会说明与令牌搭配的用户名（ECR 为 AWS，Google 的为 oauth2accesstoken，GHCR 任何名称均可）。节点只把凭据交给拉取镜像的工具：沙箱、其模板和节点日志中都不会有凭据的任何内容，仓库拒绝凭据时给出的说明也不含凭据（failure_code 为 registry_auth_failed）。沙箱从只属于其所有者的模板创建，只有指定了凭据的创建请求才会找到这个模板：不带凭据指定同一镜像时，无论节点有没有该模板，都会不登录直接向仓库请求镜像。该机密必须存在 (404 secret_not_found)，必须允许发往镜像所在的仓库（其 allowed_hosts 涵盖镜像引用中写的仓库主机，不含端口，没有指定时为 docker.io；否则返回 403 secret_host_not_allowed），且必须保存这样一对凭据 (400 invalid_field)，还必须与 image 一起使用（沙箱不是从镜像创建时返回 400 invalid_field）。

maxLength: 128
snapshotoptionalstring
快照的 id 或名称：沙箱从创建快照的那一刻继续运行，包括其进程。
templateoptionalstring
节点上模板的键（base、img-…），与 GET /internal/node 列出的一致。参考 README 中没有记录；基准测试脚本会用到它。
limitsoptionalobject
创建请求所要求的规格。没有给出（或为 null）的每一项，都取节点基础模板的值，也就是不指定规格的沙箱得到的规格。最多为本节点给沙箱的上限，即 GET /internal/node 的 max_vcpus 和 max_memory_bytes（默认为宿主机的 CPU 数，最多 32，以及其内存；从不小于基础模板的规格）；超出返回 400 invalid_field。同一镜像的每种规格都是一个独立的模板：节点还没有用该镜像构建过某种规格时，这种规格的第一个沙箱在节点用同一镜像构建模板期间以 starting 返回，之后的沙箱从它克隆。不带 image 时，基础模板以外的规格从节点的基础镜像构建。从 snapshot 或 template 创建的沙箱沿用其规格：请求相同的规格没问题，请求其他规格返回 400 invalid_field（param 为 limits）。磁盘大小由节点决定：给出 disk_bytes 返回 400 invalid_field。
- vcpusoptionalinteger | null
  虚拟 CPU 数。
  
  maximum: 32 · minimum: 1
- memory_bytesoptionalinteger | null
  内存，以字节表示：偶数个 MiB（2 MiB 页的整数倍），不少于 128 MiB。其他任何大小都返回 400 invalid_field（param 为 limits.memory_bytes），预先创建的模板 (POST /internal/templates) 和就绪列表中的规格 (ready_images.unread_lines) 也一样：把模板内存放在大页中的节点会以 2 MiB 页为单位加载虚拟机的内存，Firecracker 会拒绝加载其他大小的内存，因此 285 MiB 的模板虽然能构建，但从它创建的每个沙箱都会失败。不会取整：沙箱要么得到所请求的大小，要么被拒绝。
  
  format: int64 · minimum: 134217728
}
nameoptionalstring
调用方为沙箱、快照、存储卷或 SSH 密钥起的名称：1 到 63 个小写字母、数字和连字符，不能以连字符开头或结尾，也不能以 id 前缀开头（sbx-、exe-、snap-、vol-、evt-、req-；SSH 密钥还不能以 sshkey- 开头）。即一个不会被误认为 id 的 DNS 标签。在沙箱、快照、存储卷和 SSH 密钥各自的范围内唯一。

pattern: ^[a-z0-9]([a-z0-9\-]{0,61}[a-z0-9])?$
envoptional映射，值为string
环境变量。名称须匹配 [A-Za-z_][A-Za-z0-9_]*；值不能含 NUL 字节；合计最多 256 KiB。
secret_envoptional映射，值为string
更多的环境变量，其值为机密：沙箱中启动的每个命令都会和 env 一起得到它们，启动命令也一样（在写 env 的地方为它写入，别处都不写：模板的键和记录中都没有它们的值）。任何响应都不显示值：沙箱只显示其名称 (Sandbox.secret_env)。最多 64 个变量、64 KiB，名称规则与 env 相同，其中任何一个都不能同时出现在 env 中（400 invalid_field，param 为 secret_env.<name>）；在创建沙箱时确定，之后不能修改（如果 PATCH 在 env 中给出其中某个名称，也会同样被拒绝，param 为 env.<name>）。快照中不包含它们：从快照创建的沙箱使用它自己的创建请求给出的那些。
metadataoptional映射，值为string
供调用方自用的任意键值对；沙箱列表可以按它们筛选。最多 64 个键，每个键 1 到 64 个字符，值最多 1024 个字符。不要在这里存放机密：元数据以明文保存，沙箱在产生用量期间有过的每组元数据都会随其用量保留十三个月，沙箱删除后也一样（GET /v1/usage 按它们分组和筛选）。
volumesoptional数组，元素为object
在调用返回之前挂载的存储卷。非共享的最多两个。从推迟启动命令的模板 (TemplateBuildRequest.start_after_volumes) 创建的沙箱，会在存储卷挂载后启动其启动命令，调用在命令按模板的 ready 判断启动完成后返回；每次从其磁盘启动（重启、宿主机宕机）也一样，会先挂载存储卷。
- pathstringrequired
  存储卷在沙箱中的挂载位置：/ 以外的绝对路径。
- volumestringrequired
  存储卷的 id 或名称。
- read_onlyoptionalboolean | null
  以只读方式挂载。对共享存储卷，这一点在节点上强制执行，而不是在沙箱中。
  
  default: false
- copyoptionalboolean | null
  true：新的存储卷（其文件系统中还没有任何东西）在第一次挂载时，写入沙箱镜像在 path 上的内容，与 Docker 对新的具名卷的处理一样：每个文件、目录和链接，连同其所有者、权限、时间、扩展属性和硬链接（比如数据库镜像的数据目录，带有其服务器需要的所有者）；然后它就处于这种状态，没有 lost+found，与新的具名卷一样（会自行初始化数据目录的服务器会拒绝非空的目录）。已有内容的存储卷按原样挂载。只在创建沙箱时有效：之后挂载的存储卷 (PATCH) 不接受 copy (400 unknown_field)。
  
  default: false
- versionoptional
  volume 指定的云盘的某个版本，以其快照所说的为准 (slice D7)：沙箱会得到该版本的一个只读视图，属于它自己，在读取时从对象存储取回，无论云盘在谁手上、在哪里（云盘之后可能已被删除）。以只读方式挂载。
  
  以下之一：
  DriveVersion
  namestringrequired
  其根在对象存储中的名称。
  
  pattern: ^disks/vol-[0-9a-hjkmnp-tv-z]{16}/e[0-9]+/r[0-9]{10}-[0-9a-f]+$
  bytesintegerrequired
  format: int64 · minimum: 0
  epochintegerrequired
  format: int64 · minimum: 1
  numberintegerrequired
  format: int64 · minimum: 1
  tokenstringrequired
  pattern: ^[0-9a-f]+$
  refsstringrequired
  其引用列表，在对象存储中：控制平面的回收程序为它保留的内容。
  
  storestringrequired
  其根、页和帧所在存储的标识。
  
  keystringrequired
  加密它所用密钥的编号（在密钥开始编号之前的版本为空）。
  
  null
}
public_portsoptional数组，元素为integer
任何人都可以通过其短预览 URL 打开的端口。

maximum: 65535 · minimum: 1
public_ports_exceptoptionalarray | null
除这些端口外，其他所有端口也都公开：其短预览 URL 对任何人开放，与 public_ports 中的端口一样（这是 E2B 处理沙箱端口的方式；控制平面的 E2B 兼容层给出 [49983]，即 envd 的端口，用沙箱令牌打开）。[]：所有端口。null（默认）：只有 public_ports。端口按顺序，每个只取一次。
awake_portsoptionalarray | null
通过预览 URL 升级的连接（WebSocket：浏览器的 DevTools 客户端在 9222 端口，屏幕的观看者在 6080 端口）在这些端口上只要打开，就让沙箱保持运行并为此计费。只要这里指定了端口，沙箱是否空闲就只取决于这些连接以及交给它的请求和调用，与客户机做什么无关：其 CPU、定时器、连往任何地方的连接及其流量都不会让它保持运行，它也不会为定时器而被唤醒（期间到期的定时器会在下一个连接唤醒它时触发）。最后一个这样的连接结束 sleep_after_seconds 秒后，它就进入休眠，不会询问其客户机。这类连接在客户端一侧启用了 TCP keepalive，因此没有关闭连接就离开的客户端会在约一分钟内被发现。null 或 []（默认）：与任何沙箱一样判断空闲。按顺序保存，去掉重复项。不适用于一次性运行 (POST /v1/run)。浏览器会话 (reports/browsers/README.md) 创建时为 [9222]。
connection_idle_secondsoptionalinteger | null
awake_ports 中某个端口上的连接，在双向都没有任何数据多久之后会被节点关闭（如果没有别的东西让沙箱保持运行，沙箱会在此后 sleep_after_seconds 秒进入休眠）。null（默认）：不会因此关闭。对设置之后打开的连接生效。

maximum: 86400 · minimum: 1
inboundoptionalarray | null
从一开始就在沙箱自有 IPv6 地址上向互联网开放的端口，各附其来源（之后可用 …/tcp/{port} 开放）。没有地址池的节点会拒绝非空列表：409 no_ipv6。
sleep_after_secondsoptionalnumber | null
空闲多少秒后休眠。null：从不自行休眠。默认值为节点的设置（--sleep-after-seconds，未设置时为 30）。

maximum: 1000000000 · minimum: 1 · default: 30
expires_atoptionalstring | null
在这个时间删除沙箱，必须是将来的时间（或者按 on_expiry 的设置处理）。null 或不给出：永不。

format: date-time
on_expiryoptionaldelete或sleep或hold或null
expires_at 到时做什么：delete 删除沙箱（null 或不给出时：即此项）；sleep 让它休眠（不管里面在做什么）并保留它（此后其 expires_at 为 null，请求照常会唤醒它）；hold 同上，但保持休眠（此时会设置 held_asleep：请求不会唤醒它）。这是 E2B 在沙箱到期时暂停它的方式（控制平面的 E2B 兼容层）。其他值返回 400 invalid_field。

default: "delete"
held_asleepoptionalboolean | null
true：休眠期间，发往其端口的请求不会唤醒它：预览监听器会代为返回 502 sandbox_paused，与 E2B 的代理对已暂停沙箱的响应一样 (x-preview-ingress)，只有 API 调用（或它自己的定时器）才会唤醒它。它本身不会让沙箱休眠：那是 POST /v1/sandboxes/{id}/sleep 的事。false 或 null：与任何沙箱一样。（相当于 E2B 不带 autoResume 的 pause，由控制平面的 E2B 兼容层设置，在其 connect 时移除。）

default: false
sleep_notice_msoptionalinteger | null
在空闲规则让沙箱休眠（或暂停）之前多久，向连接到其客户机 /run/sbx/awake 的每个程序发送一行 sleep N，单位为毫秒；休眠在这段时间之后到来，除非期间发起的保持推迟了它 (sleep_hold_max_ms)。没有程序连接时，不会推迟。有人请求的休眠（POST /v1/sandboxes/{id}/sleep、冻结、迁移、节点停止）不会发出任何通知。0、null 或不给出：不通知。

maximum: 60000 · minimum: 0
sleep_hold_max_msoptionalinteger | null
客户机中的程序发起的保持（在 /run/sbx/awake 上发送 +）最多能让沙箱保持运行多久，单位为毫秒，从第一次发现它被保持、且没有别的东西让它保持运行的那一刻起算；到时无论有什么保持，它都会休眠（如果 sleep_notice_ms 要求通知，会先向已连接的程序发送 sleep N cap），下一次安静时重新开始计算。保持期间它在运行，并按运行计量。0：不理会保持。null 或不给出：节点的设置（--sleep-hold-max-seconds，未设置时为 30 秒）。

maximum: 900000 · minimum: 0
suspend_after_msoptionalinteger | null
空闲规则停止沙箱后，暂停层级（GET /internal/node 的 pause_tier）让它保持暂停多久，才保存其内存并真正休眠，单位为毫秒。暂停时，它在一两毫秒内响应，按其占用的内存计量；休眠时，按其在磁盘上保存的数据计量。无论这里怎么设置，节点的 --pause-max-seconds（未设置时为 600）也是保持暂停的最长时间：暂停的虚拟机会占用宿主机的内存。宿主机内存低于下限、其他虚拟机需要占用槽位，或者有人请求休眠，都会让它更早休眠。null 或不给出：节点的设置。节点没有暂停层级时不起作用。

maximum: 86400000 · minimum: 1000
wake_daily_atoptionalstring | null
每天的某个 UTC 时刻 (HH:MM)，沙箱休眠或暂停期间，节点每天此时唤醒它，让它完成等待唤醒、自己不计时的工作（比如数据库维护）。唤醒本身不算活动：唤醒后运行的东西才算，运行完毕后空闲规则会再次让它休眠。不适用于按连接判断空闲的沙箱 (awake_ports)。此外，有状态服务的实例（其启动命令为等待存储卷而推迟）还会为其 PostgreSQL 服务器 pg_cron 任务的下一次运行而被唤醒，节点在让它休眠之前会向其代理程序询问这一时间；有任务在运行，或在 5 秒内到期时，空闲规则不会让它休眠。null 或不给出：不唤醒。

pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
delete_after_idle_msoptionalinteger | null
沙箱休眠多久后删除，单位为毫秒 (Sandbox.idle_since)；唤醒后，从下一次休眠起重新计算。null 或不给出：不会因此删除。小于 1000 会被拒绝 (400 invalid_field)。

format: int64 · minimum: 1000
hostnameoptionalstring | null
沙箱虚拟机永久使用的主机名，代替其 id：即在其中运行 hostname 得到的名称，从第一次启动起，每次重启后也一样。由小写字母、数字和连字符组成、以点分隔的标签；否则返回 400 invalid_field。控制平面会给服务的实例使用服务的名称（或服务的 hostname）。不给出时：沙箱的 id。

maxLength: 63 · pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$
stopoptionalobject | null
在虚拟机被彻底结束之前如何停止沙箱的启动命令：在重启 (POST /v1/sandboxes/{id}/restart) 和删除之前。信号发给启动命令，然后给它 grace_ms 时间结束；到时还没结束的随虚拟机一起结束。休眠或暂停的虚拟机不会被停止：它会从上次停下的地方继续。不给出时：启动命令随其虚拟机一起结束，一直以来都是这样。不认识的键：400 unknown_field；不是这些信号之一，或者宽限时间超过十分钟：400 invalid_field。
- signaloptionalSIGTERM或SIGINT或SIGQUIT或SIGHUP或SIGUSR1或SIGUSR2另有 15 个
  用名称指定，带不带 SIG 均可。null：镜像自己的停止信号（其 STOPSIGNAL），没有则为 SIGTERM。
- grace_msoptionalinteger | null
  null 或不给出：10000 毫秒。
  
  maximum: 600000 · minimum: 0
}
logoptionalobject | null
沙箱的日志行发往的应用日志，与应用实例的日志行一样 (readAppLog)：其启动命令打印的内容、经由其端口的每个请求一行，以及节点对它做了什么（创建、停止、删除）。适用于从应用版本模板创建的、属于其所有者的沙箱（template，即日志用来识别该版本的键）：控制平面会为应用的键控实例和有状态服务的实例给出它。除此之外，应用组的任何设置都不适用于它：它不是接收应用请求的实例，按沙箱的方式休眠和删除。不带 template 时：400 invalid_field。
- appstringrequired
  控制平面对该应用的称呼：日志的名称，与 setApp 的 metadata.app 给出的一致。
  
  maxLength: 64 · minLength: 1
- versionoptionalstring | null
  以及版本，其日志行会注明它。
  
  maxLength: 64 · minLength: 1
}
checkpointoptional
沙箱运行期间的检查点：每隔 every_seconds 秒，把沙箱在某一时刻的内存和磁盘送到节点的对象存储（为此节点会把其虚拟机暂停几毫秒；发送的是自上一个检查点以来写入的内容），这样在节点的宿主机丢失时，沙箱会在别处连同进程一起从最新的检查点接管，最多丢失此后做的事。只有上一个检查点已进入对象存储，才会开始下一个：写入速度超过节点检查点链路承载能力的沙箱会落后 (checkpoint.behind_seconds)，而不是把链路占满。休眠时，从其休眠镜像接管。null（默认）：不启用。任何沙箱都可以启用，在创建时给出或通过 PATCH 设置（控制平面也会为 checkpoint 要求启用的应用的键控实例启用）；对象存储为其最新检查点保存的数据，在沙箱运行期间按休眠沙箱的状态计费 (checkpoint.stored_bytes)。不把磁盘复制到对象存储 (--upload) 的节点，或内存不分层的节点，会拒绝启用（409 checkpoints_unavailable，param 为 checkpoint），控制平面只会在支持检查点的节点上创建启用了检查点的沙箱。其云盘会与它自己的磁盘在同一时刻固定下来，从检查点接管时会连同内存一起恢复到那一刻的状态；挂载了非云盘的存储卷时（这种存储卷在对象存储中没有副本），或者客户机在其虚拟机的某块磁盘上有一次读取被卡住时，不会创建检查点。检查点不会重置客户机的 vsock 连接（代理程序的调用照常进行），如果对象存储中已有其休眠镜像，唤醒后的第一个检查点只发送客户机此后写入的内容。
以下之一：
object
null
}
regionoptionalna或eu或ap或null
创建所在的区域，由 API 读取，不会转发。null 或不给出：API 自己运行所在的区域。该区域没有机器能容纳时，由下一个区域接手；必须放在某台特定机器上的（从快照或带存储卷创建的，或用同一个 Idempotency-Key 再次发送的）会放到那台机器上，无论在哪个区域。从备份创建的存储卷创建在备份所在的区域：指定其他区域会返回 400 invalid_field。不是有效区域：400 unknown_region。响应中的 region 说明它创建在哪里。

Returns

201

沙箱。

JSON

idstringrequired
sbx- 加 16 个字符；可以用作 DNS 标签。

pattern: ^sbx-[0-9a-hjkmnp-tv-z]{16}$
awake_ports数组，元素为integerrequired
其升级连接能让它保持运行的端口；只有这些端口（加上它的请求和调用）决定它是否空闲 (SandboxCreate)；与其他沙箱判断空闲方式相同的沙箱为空。

maximum: 65535 · minimum: 1
connection_idle_secondsinteger | nullrequired
awake_ports 中某个端口上的连接，在没有任何数据多久后被节点关闭，单位为秒 (SandboxCreate)；null：不会因此关闭。

minimum: 1
awake_connectionsintegerrequired
其 awake_ports 上当前打开的连接：只要有一个，它就保持运行（awake_because 会说明），不会按空闲规则被休眠。

minimum: 0
start_commandrequired
其启动命令的运行情况：结束后在其虚拟机中被重新启动了多少次，以及上一次运行如何结束，以其客户机最后一次的说法为准（虚拟机运行期间每秒一次：src/restarts.rs）。对于保存着所有者状态的实例（键的实例、有状态服务的实例：比如数据库的），在其命令启动之后，节点会让客户机在同一台虚拟机中重新启动它，磁盘和存储卷保持原样；应用组内的实例则会被退役，由另一个实例取代；其他沙箱的启动命令结束后就保持结束状态。其客户机还没有报告时为 null：没有启动命令、还没有开始（有状态服务的启动命令要等其存储卷），或者自节点知道要询问以来其虚拟机还没有运行过。
以下之一：
SandboxStartCommand
statusstringrequired
running：正在运行（或者它留下的东西仍占用着其输出）；restarting：已结束，将在 restarting_at 重新启动；exited：已结束，不会再被启动。

restartsintegerrequired
自沙箱创建以来，它在虚拟机中被重新启动了多少次，跨越其虚拟机的多次启动累计。

format: int64 · minimum: 0
last_exitrequired
上一次运行如何结束；还没有运行结束过时为 null。

以下之一：
object
null
restarting_atstring | nullrequired
处于 restarting 时：下一次运行的开始时间，按其客户机的时钟（届时如果虚拟机在休眠，会在醒来时启动）。其他情况为 null。

format: date-time
null
}
devtoolsobject | nullrequired
浏览器镜像的沙箱（带有标签 sbx.devtools 的镜像，即其浏览器 DevTools 协议的端口）：浏览器自己的地址，由节点在构建该镜像的模板时询问得到 (/json/version)。浏览器属于模板，从该模板创建的每个沙箱中都相同，沙箱去到哪里它就跟到哪里。只接受 WebSocket 地址的客户端，连接到 port 签名链接上的 path。其他沙箱为 null。
- portintegerrequired
  maximum: 65535 · minimum: 1
- pathstringrequired
  /devtools/browser/<the browser's id>.
  
  pattern: ^/devtools/browser/[A-Za-z0-9-]{1,64}$
}
proxyrequired
它自己的代理（SandboxCreate 的 proxy）：其地址以及请求时使用的用户名，从不包含密码。没有时为 null。
以下之一：
SandboxProxy
urlstringrequired
http://host:port：代理的地址，不含凭据。

usernamestring | nullrequired
请求代理时使用的用户名；不使用用户名时为 null。

null
}
image_digeststring | nullrequired
其磁盘所来自的镜像，按其清单（或清单列表）的摘要，与构建其模板时镜像仓库给出的一致 (Template.image_digest)：即当时标签所指的镜像。之后移动标签，会让之后创建的沙箱使用另一个镜像（一个更新的模板），而这个沙箱的保持不变。在其模板构建期间 (starting)：构建所用的镜像，如果创建时已知（发现标签指向比那里的模板更新的镜像，就按那个摘要构建），否则为 null；模板没有说明时（从磁盘文件构建的，或在模板记录这一信息之前构建的）也为 null。

pattern: ^[A-Za-z0-9]+:[0-9A-Fa-f]{32,}$
appstring | nullrequired
对于应用的实例（节点根据应用请求创建和删除的那种，PUT /internal/apps/{key}）：该应用，按其模板的键，以节点的盘点为准。其他沙箱为 null，包括应用的键控实例（其 metadata 说明了其应用和键）。控制平面如果最先在某个调用的响应中看到某个实例，就靠这个字段把它排除在边缘节点的表之外，与对待节点盘点中列出的实例一样。
ipv6string | nullrequired
它自有的公网 IPv6 地址，在其整个生命周期内不变：它通过 IPv6 发送的流量从这个地址发出，不做地址转换，发往它的流量按 inbound 的设置放行。在有地址池的节点上创建时分配；休眠、快照和迁移后都保留；分叉出的沙箱或从快照创建的沙箱有自己的地址。null：只有 IPv4（其节点没有地址池，或者其模板中的代理程序早于自有地址功能）。
inbound数组，元素为objectrequired
在 ipv6 上向互联网开放的端口，各附其开放的来源，按协议和端口排序。默认关闭：为空。
- protocoltcp或udprequired
- portintegerrequired
  maximum: 65535 · minimum: 1
- from数组，元素为stringrequired
  它对哪些 IPv6 前缀开放（2001:db8::/32；单个地址写作 128 位前缀，2001:db8::7/128；::/0 表示所有人），每个只出现一次，按顺序排列。
}
checkpointrequired
其运行期间的检查点（SandboxCreate 的 checkpoint）及其进展；没有启用时为 null。
以下之一：
CheckpointStatus
every_secondsintegerrequired
该设置。

maximum: 600 · minimum: 1
last_atstring | nullrequired
对象存储中其最新检查点的时刻（为此暂停其虚拟机的时刻）；第一个检查点之前为 null。

format: date-time
behind_secondsnumberrequired
运行期间，其最新检查点比 every_seconds 多出的时长。下一个检查点在传送途中时它会上升，进入对象存储后回落：检查点跟得上时，它保持为 0 或低于一个检查点到达对象存储所需的时间；超过一个间隔，说明某个检查点用的时间超过了一个间隔，如果写入速度快于检查点送往对象存储的速度（或对象存储没有响应），它会继续增长。休眠时为 0。

minimum: 0
bytes_per_secondintegerrequired
其检查点最近的发送速率，每秒字节数（压缩后）。

minimum: 0
stored_bytesintegerrequired
对象存储为其最新检查点保存的数据：当时的内存、设备状态，以及当时对象存储中没有其他副本的磁盘数据块。在它运行期间按休眠沙箱的状态计费。

minimum: 0
errorstring | nullrequired
用一句话说明上一个检查点为什么没有创建或没有发送；正常时为 null。

null
}
secret_env数组，元素为stringrequired
创建时 secret_env 中变量的名称，按顺序；从不包含值。创建时没有给出时为空。
objectstringrequired
namerequired
调用方给它起的名称，或者为 null。
以下之一：
Name
null
}
statusstringrequired
仅供参考：调用之前不必查看它。starting：正在拉取并构建其镜像，需要它的调用会等待。sleeping：内存已保存，什么都没有在运行（只剩磁盘的沙箱，以及暂停在节点内存中的沙箱，也显示为此状态：sleep_tier 会说明是哪一种）；下一个需要它的调用会唤醒它。failed：无法构建或唤醒，或者节点的宿主机宕机后无法读取它在节点上的记录，需要它的调用会返回 409 sandbox_failed。修改它的调用（创建、休眠、重启、恢复）的响应，显示的是该调用留下的状态。
sleep_tierrequired
sleeping 状态的沙箱以何种方式休眠；其他状态为 null。paused：其虚拟机连同进程和连接静止在节点的内存中（开启了暂停层级的节点会暂停空闲的沙箱，而不是保存它），调用会在约一毫秒内恢复它；其虚拟机占用的内存像运行中的沙箱一样计量（usage.memory_bytes、memory_gib_seconds），CPU 不计量。saved：其内存和设备状态保存在节点上，什么都没有在运行；调用会在几毫秒内从中唤醒它。disk：只剩下磁盘（其虚拟机自行结束了，节点守护进程没有让它休眠就结束了，或者其内存无法保留）；下一个需要它的调用会从磁盘启动它，原来运行的东西都已不在。POST /v1/sandboxes/{id}/sleep 会保存沙箱，无论它是暂停的还是在运行的。
以下之一：
string
null
}
failurestring | nullrequired
沙箱为何处于 failed，用一句话给人看；其他情况为 null。它不会提到节点的任何内容：没有路径，也没有工具日志中的行。如果镜像仓库拒绝了所用的凭据，会附上仓库的原话，其中的凭据已去掉。
failure_coderequired
沙箱为何处于 failed，供程序使用；其他情况为 null。image_not_found：镜像不在其仓库中，或者不是公开的（对于没有指定凭据的创建请求，需要登录的仓库只会这样说）。image_pull_failed：连不上镜像仓库，或者仓库没有交出镜像，或者拉取工具因节点的某项限制被停止（failure 会说明是哪一项）。registry_auth_failed：镜像仓库拒绝了创建请求指定的凭据 (image_pull_secret)；failure 中有仓库的说明。image_unpack_failed：镜像放不进磁盘、超过节点接受的大小（failure 中有具体数字），或者无法解压。invalid_image：镜像仓库位于节点上或私有网络中的地址，或者无法按要求启动镜像（start: true 却没有 ENTRYPOINT 或 CMD，或者标签要求了无法做到的事）。boot_failed：用镜像创建的虚拟机没有启动，或者其启动命令没能启动（此时 failure 会给出就绪检查得到的结果以及它最后打印的内容）。no_capacity：节点没有空间。memory_full：宿主机的内存没有空间容纳构建其模板所用的虚拟机，或容纳它自己的虚拟机。drive_full：构建镜像模板期间，节点的数据盘满了。record_lost：无法读取沙箱的记录；其文件保留在节点上，但它无法启动，只能删除。recovery_failed：沙箱的启动恢复无法完成；其文件和恢复意图保留在节点上，它无法启动，只能删除。start_failed：其他任何情况；节点日志中有记录。
以下之一：
string
null
}
imagestring | nullrequired
沙箱所对应的 OCI 镜像引用。只有在基础模板是从磁盘文件构建的节点上才为 null。
snapshotstring | nullrequired
沙箱最后一次采用其状态的快照的 id：即创建它所依据的快照，或它被恢复到的快照。从镜像创建的沙箱为 null。该快照被删除后不会清空；对于分叉，它指向分叉自己的临时快照，调用返回时那个快照已经不在了。

pattern: ^snap-[0-9a-hjkmnp-tv-z]{16}$
metadata映射，值为stringrequired
供调用方自用的任意键值对；沙箱列表可以按它们筛选。最多 64 个键，每个键 1 到 64 个字符，值最多 1024 个字符。不要在这里存放机密：元数据以明文保存，沙箱在产生用量期间有过的每组元数据都会随其用量保留十三个月，沙箱删除后也一样（GET /v1/usage 按它们分组和筛选）。
volumes数组，元素为objectrequired
- pathstringrequired
  挂载位置。
- volumestringrequired
  存储卷的 id（从不是名称）。
  
  pattern: ^vol-[0-9a-hjkmnp-tv-z]{16}$
- namestring | nullrequired
  存储卷的名称（如果有）。
- read_onlybooleanrequired
- sharedbooleanrequired
  共享存储卷（由节点通过 NFS 提供）为 true，只属于这个沙箱的存储卷（块设备）为 false。
- kindoptionalstring | null
  存储卷的类型 (Volume.kind)：云盘会在沙箱迁往其他节点时随之迁移 (slice D2)，其他类型则让沙箱留在原处。本节点没有的存储卷为 null。
- view_ofoptionalobject | null
  对于云盘某个版本的只读视图（slice D7：带 version 的 volumes）：所属的云盘以及版本。该视图只属于这个沙箱，随它一起迁移。
  
  drivestringrequired
  pattern: ^vol-[0-9a-hjkmnp-tv-z]{16}$
  versionobjectrequired
  云盘在对象存储中的一个版本（slice D4，其版本表的一个根），以其快照所说的为准 (slice D7)：分叉、恢复和只读视图都基于它创建。
  
  namestringrequired
  其根在对象存储中的名称。
  
  pattern: ^disks/vol-[0-9a-hjkmnp-tv-z]{16}/e[0-9]+/r[0-9]{10}-[0-9a-f]+$
  bytesintegerrequired
  format: int64 · minimum: 0
  epochintegerrequired
  format: int64 · minimum: 1
  numberintegerrequired
  format: int64 · minimum: 1
  tokenstringrequired
  pattern: ^[0-9a-f]+$
  refsstringrequired
  其引用列表，在对象存储中：控制平面的回收程序为它保留的内容。
  
  storestringrequired
  其根、页和帧所在存储的标识。
  
  keystringrequired
  加密它所用密钥的编号（在密钥开始编号之前的版本为空）。
}
public_ports数组，元素为integerrequired
预览 URL 不需要签名和令牌的端口。重复的端口按给出的原样保留。

maximum: 65535 · minimum: 1
public_ports_exceptarray | nullrequired
除这些端口外，其他所有端口也都公开，就像在 public_ports 中一样 (SandboxCreate)；没有设置时为 null。控制平面的 E2B 兼容层创建的沙箱为 [49983]：其端口与 E2B 的一样公开，envd 的端口需要沙箱的令牌。
egressobjectrequired
沙箱存储下来的出站规则：它可以访问什么、可以向某个主机请求什么，以及它的哪些请求会被加上机密。总是存在；没有规则的沙箱，default 为 allow，四个列表为空，其流量走的是没有规则时的路径。deny 涉及的连接或数据包会被拒绝；allow 涉及的会放行；其他的按 default 处理。inject 中的主机视为允许，http 中的主机对其条目允许的请求也视为允许。无论规则怎么说，沙箱都访问不到节点、其他沙箱、私有地址段以及各云平台的元数据地址。

主机名会与 TLS 握手的服务器名称、HTTP 请求的 Host 头匹配（任何端口），也会与沙箱的 DNS 查询匹配；对于规则可以拒绝某个名称的沙箱，节点会自己回答其 DNS 查询（被拒绝的名称得到 REFUSED）。指明某个允许主机的连接，会发往节点为该名称解析出的地址，无论沙箱原本要连哪个地址。既不是 TLS 也不是 HTTP 的 TCP 连接，只有发往规则列出的地址，或节点作为某个允许名称的地址告诉沙箱的地址时，才会放行。UDP 和其他所有协议只按地址判断。在 default: allow 下，deny 列表算不上一堵墙：任何允许的中转流量都能绕过它。
- defaultallow或denyrequired
  What happens to what neither list speaks of.
- allow数组，元素为stringrequired
  在 default: deny 下可以访问的。在 default: allow 下为空。
  
  maxLength: 300
- deny数组，元素为stringrequired
  无论 allow 怎么说，都访问不到的。
  
  maxLength: 300
- http数组，元素为objectrequired
  沙箱可以向某个主机发送的请求，按方法和路径。方法以大写显示，每个只出现一次；其余按给出的原样。
  
  hoststringrequired
  主机名，或 *. 加名称。不能是地址。
  
  maxLength: 300
  allow数组，元素为objectrequired
  放行的请求。不放行任何请求的主机应放在 deny 中。
  
  methodsoptionalarray | null
  方法，以 token 形式给出；以大写保存。请求的方法按发送时的原样比较，所以 get 不匹配任何方法。不能允许 CONNECT。
  
  pathsoptionalarray | null
  模式。模式是一个路径：以 / 开头，不含 ? 和 #，与请求的完整路径比较，即其目标中 ? 之前的部分（查询部分不参与判断）。* 代表任意长度的字符序列，包括 /，其他字符都没有特殊含义：/repos/* 匹配 /repos/ 下的一切，但不匹配 /repos。区分大小写。两者都转换为同一种形式后比较：非保留字符的转义会被解码（%7E 即 ~），其他转义保留，其中的十六进制数字转为大写，ASCII 以外的字节会被转义。编码后的斜杠仍是编码形式，不等于 /；模式中可以包含 %2F 来恰好允许这种情况 (/@types%2Fnode)。主机可能解读为另一个路径的路径没有规范形式，不匹配任何模式（没有 paths 的规则也照样检查它）：包括解码一次或多次转义、把 \ 和编码的斜杠视为 /、去掉段中 ; 之后的内容并去掉段两端的空格后，某一段为 . 或 .. 的路径；含有格式错误的转义、#、控制字符、非 UTF-8 字节，或者会折叠成 .、/ 或 \ 的字符（U+FF0E、U+FF0F、U+FF3C、U+2215、U+2044、U+2024）的路径；超过 8192 字节的路径。这样的请求返回 400 malformed_request。
- inject数组，元素为objectrequired
  节点添加到沙箱发往某个主机的 HTTPS 请求上的请求头。
  
  hoststringrequired
  主机名，或 *. 加名称。不能是地址。
  
  maxLength: 300
  headers映射，值为stringrequired
  每个请求头的名称和值。值中的 ${secrets.NAME} 代表该名称的机密 (PUT /v1/secrets/{name})，它必须允许发往 host（其 allowed_hosts；否则返回 403 secret_host_not_allowed）；沙箱对象只显示引用，从不显示机密。决定请求去向或结束位置的请求头（Host、Content-Length、Transfer-Encoding、Connection、Upgrade、TE、Trailer、Keep-Alive、Expect）不能设置。
- deny_portsoptional数组，元素为integer
  任何连接都到达不了的端口，TCP 或 UDP，无论连往哪里，也无论规则的其他部分怎么说：由数据包过滤器最先拒绝，从不交给代理。只有规则关闭了某些端口时才显示。控制平面会这样关闭浏览器会话的邮件端口和矿池端口。
  
  maximum: 65535 · minimum: 1
}
sleep_after_secondsnumber | nullrequired
沙箱空闲多少秒后休眠。null：从不自行休眠。由调用方设置时至少为 1；应用的实例使用其应用的设置（PUT /internal/apps/{key} 的 sleep_after_ms），可能更短。

minimum: 0
expires_atstring | nullrequired
沙箱自行删除的时间（或按 on_expiry 的设置处理）。null：永不。

format: date-time
on_expirydelete或sleep或holdrequired
expires_at 到时做什么：delete，删除沙箱（默认）；sleep，让它休眠（不管里面在做什么）并保留它，此后其 expires_at 为 null；hold，同上，但保持休眠（设置 held_asleep）。控制平面的 E2B 兼容层会给到期即暂停的沙箱设置 sleep 或 hold。
held_asleepbooleanrequired
休眠且不会被请求唤醒（E2B 的已暂停沙箱，控制平面的 E2B 兼容层在其 pause 和 connect 之间这样保持它）：休眠期间，发往其端口的请求不会唤醒它，预览监听器会代为返回 502 sandbox_paused (x-preview-ingress)。API 调用照常会唤醒它，它自己的定时器也会；它运行时到来的请求会照常交给它。
sleep_notice_msinteger | nullrequired
在空闲规则让它休眠之前多久，通知连接到其客户机 /run/sbx/awake 的程序，单位为毫秒 (SandboxCreate)；null：不通知。
sleep_hold_max_msintegerrequired
其客户机的保持最多能让它保持运行多久，单位为毫秒 (SandboxCreate)：它自己的设置，或节点的设置。保持期间，awake_because 会说明。

minimum: 0
suspend_after_msintegerrequired
暂停层级让它保持暂停多久后才真正休眠，单位为毫秒 (SandboxCreate)：它自己的设置，受节点 --pause-max-seconds 的限制；没有设置时为节点的设置。

minimum: 1000
wake_daily_atstring | nullrequired
休眠期间节点每天唤醒它的 UTC 时刻 (SandboxCreate)；null：不唤醒。

pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
delete_after_idle_msinteger | nullrequired
休眠多久后节点删除该沙箱，单位为毫秒，从 idle_since 起算：被唤醒的沙箱从下一次休眠起重新计算。null：不会因此删除（默认）；沙箱会一直保留，直到被删除或其 expires_at 到期。不会自行休眠的沙箱（sleep_after_seconds 为 null）计算的是被让它进入的休眠（POST /v1/sandboxes/{id}/sleep、其节点重启）。冻结期间（其所有者的支出上限）不计算：冻结会连同数据保留它，解冻后，其当前的休眠从那时开始计算。

format: int64 · minimum: 1000
idle_sincestring | nullrequired
status 为 sleeping 时，当前这次休眠开始的时间：其虚拟机被暂停或休眠的时间，或发现它已结束的时间。节点停止时正在运行的沙箱，从节点重新启动那一刻起算休眠；被冻结过的沙箱，从解冻那一刻起算。不在休眠时为 null。

format: date-time
limitsobjectrequired
虚拟机的规格：其创建请求在 limits 中要求的规格，没有给出的部分取节点基础模板的值；从快照或模板创建的沙箱沿用其规格。磁盘大小对每个沙箱都由节点决定。
- vcpusintegerrequired
  虚拟 CPU 数。
  
  minimum: 0
- memory_bytesintegerrequired
  虚拟机拥有的内存。
  
  format: int64 · minimum: 0
- disk_bytesintegerrequired
  根磁盘的大小。沙箱处于 starting 且还没有磁盘时为 0。
  
  format: int64 · minimum: 0
}
guest_mitigationsbooleanrequired
客户机内核是否保留针对推测执行的缓解措施（创建时的 guest_mitigations）。
tmpdisk或memoryrequired
其 /tmp 放在哪里（创建时的 tmp）：磁盘上，或客户机内存中的 tmpfs，后者按内存计费，沙箱从磁盘重新启动时会消失。从快照创建的沙箱沿用快照所属沙箱的设置。
created_atstringrequired
format: date-time
booted_atstring | nullrequired
虚拟机最后一次从零启动的时间：创建时，以及每次从磁盘重启后。休眠和唤醒不会改变它。

format: date-time
last_active_atstring | nullrequired
节点看到的最后一次活动：一次调用、其链路上的一个数据包、客户机在计算（在 sleep_after_seconds 内平均超过一个核心的 2%，宿主机看到超过这个数时以客户机自己的统计为准；对于客户机尚不报告计算量之前的模板，以宿主机的统计为准），在节点检查时记录。

format: date-time
awake_becausestring | nullrequired
运行中的沙箱为什么还没有被休眠，用几个词说明。status 不是 running 时为 null。应用的实例给出节点提供的原因：手头有请求、有调用在进行中、有请求在不到其 sleep_after_seconds 之前刚结束，或者其应用的下限让它保持运行。被项目网络上的数据包唤醒、之后再没有别的东西让它保持运行的沙箱，会说明这一点以及是哪个数据包：woken by a packet: TCP from 10.64.0.7:41594 to port 5432 [S] …。项目内部的连接不会让任何沙箱保持运行：在它休眠期间经由这些连接到来的数据，由节点暂存 (Node.hold)。
usageobjectrequired
沙箱已经使用和正在使用的资源。
- proxy_sent_bytesintegerrequired
  沙箱自创建以来经由其自己的代理 (proxy) 发送的字节数：进入其隧道的数据，按交给代理的每个字节计（不含建立隧道的请求）。从未有过代理的沙箱为 0。
  
  format: int64 · minimum: 0
- proxy_received_bytesintegerrequired
  沙箱自创建以来经由其自己的代理收回的字节数，按从代理取到的每个字节计，无论沙箱那一端的连接是否还在接收（即代理统计的它发出的量）。
  
  format: int64 · minimum: 0
- awake_secondsnumberrequired
  沙箱的虚拟机自创建以来运行了多长时间，精确到毫秒：即其运行时长。不包括休眠期间，也不包括暂停层级让其虚拟机暂停的期间。与其内存计量所用的毫秒数相同 (memory_gib_seconds)。节点的账目按小时统计它（GET /internal/inventory 中每个时段的 awake_ms）。
  
  minimum: 0
- egress_refused_requestsintegerrequired
  自沙箱创建以来，节点读取了但没有转发的沙箱 HTTP 请求数：被其自己的 egress 规则拒绝的、无法以唯一方式读取的，以及在其所有者的沙箱已占满代理连接份额时到来的（x-egress-proxy 中状态为 400 或 403 的响应、502 secret_missing 和 503 egress_connections_full）。每秒统计一次。每个这样的请求还会在节点日志中记一行，带有响应所附的 id、方法、主机和路径（不含查询）；单个沙箱每分钟最多写 30 行。
  
  format: int64 · minimum: 0
- cpu_secondsnumberrequired
  沙箱的虚拟机自沙箱创建以来使用的 CPU 时间，单位为秒：其 vCPU 以及为它们服务的设备。宿主机代表客户机占用 CPU 等待的时间不计入：虚拟机监控程序轮询以唤醒已停机的 vCPU 的时间，以及块设备查找下一个请求的时间。不计入的部分从不超过已计入的部分：虚拟机进程所用的 CPU 时间至少有一半算作沙箱的。
  
  minimum: 0
- memory_gib_secondsnumberrequired
  沙箱在宿主机上独占的内存 (memory_bytes)，向上取整到 128 MiB 的档位，在沙箱运行或暂停（sleep_tier 为 paused）期间对时间积分：GiB 乘以秒。
  
  minimum: 0
- memory_bytesintegerrequired
  宿主机现在专为这个沙箱占用的内存：客户机对其模板内存写入的部分、模板从未有过的内存，以及 VMM 自身的内存。客户机只读取过的模板内存页由该模板的所有沙箱共享，不计入。暂停的沙箱为其虚拟机静止时占用的内存；以其他方式休眠时为 0。
  
  format: int64 · minimum: 0
- disk_bytesintegerrequired
  根磁盘现在在节点上占用的字节数。
  
  format: int64 · minimum: 0
- egress_bytesintegerrequired
  沙箱自创建以来发送到互联网的字节数：包括它自己发送的，以及发给其预览 URL 访问者的。
  
  format: int64 · minimum: 0
}
host_failurerequired
沙箱最近一次因所在宿主机而丢失了什么，以及原因 (cause)：宿主机硬宕机（断电、内核崩溃）时丢失其内存，以节点恢复后发现的情况为准；或者节点重启时使用的 Firecracker 与保存内存时的不同，而沙箱随后被使用，从而丢失其内存。什么都没有丢失的沙箱为 null：没有经历过上述任何一种情况的，以及休眠时所需的一切都在宿主机磁盘上的沙箱，后者在保持原样的节点上会照常唤醒。在下一次这样的丢失之前，它保持不变。
以下之一：
SandboxHostFailure
atstringrequired
节点发现沙箱处于这种情况的时间。cause 为 hard_stop 时，这是节点恢复的时间；宿主机在此之前的某个时候就已宕机。

format: date-time
causestringrequired
hard_stop：宿主机在没有任何预兆的情况下宕机（断电、内核崩溃）。node_changed：没有任何东西宕机。沙箱的内存，或者创建它所依据、回滚它所到的快照的内存是完整的，但保存它的 Firecracker 构建版本宿主机没有保留（保留的构建版本能唤醒它保存的东西：Node.firecrackers；detail 会指明是哪个构建版本），或者保存时的虚拟机设备设置与节点现在启动虚拟机所用的不同（比如节点升级之后）。保存的虚拟机只能载入保存它的那个环境：载入其他任何环境，都会让客户机在不是原来那些的设备上运行，从而在毫无报错的情况下损坏它读写的数据。节点会一直保留这样的内存，直到沙箱下一次被使用，这样，如果节点用保存它的那个环境重新启动，就能原样唤醒沙箱；在无法加载它的节点上第一次使用时，内存会被放弃，并设置此项。load_failed：没有任何东西宕机，内存是完整的，也是本节点能加载的，但仍然无法恢复（比如更换了宿主机的内核之后：detail 会指明保存内存时的内核以及要加载它的内核）。只有在有证据时才会因此放弃内存：节点的 Firecracker 拒绝加载它；要加载它的进程在加载过程中结束了；虚拟机一加载就结束了；虚拟机已加载但没有响应，且无法再次保存；或者虚拟机已加载、仍然存活但没有响应，并且在第一次之后五分钟或更久再次如此，期间没有一次成功的唤醒。在加载任何东西之前就失败的唤醒，不会改变内存，第一次没有响应以及之后五分钟内的每次没有响应也一样：这些调用会返回 503 unavailable，可以再次发起。发现内存已不在的那个调用，由随后从磁盘启动的虚拟机响应。rollback_interrupted：节点在回滚过程中停止了。在为这个沙箱提供服务之前，已重放了其强制的磁盘替换；其之前的内存已被丢弃，它从快照的磁盘启动。替换意图会一直保留，直到丢失记录和停止的数据块都写入磁盘。moved：沙箱从另一个节点迁到本节点 (POST /internal/sandboxes/{id}/takeover)，但没有带上内存，因为对象存储中没有与其磁盘被恢复到的那个状态完全一致的内存镜像：它在最后一次休眠后被唤醒过，或者另一个节点的宿主机丢失时它正在运行，或者镜像无法读取（detail 会说明是哪一种）。其磁盘就是那个状态（disk 为 restored）。

memorystringrequired
lost：沙箱内存中的东西都已丢失，包括其进程。hard_stop 时：要么其虚拟机正在运行，要么它在宕机之前不久刚刚休眠，内存还没有完整地写入宿主机磁盘；不完整的内存镜像永远不会被唤醒。node_changed 时：内存是完整的，但没有被加载。load_failed 时：内存是完整的，但加载失败。moved 时：无法在它带来的磁盘之上加载任何内存镜像。

diskstringrequired
沙箱磁盘现在的情况。whole：没有任何东西宕机，磁盘没有丢失任何东西（node_changed：与保存内存时一样；load_failed：此外还包括已加载但没有响应的虚拟机在被结束之前写入的内容）。unverified：宿主机上的磁盘，不确定是否完整：沙箱启动时客户机的文件系统会重放其日志，宿主机宕机前最后半分钟写入的内容可能缺失或不完整，无论客户机是否已被告知写入完成。restoring：节点会把磁盘复制到对象存储，正在从那里的副本恢复沙箱的磁盘；在完成之前，需要该沙箱的调用返回 503 unavailable。restored：磁盘是对象存储中的那份副本，即磁盘在 disk_as_of 时真实所处的一个状态。

disk_as_ofstring | nullrequired
disk 为 restored 时：磁盘回到的时刻。之后写入的内容都已丢失。其他情况为 null。

format: date-time
detailstringrequired
同样的内容，用一句话给人看。

null
}
project_addressstring | nullrequired
它在项目私有网络中的地址：项目中同一网络的其他沙箱通过它访问它，也把它视为这个地址，无论它运行在节点的哪个槽位。不在任何项目网络中的沙箱为 null。由告知节点该网络的一方分配 (setProjectNetwork)，或者由带 project_network: true 的创建请求取得。

pattern: ^10\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])(\.(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){2}$
regionrequired
持有它的节点所在的区域，以节点被告知的为准 (--region)：即控制平面把它放在了哪里。在不属于任何区域的节点上为 null。
以下之一：
string
null
}
usable_atstring | nullrequired
其磁盘从对象存储取回（恢复、迁移到本节点，或在本节点从其他节点创建的快照创建沙箱，其磁盘在对象存储中）并能够响应的时刻：其节点已拥有它，并且对于按读取逐步填充的磁盘，已有程序在监听尚未到达的数据块。磁盘在其节点上创建的沙箱为 null。每次这样的到达都会让这四个字段重新开始。

format: date-time
hydrated_atstring | nullrequired
磁盘从对象存储取回后，其所有数据块都已到达其节点的时刻；在此之前为 null，磁盘在本节点创建的沙箱也为 null。从不早于 usable_at；每次到达设置一次（sandbox.hydrated 会说明）。

format: date-time
hydrated_bytesinteger | nullrequired
磁盘从对象存储取回后的填充过程中，其节点上已有多少字节（在客户机第一次读取之前提前取来的数据块也算），总共 total_bytes；全部到达后为 total_bytes。按字节而不是按文件计：最后才到达的几个大文件所占的数据，会显示为剩余的部分。total_bytes 为 null 时它也为 null。

format: int64 · minimum: 0
total_bytesinteger | nullrequired
其磁盘要从对象存储取回多少字节：它自己的，以及（如果其节点没有该镜像，镜像也逐块取回）其镜像的。磁盘在其节点上创建的沙箱，以及在其节点统计出来之前的那一刻，为 null。

format: int64 · minimum: 0
disk_writesrequired
其磁盘今天 (UTC) 写入的数据量，与当天全速写入的份额对照：超出份额后，其磁盘的写入会变慢直到当天结束，但写入都不会失败。在不把磁盘复制到对象存储的节点上为 null，这种节点不统计也不限速；静态实例 (SandboxInternals.static) 的磁盘不复制，也为 null。
以下之一：
SandboxDiskWrites
today_bytesintegerrequired
当天 (UTC) 开始以来写入的字节数。

format: int64 · minimum: 0
checkpoint_copy_bytesintegerrequired
today_bytes 中，其检查点副本写入宿主机磁盘的量（对象存储在宿主机写出之前就收到每个副本时为 0）。当其磁盘的写入被限速时，下一个检查点会等这些字节按该速度写完后再进行。

format: int64 · minimum: 0
full_speed_until_bytesinteger | nullrequired
当天全速写入的份额：默认 100 GiB，除非节点另有设置 (--disk-write-full-gib-per-day)。null：节点不限速。

format: int64 · minimum: 0
limitedbooleanrequired
超出当天份额后：磁盘的写入速度为每秒 2 MiB (--disk-write-after-mib-per-second)，如果沙箱自己的限制更低则按它，直到当天结束。

limited_untilstring | nullrequired
当天结束、磁盘恢复全速写入的时间；没有限速时为 null。

format: date-time
null
}
app_idoptionalstring
控制平面某个应用的实例（SandboxCreate.instance_of：沙箱产品的应用，control/src/sandboxes.rs）：该应用，以控制平面给它起的名称为准，在沙箱整个生命周期内不变。其他沙箱没有这个字段。
version_idoptionalstring
有 app_id 时：其创建请求所要求的应用版本，以控制平面给它起的名称为准。经由控制平面时，为创建它所用镜像的版本 (image_digest)：在应用下移动标签会产生一个独立的版本。
keyoptionalstring
有 app_id 时：在应用的实例中用来查找它的依据，即其名称，没有名称时为其 id。
envoptional映射，值为string
沙箱的环境变量及其值。调用方是不带 exec、files、tty 任何权限范围的沙箱令牌时，没有这个字段（而不是 null）：这些值往往是凭据，用于访问沙箱链接的令牌不应能看到它们。
initoptional
其 PID 1 是什么（创建时的 init）：systemd，其镜像自己的 systemd（完整的系统），或者 null，平台的 init。从快照创建的沙箱或分叉出的沙箱，沿用快照所属沙箱的设置。完整的系统有自己的机器 ID（/etc/machine-id，以及 D-Bus 的副本 /var/lib/dbus/machine-id），在其虚拟机创建时分配（克隆模板或快照、分叉、从快照的磁盘启动），此后在休眠、唤醒、迁移和从磁盘启动时都保持不变；其 journal 按它归档 (/var/log/journal/)。
以下之一：
string
null
}
url_secretoptionalstring
为该沙箱的预览链接签名的机密。调用方是沙箱令牌时没有这个字段（而不是 null）。

pattern: ^[0-9a-f]{32}$
url_patternoptionalstring | null
端口的预览 URL，其中的 {port} 和 {signature} 需要填入：签名为 base32(HMAC-SHA256(key = url_secret, message = port)) 的前 12 个字符（port 为十进制的端口号），使用字母表 0123456789abcdefghjkmnpqrstvwxyz。对于公开端口（public_ports 中的端口，或者给出 public_ports_except 时其中没有指定的端口），去掉 -{signature}。节点没有预览域名时为 null；调用方是沙箱令牌时没有这个字段。

400

请求不符合本调用的要求。invalid_json：请求体不是 JSON 对象；unknown_field：请求体中有本调用不接受的字段；unknown_parameter：查询中有本调用不接受的参数；invalid_field：某个字段或查询参数类型错误或超出范围；invalid_name：name 不是有效的名称；invalid_env：env 中有环境变量无法容纳的名称或值；invalid_metadata：metadata 超出限制；expires_in_the_past：expires_at 不是将来的时间；invalid_egress：egress 不是有效的规则集：param 指明出错的部分；invalid_start：给出的 start、start_command 和 ready 不能这样搭配（有 ready 却没有启动命令，start: false 却带了 start_command），或者其中某一项与 init: "systemd" 一起给出（此时由 systemd 按其单元启动程序），或者 init: "systemd" 没有指定 image，而节点上没有完整系统的镜像 (--systemd-image)，或者沙箱是从 snapshot 或 template 创建的：param 指明是哪个字段；ambiguous_source：image、snapshot 和 template 给出了不止一个；invalid_image：image 不是指向互联网上镜像仓库中某个镜像的引用；invalid_path：某个存储卷的 path 不是绝对路径，或者是 /；invalid_idempotency_key：Idempotency-Key 为空或超过 255 个字符。

JSON

errorobjectrequired
- typestringrequired
  失败的类别。它决定状态码：invalid_request 400、unauthenticated 401、forbidden 403、not_found 404、conflict 409、too_large 413、internal 500、bad_gateway 502（预览监听器、出站代理，以及无法带回其沙箱的接管）、unavailable 503、timeout 504。
- codestringrequired
  具体是哪种失败。本文档顶层的 x-error-codes 表说明了每一个的含义。
- messagestringrequired
  给人看的说明。英文。
- paramstring | nullrequired
  出错的字段或查询参数（如果有）。
- retryablebooleanrequired
  在其他条件都不变的情况下，同一请求稍后可能成功时为 true。
- request_idstringrequired
  所在响应的 X-Request-Id，响应是针对 Idempotency-Key 的重放时也一样。
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  节点的 --docs-url 加上错误码，或者为 null。
}
allowed_hostsoptionalarray | null
随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null。
tooptionalstring | null
随 moved 和 sandbox_moved 返回：沙箱被交给的节点，以控制平面给它起的名称为准，或者为 null。
epochoptionalinteger
随 moved 和 sandbox_moved 返回：沙箱被释放时的纪元。随 wrong_epoch 返回：本节点持有它或释放它时的纪元。

format: int64 · minimum: 1
offsetoptionalinteger
随 sandbox_moved 返回：调用、事件流或终端在命令输出中已读到的位置（事件流最后一个事件的 id）：在沙箱去往的地方从这里接着读（Last-Event-ID，或 from）。

format: int64 · minimum: 0
exec_idoptionalstring
随 POST …/run 的 sandbox_moved 返回：调用启动并在等待的命令的 id，命令在沙箱去往的地方继续运行：迁移结束后，通过控制平面用 GET …/exec/{exec_id}?wait_seconds= 在那里等待它。再次发起同一调用会再启动一次命令，除非带着同一个 Idempotency-Key。
disk_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存到休眠时的磁盘所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
memory_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存那次休眠的内存镜像所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
drives_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱云盘的当前状态所等的时长，单位为毫秒 (slice D2)；没有等待或没有云盘时为 null。

minimum: 0
image_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱磁盘所基于的镜像所等的时长，单位为毫秒（其节点会在模板的镜像上传之前就复制磁盘）；没有等待时为 null。

minimum: 0
imageoptionalstring
随 image_missing 返回：对象存储中没有的镜像的 id，与基于它的磁盘和模板的 disk_image 中的名称一致。

pattern: ^[A-Za-z0-9_-]{1,128}$
buildoptionalstring
随 build_missing 返回：写下沙箱内存的 Firecracker 构建版本，本节点没有保留它。

pattern: ^[0-9a-f]{16}$

401

missing_api_key, invalid_api_key, expired_api_key, invalid_token.

JSON

errorobjectrequired
- typestringrequired
- codestringrequired
- messagestringrequired
- paramstring | nullrequired
- retryablebooleanrequired
- request_idstringrequired
- docs_urlstring | nullrequired
}
move_idoptionalstring
随 already_moving 返回：该沙箱正在进行的迁移。
upgrade_idoptionalstring
随 upgrade_in_progress（该键尚未结束的升级）、upgrade_started（已开始的升级）和 rollback_gone（回退被拒绝的那次升级）返回：即那次升级。

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
moveoptionalobject
随 move_over、move_going_back 和 move_taken_over 返回 (POST /internal/moves/{id}/cancel)：迁移的当前状态。
- objectstringrequired
- idstringrequired
  pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
- sandbox_idstringrequired
- project_idstringrequired
- fromobjectrequired
  idstringrequired
  namestring | nullrequired
  节点名称；之后已从记录中消失的节点为 null。
- toobjectrequired
  idstringrequired
  namestring | nullrequired
  节点名称；之后已从记录中消失的节点为 null。
- epochintegerrequired
  迁移开始时表中记录的沙箱纪元：旧节点在这个纪元释放它，新节点在纪元加一时接管它，旧节点在纪元加二时收回它，从对象存储接管则在纪元加三时。
  
  minimum: 1
- stepstringrequired
  迁移的进展：releasing（正在请旧节点释放它；表中记录它在旧节点上）、taking_over（正在请新节点接管它；表中记录它在新节点上）、reclaiming（新节点拒绝了它，正在请旧节点收回）、restoring（旧节点没有保留它的任何东西，正从对象存储接管）、done（已在新节点上）、failed（留在原处，或回到了原处，或停在某个时间无法消除的故障或运营方的取消发生时所在的位置：error 说明原因）。
- whystringrequired
  发起迁移的原因：运营方的迁移、撤离或恢复。
- wakebooleanrequired
  新节点是否唤醒它：按调用的指定，或按迁移开始时它的状态（是否在运行）。
- from_storebooleanrequired
  新节点只从对象存储接管它。
- releaseobject | nullrequired
  旧节点释放时的响应（sandboxd/openapi/openapi.json，releaseSandbox），不含释放所用的密钥；响应之前为 null。
- takeoverobject | nullrequired
  结束迁移的那次接管的响应（节点文档中的 takeoverSandbox）：磁盘和内存来自哪里 (source)、各用了多长时间 (ms)、memory；之前为 null。
- errorrequired
  失败的迁移：失败原因（如果被带回旧节点，则为新节点的拒绝原因）；已完成的迁移：null；进行中的迁移：如果当前步骤要再次请求，则为该步骤上次得到的答复。
  
  以下之一：
  object
  null
- attemptsintegerrequired
  当前步骤已请求了多少次，仍没有得到确定的答复。
  
  minimum: 0
- next_attempt_atstring | nullrequired
  该步骤何时再次请求；不在等待时为 null。
  
  format: date-time
- batchstring | nullrequired
  它所属的撤离 (evc-…) 或恢复 (rcv-…)。
- created_atstringrequired
  format: date-time
- updated_atstringrequired
  format: date-time
- ended_atstring | nullrequired
  format: date-time
}
lease_untiloptionalstring
随 lease_held 返回：节点最后获得的租约最晚可以持有到何时，再加上让节点察觉租约到期所需的时间（在此之前 recoverNode 会被拒绝）。

format: date-time
activeoptionalobject | null
随 standby 返回：备用副本最后一次读取租约时的活动副本；没有副本持有租约时为 null。
- namestringrequired
- urlstringrequired
- termintegerrequired
  minimum: 1
}
allowed_hostsoptionalarray | null
随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null（节点的 SecretHosts）。
problemsoptional数组，元素为object
随 invalid_definition 返回：定义中的每个问题，各附其位置和内容。
- atstringrequired
  在定义中的位置，用点分隔的路径 (services.web.port)；针对整个定义时为空。
- messagestringrequired
}
reportoptionalobject
随 compose_refused 返回：导入的报告，说明拒绝了什么、为什么以及要改什么。
- objectcompose_importrequired
- namestring | nullrequired
  模型的 name：即每个服务的标签 compose.project。null：模型没有名称。
- dry_runbooleanrequired
- strictbooleanrequired
- profiles数组，元素为stringrequired
- treatmentsobjectrequired
  报告中每种处理方式各有多少项。
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- items数组，元素为objectrequired
  模型的顶层元素：name，以及每个卷、网络、config、secret 和扩展。
  
  atstringrequired
  在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。
  
  treatmentdone或adapted或ignored或refusedrequired
  done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。
  
  whystringrequired
  changestring | nullrequired
  被拒绝的项：要改什么。其他情况为 null。
- services数组，元素为objectrequired
  导入所采纳的服务，按模型中的顺序。
  
  namestringrequired
  服务的名称，也是其应用的名称。
  
  app_idstring | nullrequired
  其应用。null：试运行，且项目中没有该服务。
  
  pattern: ^app-
  statuscreated或changed或unchangedrequired
  导入对其应用做了（试运行时为将会做）什么：创建、写入变化的部分，或什么都不做。
  
  kindservice或jobrequired
  job：模型中有服务等待它完成，它会在每次需要它的部署中运行到结束。
  
  statefulbooleanrequired
  它挂载自己的存储卷：只有一个实例，由该实例持有存储卷。
  
  versionbooleanrequired
  导入的部署是否为它创建版本：即解析引用后其版本的构成与当前版本不同。
  
  items数组，元素为objectrequired
  atstringrequired
  在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。
  
  treatmentdone或adapted或ignored或refusedrequired
  done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。
  
  whystringrequired
  changestring | nullrequired
  被拒绝的项：要改什么。其他情况为 null。
  
  appobjectrequired
  导入写入的服务应用字段：其版本的构成，以及立即生效的设置。
  
  imagestring | nullrequired
  应用下一个版本的构成，连同其后的七个字段：即其最新版本的构成，加上此后的修改。null：应用没有镜像，也没有版本。
  
  image_pull_secretstring | nullrequired
  保存镜像仓库凭据的机密的名称。任何响应都不包含其值。null：没有。
  
  start_commandrequired
  以下之一：
  StartCommand
  null
  start_argsrequired
  放在镜像 ENTRYPOINT 之后、取代其 CMD 的内容。null：使用镜像的 CMD，或者整个 start_command。
  
  以下之一：
  array<string>
  null
  portinteger | nullrequired
  readyobjectrequired
  判断实例已启动的方式，版本的模板会在实例启动后保存：三者必须恰好给出一个。前两种从实例外部检查，所以服务必须监听所有地址 (0.0.0.0)。
  
  httpoptionalstring
  一个以 / 开头的路径：在应用端口上对它发起 GET，返回 200 到 399 之间的状态码。
  
  tcpoptionaltrue
  应用端口接受连接。
  
  commandoptional
  在实例中执行成功的一条命令。由实例的 shell 运行：参数列表会被写成一行交给它。
  
  以下之一：
  string
  array<string>
  env映射，值为stringrequired
  secrets映射，值为stringrequired
  机密的名称。任何响应都不包含值。
  
  sizeobjectrequired
  单个实例最多能使用的资源。按实际用量计费。
  
  vcpusintegerrequired
  minimum: 1
  memory_bytesintegerrequired
  偶数个 MiB（即节点为虚拟机加载内存所用的 2 MiB 页的整数倍），以字节表示。其他任何大小都返回 400 invalid_field（param 为 size.memory_bytes）：没有节点会创建这种大小的实例，正如没有节点会创建这种大小的沙箱（节点的 SandboxLimitsCreate.memory_bytes）。
  
  minimum: 134217728
  volumes数组，元素为objectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  只有给出为 true 时才会出现。
  
  kindstringrequired
  files数组，元素为objectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  以下之一：
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regions数组，元素为stringrequired
  按 na、eu、ap 的顺序。
  
  scaleobjectrequired
  min_instancesintegerrequired
  无论有没有请求，应用在一个区域内保持运行的实例数：即下限。该区域服务该应用的节点按分摊 max_instances 的方式分摊它（两个节点、下限为 2：各一个；下限为 1：一个，在最先尝试的节点上；下限为 5：三个和两个），不在线的节点由其他节点补足。节点在收到通知时就创建自己那部分，而不是等到第一个请求，也不会因为空闲而停止或删除这些实例；它们按运行中的实例计量。0（未设置时的值）：没有下限。调低后，超出部分的实例从那一刻起视为空闲，并像空闲实例一样被停止和删除。最多为 max_instances（如果给出），且不超过账户套餐允许应用在一个区域请求的数量（caps.app_instances.limit：5、50 和 500）：超出会被拒绝，返回 403 plan_cap_reached。
  
  minimum: 0
  max_instancesinteger | nullrequired
  应用在一个区域内最多有多少个实例：由该区域服务该应用的节点分摊。最多为账户套餐允许应用请求的数量（caps.app_instances.limit：免费版 5，付费版 500）：超出会被拒绝，返回 403 plan_cap_reached；在允许的套餐上请求的数值会保留，但受当前套餐数值的限制。null：未指定数量的应用使用套餐的数值（caps.app_instances.default：免费版 2，付费版 50），如果 min_instances 更大则用它。告诉节点的数值，不超过账户除其他运行中资源外还能容纳的运行量，也不少于应用当前运行的实例数。
  
  minimum: 1
  concurrencyinteger | nullrequired
  单个实例同时处理的上限：边缘节点发给它的请求，加上它在项目网络上打开的连接（经由其服务的地址，节点会按连接把它们分给各个实例；或者直接连到它自己的地址）。达到上限的实例即为已满，更多的请求会创建新实例。null（未设置时的值）：没有上限。此时节点会在现有实例的 CPU 或内存接近其规格时增加实例，应用不必猜一个数字；一次只处理一个请求的服务应设为 1。
  
  maximum: 1000 · minimum: 1
  sleep_after_msinteger | nullrequired
  实例在没有请求时最多等待多久就停止，单位为毫秒。在这个上限以内，节点根据应用自己的流量选择等待时间：在应用最近一段时间里两次请求之间的间隔上，比较多运行一秒空闲与停止再恢复所花的 CPU 时间，选出成本最低的等待时间；这样，请求间隔比停止成本还短的应用会一直运行，请求间隔很长的应用则在最后一个响应结束后立即停止（0：总是立即停止）。null（未设置时的值）：平台的上限，三秒。设置过 100（2026年10月28日之前的默认值）的应用，从那天起视为 null。持续停止的实例会在 delete_after_ms 后被其节点删除，下一个需要实例的请求会得到一个新实例；min_instances 保持运行的实例既不会停止也不会删除。
  
  maximum: 600000 · minimum: 0
  sleep_notice_msinteger | nullrequired
  在实例因空闲而停止之前多久，向连接到其客户机 /run/sbx/awake 的程序发送一行 sleep N，单位为毫秒：程序可以借此写出手头的数据、关闭连接，或者发起保持，从而推迟停止。无论它们是否响应，停止都会在这段时间之后到来；没有程序连接时，不会推迟。键控实例也会收到通知。0 或 null：不通知（默认）。
  
  maximum: 60000 · minimum: 0
  sleep_hold_max_msintegerrequired
  实例中的程序发起的保持，在空闲时间到期后最多还能让实例运行多久，单位为毫秒：程序连接 /run/sbx/awake，如果某个请求在响应之后还有后续工作，就在响应它之前发送 +，工作完成后发送 -（或关闭连接，或退出）；最后一个保持解除 sleep_after_ms 之后，实例停止。超过这个时间，无论有什么保持，实例都会停止；如果 sleep_notice_ms 要求通知，会先向已连接的程序发送 sleep N cap。保持期间实例在运行，并按运行计量。0：不理会保持。null：30000（默认）。
  
  maximum: 900000 · minimum: 0
  delete_after_msinteger | nullrequired
  实例空闲多久后被删除，与停止使用同一个起算点：下一个需要实例的请求会得到一个新实例，即版本模板的克隆，不含被删除的实例在内存和磁盘中积累的东西（需要长久保存的数据请放在存储卷或数据库中）。一秒到一小时，一小时是平台的时间，也是上限：超出会被拒绝 (400 invalid_field)，需要保持预热的实例应计入 min_instances。null（未设置时的值）：节点的一小时 (--app-delete-after-seconds)。修改对应用现有的实例和之后创建的实例同样有效：每个节点至少每秒按应用当前的时间检查一次每个实例。不适用于应用的键控实例，键控实例用 keys.delete_after_idle_ms。
  
  maximum: 3600000 · minimum: 1000
  suspend_after_msoptionalinteger | null
  已停止的实例在保存内存并真正休眠之前保持暂停多久，单位为毫秒：暂停时，下一个请求在一两毫秒内得到响应，内存照常计量；休眠时，唤醒要多几毫秒，只计量它保存的数据。节点会把它限制在节点让任何实例保持暂停的最长时间内（十分钟）；宿主机内存不足、其他虚拟机需要占用槽位，或者有人请求休眠，都会让它更早休眠。null（默认）：节点的最长时间。数据库的 suspend_after_seconds 就是其应用的这一设置。
  
  maximum: 86400000 · minimum: 1000
  wake_daily_atoptionalstring | null
  每天的某个 UTC 时刻 (HH:MM)，在此时唤醒应用中处于休眠状态的键控实例和有状态服务的实例，让它们完成等待唤醒才能做的工作（比如数据库维护）；节点根据应用请求创建和删除的实例只会被请求唤醒。唤醒本身不算活动：唤醒后运行的东西才算，运行完毕后实例会再次休眠。此外，无论这里怎么设置，有状态服务的实例都会为其 PostgreSQL 服务器 pg_cron 任务的下一次运行而被唤醒。null（默认）：不唤醒。数据库的 wake_daily_at 就是其应用的这一设置。
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  keysrequired
  以下之一：
  object
  null
  egressobject | nullrequired
  与沙箱相同的出站规则（default、allow、deny、http、inject），没有时为 null；按调用给出的原样保存（PATCH 会像节点那样按键逐个合并）。规则立即生效，不产生新版本：服务该应用的节点会把它们应用到其组内的每个实例上，包括现有的实例（运行中的实例对其已有连接也生效）和之后创建的实例；键控实例不受这些规则约束。控制平面只检查它们是不是由这些键组成、不超过 256 KiB 的对象：规则的内容由节点在应用时检查，节点读不懂其规则的实例，所有出站流量都会被拒绝（节点日志会说明原因）。
  
  defaultoptionalallow或deny或null
  allowoptionalarray | null
  denyoptionalarray | null
  httpoptionalarray | null
  injectoptionalarray | null
  deny_portsoptionalarray | null
  任何连接都到达不了的端口，TCP 或 UDP，无论连往哪里，也无论规则的其他部分怎么说。浏览器会话的规则总是包含 25、465、587 以及矿池监听的端口（3333、4444、5555、7777、14444、45700）：无论其规则如何修改，控制平面都会把它们加上。
  
  metadata映射，值为stringrequired
  logsobjectrequired
  应用日志包含哪些内容，每一项为给出的值或默认值 (AppLogSettings)。
  
  outputbooleanrequired
  keepbooleanrequired
  requestsobjectrequired
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  keep_errorsbooleanrequired
  publicbooleanrequired
  是否在其默认域名 (url) 上响应。
  
  depends_on数组，元素为objectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliases数组，元素为stringrequired
  endpoint_modestringrequired
  drivesoptional数组，元素为object
  其实例挂载的云盘 (AppCreate.drives)：没有指定时为空列表 []。
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptional数组，元素为object
  每个键的实例自有的云盘 (AppCreate.key_drives)：没有给出时为空列表 []。
  
  namestringrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  format: int64
  nocopyoptionalunknown
  只有给出为 true 时才会出现。
  
  runtimeoptional
  运行时设置 (AppCreate.runtime)。null：没有。
  
  以下之一：
  Runtime
  ulimits映射，值为RuntimeLimitGivenrequired
  sysctls映射，值为stringrequired
  tmpfs数组，元素为objectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  servers数组，元素为stringrequired
  search数组，元素为stringrequired
  options数组，元素为stringrequired
  shm_size_bytesinteger | nullrequired
  null
  tracesoptionalobject
  应用请求的链路追踪包含哪些内容，每一项为给出的值或默认值 (AppTraceSettings)：sample_rate 为 0 时不产生任何 span。
  
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  trust_incomingbooleanrequired
- volumes数组，元素为objectrequired
  服务挂载的项目存储卷。
  
  modelstring | nullrequired
  它在模型中的名称。null：为有状态服务挂载但未命名卷的路径创建的。
  
  namestringrequired
  它在项目中的名称。
  
  idstring | nullrequired
  null：尚未创建 (to_make)。
  
  pattern: ^vol-
  sharedbooleanrequired
  有多个服务挂载它，或者某个服务有多个实例：每个服务的每个实例同时挂载它。
  
  statusto_make或made或there或externalrequired
  to_make：导入会创建它（试运行时对将要创建的存储卷这样说明）；made：本次导入创建了它；there：之前的导入创建了它，或者已有同名的存储卷；external：模型把它标为 external，而项目中已有它。
  
  used_by数组，元素为stringrequired
- secrets数组，元素为objectrequired
  模型中授予服务的 secrets。
  
  modelstringrequired
  它在模型中的名称。
  
  namestringrequired
  保存它的项目机密：即模型中的名称，其中机密名称不允许的每个字符都写成下划线。
  
  therebooleanrequired
  项目中是否已有它。导入（非试运行）时如果它还不存在，会被拒绝，返回 404 secret_not_found。
  
  used_by数组，元素为stringrequired
- left_out数组，元素为objectrequired
  属于未启用 profile 的服务，导入不会处理它们。
  
  namestringrequired
  profiles数组，元素为stringrequired
- absent数组，元素为stringrequired
  项目中有而模型中没有的服务：保持原样。
- deploystring | nullrequired
  导入触发的部署 (GET /v1/deploys/{id})。null：试运行，或者没有服务需要新版本。
  
  pattern: ^dpl-
}
accountsoptional数组，元素为object
随 sole_owner 返回：该用户是唯一所有者的那些账户。
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}

403

凭据无权执行此操作。needs_api_key：沙箱令牌不能执行此操作。secret_host_not_allowed：机密会被发往它不允许去的主机：通过 egress.inject（给出的规则，或快照中的规则），或作为 image_pull_secret 发往 image 的镜像仓库（param 指明是哪一个；与 error 并列的 allowed_hosts 列出它可以去的地方）。account_share_reached：账户在本节点数据盘上占用的空间已达到单个账户的上限（见 GET /internal/node 的 drive.accounts），放不下沙箱的内存外加 1 GB 的写入空间；错误信息会说明它在这里已占用多少、上限是多少。没有创建任何东西。

JSON

errorobjectrequired
- typestringrequired
  失败的类别。它决定状态码：invalid_request 400、unauthenticated 401、forbidden 403、not_found 404、conflict 409、too_large 413、internal 500、bad_gateway 502（预览监听器、出站代理，以及无法带回其沙箱的接管）、unavailable 503、timeout 504。
- codestringrequired
  具体是哪种失败。本文档顶层的 x-error-codes 表说明了每一个的含义。
- messagestringrequired
  给人看的说明。英文。
- paramstring | nullrequired
  出错的字段或查询参数（如果有）。
- retryablebooleanrequired
  在其他条件都不变的情况下，同一请求稍后可能成功时为 true。
- request_idstringrequired
  所在响应的 X-Request-Id，响应是针对 Idempotency-Key 的重放时也一样。
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  节点的 --docs-url 加上错误码，或者为 null。
}
allowed_hostsoptionalarray | null
随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null。
tooptionalstring | null
随 moved 和 sandbox_moved 返回：沙箱被交给的节点，以控制平面给它起的名称为准，或者为 null。
epochoptionalinteger
随 moved 和 sandbox_moved 返回：沙箱被释放时的纪元。随 wrong_epoch 返回：本节点持有它或释放它时的纪元。

format: int64 · minimum: 1
offsetoptionalinteger
随 sandbox_moved 返回：调用、事件流或终端在命令输出中已读到的位置（事件流最后一个事件的 id）：在沙箱去往的地方从这里接着读（Last-Event-ID，或 from）。

format: int64 · minimum: 0
exec_idoptionalstring
随 POST …/run 的 sandbox_moved 返回：调用启动并在等待的命令的 id，命令在沙箱去往的地方继续运行：迁移结束后，通过控制平面用 GET …/exec/{exec_id}?wait_seconds= 在那里等待它。再次发起同一调用会再启动一次命令，除非带着同一个 Idempotency-Key。
disk_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存到休眠时的磁盘所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
memory_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存那次休眠的内存镜像所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
drives_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱云盘的当前状态所等的时长，单位为毫秒 (slice D2)；没有等待或没有云盘时为 null。

minimum: 0
image_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱磁盘所基于的镜像所等的时长，单位为毫秒（其节点会在模板的镜像上传之前就复制磁盘）；没有等待时为 null。

minimum: 0
imageoptionalstring
随 image_missing 返回：对象存储中没有的镜像的 id，与基于它的磁盘和模板的 disk_image 中的名称一致。

pattern: ^[A-Za-z0-9_-]{1,128}$
buildoptionalstring
随 build_missing 返回：写下沙箱内存的 Firecracker 构建版本，本节点没有保留它。

pattern: ^[0-9a-f]{16}$

404

请求中指定的对象不存在。snapshot_not_found：快照不存在；template_not_found：模板不存在；volume_not_found：volumes 中指定的某个存储卷不存在；secret_not_found：egress.inject 中指定的机密，或 image_pull_secret 指定的机密不存在。

JSON

errorobjectrequired
- typestringrequired
  失败的类别。它决定状态码：invalid_request 400、unauthenticated 401、forbidden 403、not_found 404、conflict 409、too_large 413、internal 500、bad_gateway 502（预览监听器、出站代理，以及无法带回其沙箱的接管）、unavailable 503、timeout 504。
- codestringrequired
  具体是哪种失败。本文档顶层的 x-error-codes 表说明了每一个的含义。
- messagestringrequired
  给人看的说明。英文。
- paramstring | nullrequired
  出错的字段或查询参数（如果有）。
- retryablebooleanrequired
  在其他条件都不变的情况下，同一请求稍后可能成功时为 true。
- request_idstringrequired
  所在响应的 X-Request-Id，响应是针对 Idempotency-Key 的重放时也一样。
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  节点的 --docs-url 加上错误码，或者为 null。
}
allowed_hostsoptionalarray | null
随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null。
tooptionalstring | null
随 moved 和 sandbox_moved 返回：沙箱被交给的节点，以控制平面给它起的名称为准，或者为 null。
epochoptionalinteger
随 moved 和 sandbox_moved 返回：沙箱被释放时的纪元。随 wrong_epoch 返回：本节点持有它或释放它时的纪元。

format: int64 · minimum: 1
offsetoptionalinteger
随 sandbox_moved 返回：调用、事件流或终端在命令输出中已读到的位置（事件流最后一个事件的 id）：在沙箱去往的地方从这里接着读（Last-Event-ID，或 from）。

format: int64 · minimum: 0
exec_idoptionalstring
随 POST …/run 的 sandbox_moved 返回：调用启动并在等待的命令的 id，命令在沙箱去往的地方继续运行：迁移结束后，通过控制平面用 GET …/exec/{exec_id}?wait_seconds= 在那里等待它。再次发起同一调用会再启动一次命令，除非带着同一个 Idempotency-Key。
disk_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存到休眠时的磁盘所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
memory_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存那次休眠的内存镜像所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
drives_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱云盘的当前状态所等的时长，单位为毫秒 (slice D2)；没有等待或没有云盘时为 null。

minimum: 0
image_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱磁盘所基于的镜像所等的时长，单位为毫秒（其节点会在模板的镜像上传之前就复制磁盘）；没有等待时为 null。

minimum: 0
imageoptionalstring
随 image_missing 返回：对象存储中没有的镜像的 id，与基于它的磁盘和模板的 disk_image 中的名称一致。

pattern: ^[A-Za-z0-9_-]{1,128}$
buildoptionalstring
随 build_missing 返回：写下沙箱内存的 Firecracker 构建版本，本节点没有保留它。

pattern: ^[0-9a-f]{16}$

409

某个对象的状态不允许此操作。name_taken：名称已被占用；volume_in_use：volumes 中某个非共享存储卷属于另一个沙箱；duplicate_volume：某个存储卷在 volumes 中出现了两次；mount_path_taken：volumes 中有两个存储卷的 path 相同；too_many_volumes：volumes 中非共享存储卷的数量超过了沙箱所在机器的空余磁盘数（八个；从早于八个磁盘时期的模板或快照创建的沙箱为两个）；snapshot_lost：快照的 status 为 lost；no_project_address：请求了 project_network，但节点上没有该项目的网络，或者网络中已没有空余地址，或者 project_address 指定的地址在此期间被另一个沙箱占用了；sandbox_failed：沙箱的模板推迟了启动命令 (TemplateBuildRequest.start_after_volumes)，而存储卷挂载后命令没能启动：错误信息会给出它最后打印的内容，不保留任何东西；idempotency_key_reused：该键已与另一个请求体一起使用过；idempotency_in_progress：使用该键的第一个请求仍在执行。volume_restoring：它指定的某个存储卷正在从备份创建，或者没能创建成功。checkpoints_unavailable（param 为 checkpoint）：开启了 checkpoint，但本节点不支持检查点（它不把磁盘复制到对象存储，或者它的内存不分层）。

JSON

errorobjectrequired
- typestringrequired
  失败的类别。它决定状态码：invalid_request 400、unauthenticated 401、forbidden 403、not_found 404、conflict 409、too_large 413、internal 500、bad_gateway 502（预览监听器、出站代理，以及无法带回其沙箱的接管）、unavailable 503、timeout 504。
- codestringrequired
  具体是哪种失败。本文档顶层的 x-error-codes 表说明了每一个的含义。
- messagestringrequired
  给人看的说明。英文。
- paramstring | nullrequired
  出错的字段或查询参数（如果有）。
- retryablebooleanrequired
  在其他条件都不变的情况下，同一请求稍后可能成功时为 true。
- request_idstringrequired
  所在响应的 X-Request-Id，响应是针对 Idempotency-Key 的重放时也一样。
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  节点的 --docs-url 加上错误码，或者为 null。
}
allowed_hostsoptionalarray | null
随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null。
tooptionalstring | null
随 moved 和 sandbox_moved 返回：沙箱被交给的节点，以控制平面给它起的名称为准，或者为 null。
epochoptionalinteger
随 moved 和 sandbox_moved 返回：沙箱被释放时的纪元。随 wrong_epoch 返回：本节点持有它或释放它时的纪元。

format: int64 · minimum: 1
offsetoptionalinteger
随 sandbox_moved 返回：调用、事件流或终端在命令输出中已读到的位置（事件流最后一个事件的 id）：在沙箱去往的地方从这里接着读（Last-Event-ID，或 from）。

format: int64 · minimum: 0
exec_idoptionalstring
随 POST …/run 的 sandbox_moved 返回：调用启动并在等待的命令的 id，命令在沙箱去往的地方继续运行：迁移结束后，通过控制平面用 GET …/exec/{exec_id}?wait_seconds= 在那里等待它。再次发起同一调用会再启动一次命令，除非带着同一个 Idempotency-Key。
disk_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存到休眠时的磁盘所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
memory_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存那次休眠的内存镜像所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
drives_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱云盘的当前状态所等的时长，单位为毫秒 (slice D2)；没有等待或没有云盘时为 null。

minimum: 0
image_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱磁盘所基于的镜像所等的时长，单位为毫秒（其节点会在模板的镜像上传之前就复制磁盘）；没有等待时为 null。

minimum: 0
imageoptionalstring
随 image_missing 返回：对象存储中没有的镜像的 id，与基于它的磁盘和模板的 disk_image 中的名称一致。

pattern: ^[A-Za-z0-9_-]{1,128}$
buildoptionalstring
随 build_missing 返回：写下沙箱内存的 Firecracker 构建版本，本节点没有保留它。

pattern: ^[0-9a-f]{16}$

503

不可用。not_served_here：给出了 egress 规则，但本节点无法执行规则（它没有 nft）；或者请求了 project_network，但本节点不把沙箱放进项目网络；或者沙箱要从节点没有模板的 image 创建，而本节点不拉取镜像（原因见 GET /internal/node 的 image_pulls；param 为 image）；或者 key_missing：本节点启用了加密 (src/seal.rs)，却没有所属项目的密钥或平台的密钥（错误信息会说明是哪一个）：控制平面会提供密钥，之后再次发起同一调用即可 (Retry-After)；或者 unavailable：volumes 中的某个存储卷没能及时挂载，稍后再次发起同一调用即可 (Retry-After)：客户机没能在 60 秒内完成挂载（云盘的数据块迟迟不来：对象存储不在线，或取块程序连不上），或者这样的挂载之后它仍在从机器上卸下，或者它是逐块传来的云盘，而它的数据块暂时没有任何来源响应。

JSON

errorobjectrequired
- typestringrequired
  失败的类别。它决定状态码：invalid_request 400、unauthenticated 401、forbidden 403、not_found 404、conflict 409、too_large 413、internal 500、bad_gateway 502（预览监听器、出站代理，以及无法带回其沙箱的接管）、unavailable 503、timeout 504。
- codestringrequired
  具体是哪种失败。本文档顶层的 x-error-codes 表说明了每一个的含义。
- messagestringrequired
  给人看的说明。英文。
- paramstring | nullrequired
  出错的字段或查询参数（如果有）。
- retryablebooleanrequired
  在其他条件都不变的情况下，同一请求稍后可能成功时为 true。
- request_idstringrequired
  所在响应的 X-Request-Id，响应是针对 Idempotency-Key 的重放时也一样。
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  节点的 --docs-url 加上错误码，或者为 null。
}
allowed_hostsoptionalarray | null
随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null。
tooptionalstring | null
随 moved 和 sandbox_moved 返回：沙箱被交给的节点，以控制平面给它起的名称为准，或者为 null。
epochoptionalinteger
随 moved 和 sandbox_moved 返回：沙箱被释放时的纪元。随 wrong_epoch 返回：本节点持有它或释放它时的纪元。

format: int64 · minimum: 1
offsetoptionalinteger
随 sandbox_moved 返回：调用、事件流或终端在命令输出中已读到的位置（事件流最后一个事件的 id）：在沙箱去往的地方从这里接着读（Last-Event-ID，或 from）。

format: int64 · minimum: 0
exec_idoptionalstring
随 POST …/run 的 sandbox_moved 返回：调用启动并在等待的命令的 id，命令在沙箱去往的地方继续运行：迁移结束后，通过控制平面用 GET …/exec/{exec_id}?wait_seconds= 在那里等待它。再次发起同一调用会再启动一次命令，除非带着同一个 Idempotency-Key。
disk_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存到休眠时的磁盘所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
memory_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存那次休眠的内存镜像所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
drives_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱云盘的当前状态所等的时长，单位为毫秒 (slice D2)；没有等待或没有云盘时为 null。

minimum: 0
image_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱磁盘所基于的镜像所等的时长，单位为毫秒（其节点会在模板的镜像上传之前就复制磁盘）；没有等待时为 null。

minimum: 0
imageoptionalstring
随 image_missing 返回：对象存储中没有的镜像的 id，与基于它的磁盘和模板的 disk_image 中的名称一致。

pattern: ^[A-Za-z0-9_-]{1,128}$
buildoptionalstring
随 build_missing 返回：写下沙箱内存的 Firecracker 构建版本，本节点没有保留它。

pattern: ^[0-9a-f]{16}$

default

其他任何失败，格式相同。internal (500)：节点出错；错误信息不会多说，节点日志中以请求的 id 记录了原因。unavailable（503，可重试）：no_capacity，节点的网络槽位都已占用；memory_full，调用需要启动的虚拟机（创建、唤醒、从磁盘启动、恢复、回滚、构建）在宿主机内存中放不下（还要算上已承诺给其上运行的虚拟机的内存），也没有暂停或空闲的虚拟机可以让其休眠来腾出空间（节点的 memory）；drive_full，调用需要构建模板，而节点的数据盘没有空间（节点的 drive）；unavailable，节点正在关闭、沙箱 10 分钟后仍处于 starting、沙箱没有响应，或者沙箱正在迁到本节点（带 Retry-After: 1）；fenced，节点的租约隔离了该沙箱 (Node.lease)。moved (409)：沙箱已迁到另一个节点，由 to 指明。

JSON

errorobjectrequired
- typestringrequired
  失败的类别。它决定状态码：invalid_request 400、unauthenticated 401、forbidden 403、not_found 404、conflict 409、too_large 413、internal 500、bad_gateway 502（预览监听器、出站代理，以及无法带回其沙箱的接管）、unavailable 503、timeout 504。
- codestringrequired
  具体是哪种失败。本文档顶层的 x-error-codes 表说明了每一个的含义。
- messagestringrequired
  给人看的说明。英文。
- paramstring | nullrequired
  出错的字段或查询参数（如果有）。
- retryablebooleanrequired
  在其他条件都不变的情况下，同一请求稍后可能成功时为 true。
- request_idstringrequired
  所在响应的 X-Request-Id，响应是针对 Idempotency-Key 的重放时也一样。
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  节点的 --docs-url 加上错误码，或者为 null。
}
allowed_hostsoptionalarray | null
随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null。
tooptionalstring | null
随 moved 和 sandbox_moved 返回：沙箱被交给的节点，以控制平面给它起的名称为准，或者为 null。
epochoptionalinteger
随 moved 和 sandbox_moved 返回：沙箱被释放时的纪元。随 wrong_epoch 返回：本节点持有它或释放它时的纪元。

format: int64 · minimum: 1
offsetoptionalinteger
随 sandbox_moved 返回：调用、事件流或终端在命令输出中已读到的位置（事件流最后一个事件的 id）：在沙箱去往的地方从这里接着读（Last-Event-ID，或 from）。

format: int64 · minimum: 0
exec_idoptionalstring
随 POST …/run 的 sandbox_moved 返回：调用启动并在等待的命令的 id，命令在沙箱去往的地方继续运行：迁移结束后，通过控制平面用 GET …/exec/{exec_id}?wait_seconds= 在那里等待它。再次发起同一调用会再启动一次命令，除非带着同一个 Idempotency-Key。
disk_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存到休眠时的磁盘所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
memory_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存那次休眠的内存镜像所等的时长，单位为毫秒；没有等待时为 null。

minimum: 0
drives_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱云盘的当前状态所等的时长，单位为毫秒 (slice D2)；没有等待或没有云盘时为 null。

minimum: 0
image_msoptionalnumber | null
随 copy_behind 返回：释放时为等待对象存储保存沙箱磁盘所基于的镜像所等的时长，单位为毫秒（其节点会在模板的镜像上传之前就复制磁盘）；没有等待时为 null。

minimum: 0
imageoptionalstring
随 image_missing 返回：对象存储中没有的镜像的 id，与基于它的磁盘和模板的 disk_image 中的名称一致。

pattern: ^[A-Za-z0-9_-]{1,128}$
buildoptionalstring
随 build_missing 返回：写下沙箱内存的 Firecracker 构建版本，本节点没有保留它。

pattern: ^[0-9a-f]{16}$