复制运行中的沙箱

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

其升级连接能让它保持运行的端口；只有这些端口（加上它的请求和调用）决定它是否空闲 (SandboxCreate)；与其他沙箱判断空闲方式相同的沙箱为空。

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

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

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

浏览器镜像的沙箱（带有标签 sbx.devtools 的镜像，即其浏览器 DevTools 协议的端口）：浏览器自己的地址，由节点在构建该镜像的模板时询问得到 (/json/version)。浏览器属于模板，从该模板创建的每个沙箱中都相同，沙箱去到哪里它就跟到哪里。只接受 WebSocket 地址的客户端，连接到 port 签名链接上的 path。其他沙箱为 null。

它自己的代理（SandboxCreate 的 proxy）：其地址以及请求时使用的用户名，从不包含密码。没有时为 null。

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

对于应用的实例（节点根据应用请求创建和删除的那种，PUT /internal/apps/{key}）：该应用，按其模板的键，以节点的盘点为准。其他沙箱为 null，包括应用的键控实例（其 metadata 说明了其应用和键）。控制平面如果最先在某个调用的响应中看到某个实例，就靠这个字段把它排除在边缘节点的表之外，与对待节点盘点中列出的实例一样。

它自有的公网 IPv6 地址，在其整个生命周期内不变：它通过 IPv6 发送的流量从这个地址发出，不做地址转换，发往它的流量按 inbound 的设置放行。在有地址池的节点上创建时分配；休眠、快照和迁移后都保留；分叉出的沙箱或从快照创建的沙箱有自己的地址。null：只有 IPv4（其节点没有地址池，或者其模板中的代理程序早于自有地址功能）。

在 ipv6 上向互联网开放的端口，各附其开放的来源，按协议和端口排序。默认关闭：为空。

其运行期间的检查点（SandboxCreate 的 checkpoint）及其进展；没有启用时为 null。

创建时 secret_env 中变量的名称，按顺序；从不包含值。创建时没有给出时为空。

调用方给它起的名称，或者为 null。

仅供参考：调用之前不必查看它。starting：正在拉取并构建其镜像，需要它的调用会等待。sleeping：内存已保存，什么都没有在运行（只剩磁盘的沙箱，以及暂停在节点内存中的沙箱，也显示为此状态：sleep_tier 会说明是哪一种）；下一个需要它的调用会唤醒它。failed：无法构建或唤醒，或者节点的宿主机宕机后无法读取它在节点上的记录，需要它的调用会返回 409 sandbox_failed。修改它的调用（创建、休眠、重启、恢复）的响应，显示的是该调用留下的状态。

sleeping 状态的沙箱以何种方式休眠；其他状态为 null。paused：其虚拟机连同进程和连接静止在节点的内存中（开启了暂停层级的节点会暂停空闲的沙箱，而不是保存它），调用会在约一毫秒内恢复它；其虚拟机占用的内存像运行中的沙箱一样计量（usage.memory_bytes、memory_gib_seconds），CPU 不计量。saved：其内存和设备状态保存在节点上，什么都没有在运行；调用会在几毫秒内从中唤醒它。disk：只剩下磁盘（其虚拟机自行结束了，节点守护进程没有让它休眠就结束了，或者其内存无法保留）；下一个需要它的调用会从磁盘启动它，原来运行的东西都已不在。POST /v1/sandboxes/{id}/sleep 会保存沙箱，无论它是暂停的还是在运行的。

沙箱为何处于 failed，用一句话给人看；其他情况为 null。它不会提到节点的任何内容：没有路径，也没有工具日志中的行。如果镜像仓库拒绝了所用的凭据，会附上仓库的原话，其中的凭据已去掉。

沙箱为何处于 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：其他任何情况；节点日志中有记录。

沙箱所对应的 OCI 镜像引用。只有在基础模板是从磁盘文件构建的节点上才为 null。

沙箱最后一次采用其状态的快照的 id：即创建它所依据的快照，或它被恢复到的快照。从镜像创建的沙箱为 null。该快照被删除后不会清空；对于分叉，它指向分叉自己的临时快照，调用返回时那个快照已经不在了。

供调用方自用的任意键值对；沙箱列表可以按它们筛选。最多 64 个键，每个键 1 到 64 个字符，值最多 1024 个字符。不要在这里存放机密：元数据以明文保存，沙箱在产生用量期间有过的每组元数据都会随其用量保留十三个月，沙箱删除后也一样（GET /v1/usage 按它们分组和筛选）。

预览 URL 不需要签名和令牌的端口。重复的端口按给出的原样保留。

除这些端口外，其他所有端口也都公开，就像在 public_ports 中一样 (SandboxCreate)；没有设置时为 null。控制平面的 E2B 兼容层创建的沙箱为 [49983]：其端口与 E2B 的一样公开，envd 的端口需要沙箱的令牌。

沙箱存储下来的出站规则：它可以访问什么、可以向某个主机请求什么，以及它的哪些请求会被加上机密。总是存在；没有规则的沙箱，default 为 allow，四个列表为空，其流量走的是没有规则时的路径。deny 涉及的连接或数据包会被拒绝；allow 涉及的会放行；其他的按 default 处理。inject 中的主机视为允许，http 中的主机对其条目允许的请求也视为允许。无论规则怎么说，沙箱都访问不到节点、其他沙箱、私有地址段以及各云平台的元数据地址。

主机名会与 TLS 握手的服务器名称、HTTP 请求的 Host 头匹配（任何端口），也会与沙箱的 DNS 查询匹配；对于规则可以拒绝某个名称的沙箱，节点会自己回答其 DNS 查询（被拒绝的名称得到 REFUSED）。指明某个允许主机的连接，会发往节点为该名称解析出的地址，无论沙箱原本要连哪个地址。既不是 TLS 也不是 HTTP 的 TCP 连接，只有发往规则列出的地址，或节点作为某个允许名称的地址告诉沙箱的地址时，才会放行。UDP 和其他所有协议只按地址判断。在 default: allow 下，deny 列表算不上一堵墙：任何允许的中转流量都能绕过它。

沙箱空闲多少秒后休眠。null：从不自行休眠。由调用方设置时至少为 1；应用的实例使用其应用的设置（PUT /internal/apps/{key} 的 sleep_after_ms），可能更短。

沙箱自行删除的时间（或按 on_expiry 的设置处理）。null：永不。

expires_at 到时做什么：delete，删除沙箱（默认）；sleep，让它休眠（不管里面在做什么）并保留它，此后其 expires_at 为 null；hold，同上，但保持休眠（设置 held_asleep）。控制平面的 E2B 兼容层会给到期即暂停的沙箱设置 sleep 或 hold。

休眠且不会被请求唤醒（E2B 的已暂停沙箱，控制平面的 E2B 兼容层在其 pause 和 connect 之间这样保持它）：休眠期间，发往其端口的请求不会唤醒它，预览监听器会代为返回 502 sandbox_paused (x-preview-ingress)。API 调用照常会唤醒它，它自己的定时器也会；它运行时到来的请求会照常交给它。

在空闲规则让它休眠之前多久，通知连接到其客户机 /run/sbx/awake 的程序，单位为毫秒 (SandboxCreate)；null：不通知。

其客户机的保持最多能让它保持运行多久，单位为毫秒 (SandboxCreate)：它自己的设置，或节点的设置。保持期间，awake_because 会说明。

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

休眠期间节点每天唤醒它的 UTC 时刻 (SandboxCreate)；null：不唤醒。

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

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

虚拟机的规格：其创建请求在 limits 中要求的规格，没有给出的部分取节点基础模板的值；从快照或模板创建的沙箱沿用其规格。磁盘大小对每个沙箱都由节点决定。

客户机内核是否保留针对推测执行的缓解措施（创建时的 guest_mitigations）。

其 /tmp 放在哪里（创建时的 tmp）：磁盘上，或客户机内存中的 tmpfs，后者按内存计费，沙箱从磁盘重新启动时会消失。从快照创建的沙箱沿用快照所属沙箱的设置。

虚拟机最后一次从零启动的时间：创建时，以及每次从磁盘重启后。休眠和唤醒不会改变它。

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

运行中的沙箱为什么还没有被休眠，用几个词说明。status 不是 running 时为 null。应用的实例给出节点提供的原因：手头有请求、有调用在进行中、有请求在不到其 sleep_after_seconds 之前刚结束，或者其应用的下限让它保持运行。被项目网络上的数据包唤醒、之后再没有别的东西让它保持运行的沙箱，会说明这一点以及是哪个数据包：woken by a packet: TCP from 10.64.0.7:41594 to port 5432 [S] …。项目内部的连接不会让任何沙箱保持运行：在它休眠期间经由这些连接到来的数据，由节点暂存 (Node.hold)。

沙箱已经使用和正在使用的资源。

沙箱最近一次因所在宿主机而丢失了什么，以及原因 (cause)：宿主机硬宕机（断电、内核崩溃）时丢失其内存，以节点恢复后发现的情况为准；或者节点重启时使用的 Firecracker 与保存内存时的不同，而沙箱随后被使用，从而丢失其内存。什么都没有丢失的沙箱为 null：没有经历过上述任何一种情况的，以及休眠时所需的一切都在宿主机磁盘上的沙箱，后者在保持原样的节点上会照常唤醒。在下一次这样的丢失之前，它保持不变。

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

持有它的节点所在的区域，以节点被告知的为准 (--region)：即控制平面把它放在了哪里。在不属于任何区域的节点上为 null。

其磁盘从对象存储取回（恢复、迁移到本节点，或在本节点从其他节点创建的快照创建沙箱，其磁盘在对象存储中）并能够响应的时刻：其节点已拥有它，并且对于按读取逐步填充的磁盘，已有程序在监听尚未到达的数据块。磁盘在其节点上创建的沙箱为 null。每次这样的到达都会让这四个字段重新开始。

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

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

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

其磁盘今天 (UTC) 写入的数据量，与当天全速写入的份额对照：超出份额后，其磁盘的写入会变慢直到当天结束，但写入都不会失败。在不把磁盘复制到对象存储的节点上为 null，这种节点不统计也不限速；静态实例 (SandboxInternals.static) 的磁盘不复制，也为 null。

控制平面某个应用的实例（SandboxCreate.instance_of：沙箱产品的应用，control/src/sandboxes.rs）：该应用，以控制平面给它起的名称为准，在沙箱整个生命周期内不变。其他沙箱没有这个字段。

有 app_id 时：其创建请求所要求的应用版本，以控制平面给它起的名称为准。经由控制平面时，为创建它所用镜像的版本 (image_digest)：在应用下移动标签会产生一个独立的版本。

有 app_id 时：在应用的实例中用来查找它的依据，即其名称，没有名称时为其 id。

沙箱的环境变量及其值。调用方是不带 exec、files、tty 任何权限范围的沙箱令牌时，没有这个字段（而不是 null）：这些值往往是凭据，用于访问沙箱链接的令牌不应能看到它们。

其 PID 1 是什么（创建时的 init）：systemd，其镜像自己的 systemd（完整的系统），或者 null，平台的 init。从快照创建的沙箱或分叉出的沙箱，沿用快照所属沙箱的设置。完整的系统有自己的机器 ID（/etc/machine-id，以及 D-Bus 的副本 /var/lib/dbus/machine-id），在其虚拟机创建时分配（克隆模板或快照、分叉、从快照的磁盘启动），此后在休眠、唤醒、迁移和从磁盘启动时都保持不变；其 journal 按它归档 (/var/log/journal/)。

为该沙箱的预览链接签名的机密。调用方是沙箱令牌时没有这个字段（而不是 null）。

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

失败的类别。它决定状态码：invalid_request 400、unauthenticated 401、forbidden 403、not_found 404、conflict 409、too_large 413、internal 500、bad_gateway 502（预览监听器、出站代理，以及无法带回其沙箱的接管）、unavailable 503、timeout 504。

具体是哪种失败。本文档顶层的 x-error-codes 表说明了每一个的含义。

给人看的说明。英文。

出错的字段或查询参数（如果有）。

在其他条件都不变的情况下，同一请求稍后可能成功时为 true。

所在响应的 X-Request-Id，响应是针对 Idempotency-Key 的重放时也一样。

节点的 --docs-url 加上错误码，或者为 null。