用途:Sandbox Bridge 让代理或开发者通过一个小型 HTTP API 驱动真实的 Cloudflare Sandbox 容器,用于验证 SDK 改动、复现问题或在真实容器中测试命令,无需自行部署 worker。
主要能力:暴露完整 @cloudflare/sandbox SDK。核心流程为:POST /v1/sandbox 创建沙箱并取得不透明 ID;用该 ID 调用 /v1/sandbox/{id}/exec 执行命令(以 SSE 流返回 stdout、stderr、exit、error 事件,stdout/stderr 为 base64 编码);通过 PUT/GET /v1/sandbox/{id}/file/... 读写 /workspace 下文件;DELETE /v1/sandbox/{id} 销毁。还提供 /health、池预热管理、PTY、运行进程列表、S3 兼容桶的 FUSE 挂载/卸载、工作区 hydrate/persist 等端点,完整 schema 见 /v1/openapi.json。
使用方式:所有请求需 Authorization: Bearer $SANDBOX_API_KEY,令牌只能放请求头,不可放查询串。若两个环境变量未设置,则本会话不可用,可改用 wrangler dev 或请用户启用。exec 请求体为已 shell 拆分的 argv 数组,shell 片段需包成 ["sh","-lc","..."];可选 timeout_ms 与 cwd(须在 /workspace 下)。默认无会话,需持久化 cwd 或环境变量时用 POST /v1/sandbox/{id}/session 创建会话,并通过 Session-Id 头复用;会话随父沙箱销毁而消失。
适用场景:快速验证命令在真实沙箱容器中的行为,无需本地 Docker 或构建步骤;尤其适合依赖主机级能力的功能,如基于 FUSE 的桶挂载,wrangler dev 无法复现。
限制:桥接运行的是当前已部署的 @cloudflare/sandbox 版本,不会自动同步工作树;测试未发布且不依赖 FUSE 的 SDK 改动应改用 wrangler dev。错误返回 JSON 错误码,如 unauthorized、invalid_request、exec_error 等;SSE 流打开后传输错误以 event: error 形式到达。使用完毕应始终清理沙箱。