在新建沙箱中运行一条命令

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

让请求可以安全地重发。见简介中的“Idempotency-Key”一节。

字符串是交给 sh -c 的一行命令；列表按原样运行，不经过 shell，第一个词像 shell 那样查找：沿着命令自身环境中的 PATH（镜像的，加上 env 的设置）。最多 1000 个参数，不能含 NUL 字节。

true：虚拟机启动时运行镜像自己的启动命令（ENTRYPOINT 和 CMD）；false：不启动任何东西，无论镜像的标签要求什么。只要给出了（start、start_command 和 ready 中的任何一个），就只以它为准：不读取镜像的标签 sbx.start 和 sbx.ready。沙箱从用这些设置和 env 构建的模板创建（同一镜像的两种设置就是两个模板；某种设置的第一个沙箱在构建期间以 starting 返回），只有其所有者的沙箱会从这个模板创建。不适用于从 snapshot 或 template 创建的沙箱 (400 invalid_start)。

启动命令，以镜像的用户身份运行，其输出由沙箱的代理程序作为命令 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。

沙箱模板的虚拟机何时算作已启动：只有这项检查通过后，节点才会保存模板（使用这些设置的每个沙箱都从它克隆），这样每个沙箱中的服务从一开始就在运行。三者选一。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)。不给出时：不等待，直接保存模板。

沙箱可以访问什么，以及它的哪些请求会被加上机密，与 SandboxCreate 中相同。

客户机内核是否保留针对推测执行的缓解措施。它们保护客户机内核不受同一沙箱中进程的攻击：当一个沙箱运行多个互不信任的用户的代码时，请开启它们。无论如何，宿主机都会把各沙箱相互隔离。默认：节点的设置（关闭）。该设置在内核启动时确定：第一个设置与其镜像模板不同的沙箱，会像新镜像一样启动（以 starting 返回），从快照创建的沙箱沿用快照的设置（请求另一种设置会返回 400）。

沙箱的 /tmp 放在哪里。disk：与其他部分一样放在磁盘上。memory：最多占其内存一半的 tmpfs，在第一个命令之前挂载（对从模板或镜像创建的沙箱，覆盖在模板客户机放在那里的内容之上；从其磁盘启动时由客户机的 init 挂载）：写在那里的内容占用客户机的内存，按内存计费，休眠时保留，从磁盘重新启动时消失。如果快照所属的沙箱把它放在内存中，从该快照创建的沙箱无论这里怎么设置也都放在内存中。

其虚拟机及其命令的运行时设置，与 Compose 文件中的 ulimits、sysctls、tmpfs、dns 和 shm_size 一样 (Runtime)。对从镜像创建的沙箱：会用这些设置为调用方构建一个专属模板（没有指定启动方式时，按镜像的标签启动镜像）。从快照或模板创建的沙箱会被拒绝 (400 invalid_start)，它们沿用其虚拟机已有的设置。

沙箱的 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」）。

true：沙箱在运行任何东西之前就接入其项目的私有网络，使用节点为该项目预留的第一个空余地址 (setProjectNetwork)：响应会给出是哪个地址 (project_address)。项目就是调用的所有者，所以这是供控制平面代项目发起的调用使用的；在独立运行的节点上，沙箱不属于任何人，要接入网络需要在网络中指定它。沙箱除非提出请求，否则不会接入任何项目网络：默认 false。分叉出的副本不接入任何网络，无论原沙箱在哪个网络中。

OCI 镜像引用（python:3.12、ghcr.io/org/app@sha256:…），位于互联网上的镜像仓库：可以是对所有人开放的仓库，也可以是需要登录的仓库（配合 image_pull_secret）。某个镜像的第一个沙箱在节点拉取镜像并构建模板期间以 starting 返回；之后的沙箱从模板启动。默认：节点的基础镜像。

保存非公开镜像所在仓库凭据的机密 (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）。

快照的 id 或名称：沙箱从创建快照的那一刻继续运行，包括其进程。

节点上模板的键（base、img-…），与 GET /internal/node 列出的一致。参考 README 中没有记录；基准测试脚本会用到它。

创建请求所要求的规格。没有给出（或为 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。

调用方为沙箱、快照、存储卷或 SSH 密钥起的名称：1 到 63 个小写字母、数字和连字符，不能以连字符开头或结尾，也不能以 id 前缀开头（sbx-、exe-、snap-、vol-、evt-、req-；SSH 密钥还不能以 sshkey- 开头）。即一个不会被误认为 id 的 DNS 标签。在沙箱、快照、存储卷和 SSH 密钥各自的范围内唯一。

为这个命令添加到沙箱 env 中的变量；同名时以这里的为准。

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

在调用返回之前挂载的存储卷。非共享的最多两个。

任何人都可以通过其短预览 URL 打开的端口。

除这些端口外，其他所有端口也都公开：其短预览 URL 对任何人开放，与 public_ports 中的端口一样（这是 E2B 处理沙箱端口的方式；控制平面的 E2B 兼容层给出 [49983]，即 envd 的端口，用沙箱令牌打开）。[]：所有端口。null（默认）：只有 public_ports。端口按顺序，每个只取一次。

从一开始就在沙箱自有 IPv6 地址上向互联网开放的端口，各附其来源（之后可用 …/tcp/{port} 开放）。没有地址池的节点会拒绝非空列表：409 no_ipv6。

空闲多少秒后休眠。null：从不自行休眠。默认值为节点的设置（--sleep-after-seconds，未设置时为 30）。

在这个时间删除沙箱，必须是将来的时间（或者按 on_expiry 的设置处理）。null 或不给出：永不。

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

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

与 SandboxCreate 中相同：接受，但不起作用，因为该沙箱从不休眠。

与 SandboxCreate 中相同：接受，但不起作用，因为该沙箱从不休眠。

与 SandboxCreate 中相同：接受，但不起作用，因为该沙箱从不休眠。

与 SandboxCreate 中相同：接受，但不起作用，因为该沙箱从不休眠。

与 SandboxCreate 中相同：接受，并在命令运行期间创建检查点。

与 SandboxCreate 中相同：接受，但不起作用，因为该沙箱从不休眠。

与 SandboxCreate 中相同。

在虚拟机被彻底结束之前如何停止沙箱的启动命令：在重启 (POST /v1/sandboxes/{id}/restart) 和删除之前。信号发给启动命令，然后给它 grace_ms 时间结束；到时还没结束的随虚拟机一起结束。休眠或暂停的虚拟机不会被停止：它会从上次停下的地方继续。不给出时：启动命令随其虚拟机一起结束，一直以来都是这样。不认识的键：400 unknown_field；不是这些信号之一，或者宽限时间超过十分钟：400 invalid_field。

与 SandboxCreate 中相同：更多的变量，其值为机密，作用于沙箱，因此也作用于命令；其中任何一个都不能同时出现在 env 中（400 invalid_field，param 为 secret_env.<name>）。任何响应都不显示值。

运行所在的绝对路径。默认：镜像的工作目录。目录不存在不算调用的错误：命令以退出码 126 结束。

用户名、uid 或 uid:gid。默认：镜像的用户。

与 RunRequest 中相同，但有默认值：否则没有任何东西会让该沙箱停下来。

喂给命令输入的内容，之后关闭输入（除非 stdin_open）。encoding 指定时为 Base64。整个请求最大 64 MiB（超出时返回 413 body_too_large）：更长的输入请分多次调用 …/exec/{exec_id}/stdin 发送，或者先写入文件。

base64：stdin 为 base64，stdout 和 stderr 也以 base64 返回（在事件流中：事件携带 base64 而不是 text）。用于非文本的输出。

以事件流返回。默认：请求的 Accept 包含 text/event-stream 时为 true。

让命令等待读取本调用响应的一方，而不是抢在它前面运行。与 RunRequest 中相同。

创建所在的区域，由 API 读取，不会转发。null 或不给出：API 自己运行所在的区域。该区域没有机器能容纳时，由下一个区域接手；必须放在某台特定机器上的（从快照或带存储卷创建的，或用同一个 Idempotency-Key 再次发送的）会放到那台机器上，无论在哪个区域。从备份创建的存储卷创建在备份所在的区域：指定其他区域会返回 400 invalid_field。不是有效区域：400 unknown_region。响应中的 region 说明它创建在哪里。