Bailian Sandbox（bl sandbox）是阿里云百炼提供的沙箱实例与模版生命周期管理命令行入口。它通过百炼兼容 E2B 的 REST 控制面来管理 Sandbox 实例和模版，无需 E2B SDK 或 E2B API Key，认证使用百炼 API Key 作为 Authorization Bearer token。
用途与范围
该工具用于创建、查询、连接、暂停、恢复或释放百炼沙箱实例，以及查看内置基础镜像、上传模版挂载文件、创建、更新、查询、删除沙箱模版、查看模版构建状态。运行 bl 前需先阅读共享的 bailian-protocol，了解同意、高风险确认、版本检查、认证和错误处理；若缺失，应停止执行并提示用户通过 bl skill init 安装完整套件。
配置与认证
Base URL 通过与管理 Agent 相同的 CLI 链解析：--base-url > DASHSCOPE_BASE_URL > login/profile base_url。使用形如 https://workspace.cn-beijing.maas.aliyuncs.com 的 origin；CLI 会剥离 URL 路径、查询和片段，并为生命周期操作追加 /api/v1/agentstudio/sandbox，为模版文件上传追加 /api/v1/agentstudio/files。已保存的 API Key 会被复用。若未配置 Base URL，则依次从 --workspace-id、BAILIAN_WORKSPACE_ID、已配置的 workspace_id 解析工作区，并使用 https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sandbox。配置了 Base URL 时，workspace 标志可选。服务当前支持 cn-beijing，且需要预先完成 Sandbox SLR 授权。
无需 agents.yaml 或本地 IaC 状态。get / connect 返回实例连接信息，但不会打开交互式 shell 或浏览器。如需 WebShell、CDP 或 VNC，需使用这些信息配合运行时 API。不要臆造 bl sandbox exec、webshell 或 browser 子命令。
主要操作
发现内置基础镜像预设：bl sandbox official-images（离线，无需认证）。 上传本地文件用于模版挂载：bl sandbox file upload。 查看或创建实例：bl sandbox list / get / create。 连接、暂停或恢复实例：bl sandbox connect / pause / resume。 释放实例：bl sandbox delete。 查看或构建模版：bl sandbox template list / get / create / update。 检查已提交的模版构建：bl sandbox template build-status。 删除模版：bl sandbox template delete。
具体标志、用法和示例请阅读 reference/index.md 及 reference/sandbox.md 的相关章节，或运行对应命令加 --help。不要猜测标志。
若要将 origin 保存到隔离的 Profile，可使用 bl auth login --config sandbox --api-key <key> --base-url <origin>。单命令覆盖可使用 bl sandbox list --base-url <origin>。自定义网关同样适用于模版 build-status 轮询。
内置模版镜像
对于内置模版镜像，先通过 sandbox official-images 发现预设 ID 或中文名称，再将其传给 template create/update 的 --image。这会同时填充 fromImage 和 imageName；单独使用 --image-name 仍只是显示名称，不是镜像选择器。预设会覆盖 body 中的 image 字段；显式的 --from-image / --image-name 会覆盖对应的预设字段。预设是固定的 cn-beijing 镜像 URL，不是实时目录，也不保证在其他环境可用。省略 --image 不会改变现有默认值，也不会隐式更新模版的镜像。
连接实例
对于访问运行中实例、打开 WebShell、控制浏览器或显示其实时桌面的请求，请阅读 assets/instance-connections.md，其中包含连接工作流、API 载荷、验证步骤和官方文档链接。
使用 bl sandbox get --sandbox-id <id> --show-credentials --output json 获取最新 JSON。将 envdAccessToken 用作 X-Access-Token；控制面的百炼 API Key 是另一种凭据。
WebShell 使用返回的 envdUrl 和 envd PTY RPC。官方浏览器模版在 {port}-{sandboxID}.{domain} 上使用端口 3000 进行 CDP 和 VNC。这些端口和路径来自模版契约，而非 get 返回的字段；未经检查其文档，不要将其应用于其他镜像。
当用户要求打开或访问实例时，需完成连接并验证终端命令或渲染的浏览器页面。仅返回连接 JSON 或健康检查成功并不算完成该请求。本地代理 URL 是主机侧访问页面，不是 Sandbox API 返回的 URL。
操作边界
变更类命令作用于远程资源。只执行请求的操作和范围；只读发现不授权创建、暂停、恢复或删除资源。
实例和模版删除属于高风险操作。遵循共享协议：显示确切目标和风险，然后等待明确确认后再添加 --yes。将 requires_confirmation 视为停止信号，而非自动重试的理由。
连接凭据默认被脱敏。连接或访问实例的请求需要令牌：该操作使用 --show-credentials，私下捕获结果，并让令牌远离聊天摘要、日志、URL 和提交文件。
模版 create/update 通过轮询 build-status 端点等待，而非模版详情。--async 在提交响应后返回 templateID / buildID；这不意味着构建已就绪。使用这些 ID 配合 template build-status 检查完成情况。
全局 --timeout 限制 HTTP 请求和总模版构建轮询。--instance-timeout 设置实例生命周期；两者是不同的限制。轮询超时不能证明远程构建失败或停止；在提交另一次构建前检查其状态。
--body 接受内联 JSON 对象或通过 @path 传入；显式标志覆盖 body 字段。对于本地模版挂载，先使用 bl sandbox file upload：它直接向 /api/v1/agentstudio/files 发送 multipart 文件和固定 source=sandbox_template，并携带百炼 API Key。将返回的 id 用作 template create/update --body 中的 mntConfig[].originFileId，配合 mountPath 和可选的 originFileName。上传和模版必须使用同一工作区。这不是 bl file upload 的临时 OSS 上传，也不是传输到运行中实例。
文件上传在上传响应后立即返回，不轮询安全审查。status=checking 表示尚未准备好挂载；只使用 status 为 available 的文件。--quiet 仅返回 File ID；检查普通/JSON 响应以获取 status。仅上传不授权创建模版或实例。
常见交接
按名称引用同级技能：若已安装则阅读；否则使用命令的 --help 或提示 bl skill init。
Managed Agent / Session / Environment 资源或 agents.yaml IaC → bailian-managed-agent（bl managed-agent --help）。
工作区发现或 CLI 登录/配置 → bailian-cli（bl workspace --help / bl auth --help / bl config --help）。
参考
bailian-protocol — 共享执行协议，随 bl skill init 安装。 reference/ — 生成的命令参考。 Instance connections — WebShell、浏览器 CDP、VNC 和官方运行时文档。