HTTP API 参考

本页记录 sandbox bridge 暴露的每条路由。

/v1/sandbox/* 和 /v1/openapi.* 下的所有路由都需要 Bearer token：

Authorization: Bearer <SANDBOX_API_KEY>

未配置 SANDBOX_API_KEY 时，为便于本地开发会跳过认证。部署到生产环境前请务必设置该密钥。

bridge 提供自身的 API 文档：

两条路由均支持通过 Bearer 请求头或 ?token= 查询参数进行认证。

在本地使用 npm run dev 运行时，在浏览器中打开 http://localhost:8787/v1/openapi，可交互式探索每个端点。

/exec 端点接受 JSON 请求体：

{
  "argv": ["sh", "-lc", "echo hello"],
  "timeout_ms": 10000,
  "cwd": "/workspace"
}

argv 数组的每个元素在拼接为 shell 命令前，会使用 ANSI-C $'...' 引号进行转义。仅包含安全字符（A-Za-z0-9@%+=:,./-）的 token 会原样传递。所有其他 token 会包装在 $'...' 中，并对反斜杠、单引号、换行、回车和制表符进行转义。这可防止 shell 注入，同时保留包含空格、引号或特殊字符的参数。

响应为 text/event-stream，包含以下事件类型：

文件路径编码在 URL 的 /file/ 之后。所有路径必须解析到 /workspace 内。路径遍历尝试（例如 ../../etc/passwd）会被拒绝。

/persist 端点接受可选的 excludes 查询参数 — 要从归档中排除的相对路径的逗号分隔列表。

/hydrate 端点接受最大 32 MiB 的原始 tar 负载。

/mount 端点接受 JSON 请求体。支持两种流程：

省略 endpoint，并在 bucket 中传入 Worker R2 绑定名称：

{
  "bucket": "MY_BUCKET",
  "mountPath": "/mnt/data",
  "options": {
    "readOnly": false,
    "prefix": "/subdir"
  }
}

当省略 options.endpoint 时，bucket 表示 Worker R2 绑定名称。

对于显式的 S3 兼容端点挂载，请包含 endpoint 以及可选的 credentials：

{
  "bucket": "my-r2-bucket",
  "mountPath": "/mnt/data",
  "options": {
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
    "readOnly": false,
    "prefix": "/subdir",
    "credentials": {
      "accessKeyId": "...",
      "secretAccessKey": "..."
    }
  }
}

当提供 endpoint 时，bucket 表示远程存储桶名称。此模式下凭据是可选的 — 省略时，bridge 会从 Worker 密钥（R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY 或 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY）自动检测。

会话在沙箱内隔离工作目录、环境变量和命令执行状态。在 /exec、/file/* 和 /pty 请求上传递 Session-Id 请求头，可将其限定到某个会话。

未提供 Session-Id 请求头时，请求使用沙箱的隐式执行模式。默认这是默认会话，但配置了 enableDefaultSession: false 的 SDK 会改为以无会话方式运行这些隐式操作。

查询参数：

WebSocket 为终端 I/O 携带二进制帧，为控制消息携带 JSON 文本帧：

预热池会预先启动沙箱 container，使新会话可即时启动。在 wrangler.jsonc 中使用环境变量配置：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "vars": {
    "WARM_POOL_TARGET": "3",
    "WARM_POOL_REFRESH_INTERVAL": "10000"
  }
}

[vars]
WARM_POOL_TARGET = "3"           # Number of idle containers to keep warm (0 = disabled)
WARM_POOL_REFRESH_INTERVAL = "10000"  # Health-check interval in milliseconds

cron 触发器（* * * * *）会在部署后自动预热池。将 WARM_POOL_TARGET 设为 "0"（默认值）可禁用池并避免意外费用。

• Bridge 概览 — bridge 是什么、部署和用法示例。
• Sandbox API 参考 — 完整 Sandbox SDK 方法参考。
• GitHub 上的 Bridge 源码 ↗ — Worker、Dockerfile 和 OpenAPI schema。