命令与文件

E2B SDK 的 sandbox.commands.* 与 sandbox.files.* 在 Kibotos 的 sandbox 上照常可用，行为与 E2B 相同。本页介绍支持的进程与文件接口、请求以哪个账号执行、路径怎样解析，以及进程流与目录监视的行为。

支持的接口复制标题链接

进程与文件接口的线上格式与 E2B 的 envd 相同：Connect、gRPC、gRPC-Web 三种协议，JSON 与二进制编码，gzip 压缩协商。

PTY 与普通命令都通过 Start 启动。

执行命令复制标题链接

下面的例子以 root 在 /tmp 下执行一条命令，并打印它的输出：

const result = await sandbox.commands.run('id -un && pwd', { user: 'root', cwd: '/tmp' });
console.log(result.stdout);

不指定 user 与 cwd 时，命令以 Template 的账号、在这个账号的 home 目录下执行，见执行账号与工作目录。

命令执行期间网关与 node 之间的连接断开时，输出仍从同一条流陆续到达，见进程流。

执行账号与工作目录复制标题链接

每个进程与文件请求都以 guest 里的某个账号执行。账号用 SDK 的 user 选项指定，进程请求还可以指定 cwd。

选择执行账号复制标题链接

• 没有指定账号时，使用 Template 声明的账号。
• root 表示使用 root。
• 网关不校验账号名。Template 中没有声明的账号名会被 node 以 invalid_argument 拒绝，SDK 原样收到这个错误。

工作目录与相对路径复制标题链接

• 没有指定 cwd 时，进程在执行账号的 home 目录启动。
• 文件路径与 cwd 写相对路径时，按执行账号的 home 目录解析；~ 与 ~/… 也指这个目录，与 E2B 一致。
• ~name 指别的账号的 home，返回 invalid_argument。
• Workspace 的 guest 早于 v0.3.0 时只接受绝对路径，相对路径返回 400。重启 Workspace 后可以使用相对路径。

下面的例子用相对路径写入一个文件再读回。Template 声明的账号是 user 时，两次调用都使用 /home/user/notes.txt：

await sandbox.files.write('notes.txt', 'hello');
console.log(await sandbox.files.read('notes.txt'));

账号的传递方式复制标题链接

envd 协议用 HTTP basic auth 传递执行请求的账号：

• 指定了 user 时，SDK 发送 Authorization: Basic base64(username + ":")。
• 网关把用户名原样传给原生 API：Start 与文件系统请求的 user 字段，以及 /v1/files 的 user 查询参数。
• GET /files 与 POST /files 还接受 envd 协议中的 username 查询参数。两者同时存在时以 basic auth 为准。
• X-Access-Token 仍是认证凭证，basic auth 只表示身份。

进程流复制标题链接

网关与 node 之间的进程流断开时，网关自动续上。SDK 收到的仍是同一条流，输出不丢不重。网关最多重试 30 秒。

sandbox 为每个进程只保留有限的最近输出，上限见进程流续传。断开太久、输出超过上限时，丢失的部分补不回来，这条流以 data_loss 结束，不把有缺口的输出当作连续输出交给 SDK。

目录监视复制标题链接

files.watchDir（WatchDir）监视单个目录，不包括它的子目录：

• 监视在目录被删除或移走、sandbox 暂停、事件来不及送达时结束，onExit 收到对应的错误。结束原因见目录监视。
• allowNetworkMounts 被忽略。

下面两种监视方式不可用，都列在不支持的能力中：

• recursive: true 返回 unimplemented。
• CreateWatcher、GetWatcherEvents、RemoveWatcher 返回 unimplemented。它们要求网关跨请求保存监视状态，而网关不保存状态。

注意复制标题链接

• 与 E2B 不同，Kibotos 上进程与文件接口的每条请求消息最多 4 MiB，压缩的消息按解压后计。超出时返回 resource_exhausted，不转发给 sandbox。超过约 3 MiB 的数据要分几次 sendStdin 发送。
• files.write 每个文件最多上传 1 GiB，超出时返回 413（resource_exhausted）。读取没有大小上限：files.read 能读任意大小的文件，读取期间文件被改写时网关让这次读取失败。v0.3.0 之前的网关读取超过 1 GiB 的文件返回 413。

下一步复制标题链接

• Sandbox 与生命周期：创建、暂停、恢复 sandbox，以及到期时间。
• Volume：在 sandbox 中挂载独立 Volume。
• 命令与终端：这些接口背后的原生进程 API。
• 文件：原生文件 API 及其限制与错误。