bailian-sandbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bailian Sandbox (

bl sandbox

)

百炼沙箱（

bl sandbox

）

Before running

bl

, read the shared bailian-protocol for consent, high-risk confirmation, version checks, authentication, and error handling. If it is missing, stop execution and prompt the user to install the full family with

bl skill init

运行

bl

之前，请阅读共享的 bailian-protocol 以了解同意条款、高危确认、版本检查、身份验证和错误处理相关内容。如果缺少该协议，请停止执行并提示用户通过

bl skill init

安装完整套件。

Scope and setup

适用范围与设置

Manage Sandbox instances and templates through Bailian's E2B-compatible REST control plane. No E2B SDK or E2B API key is required; authentication uses the Bailian API Key as an Authorization Bearer token.
Resolve Base URL through the same CLI chain as Managed Agent:
```
--base-url
```
>
```
DASHSCOPE_BASE_URL
```
> login/profile
```
base_url
```
. Use an origin such as
```
https://workspace.cn-beijing.maas.aliyuncs.com
```
; the CLI strips URL paths/query/fragment and appends
```
/api/v1/agentstudio/sandbox
```
for lifecycle operations, or
```
/api/v1/agentstudio/files
```
for template file uploads. The saved API Key is reused. Profile capability fallback follows the shared protocol for both the key and Base URL.
If no Base URL is configured, resolve the workspace from
```
--workspace-id
```
, then
```
BAILIAN_WORKSPACE_ID
```
, then configured
```
workspace_id
```
, and use
```
https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sandbox
```
. With a configured Base URL, the workspace flag is optional. The service currently supports
```
cn-beijing
```
and requires prior Sandbox SLR authorization.
No
```
agents.yaml
```
or local IaC state is required.
```
get
```
/
```
connect
```
return instance connection information; neither opens an interactive shell or browser. For WebShell, CDP, or VNC, use that information with the runtime APIs described below. Do not invent
```
bl sandbox exec
```
,
```
webshell
```
, or browser subcommands.

通过百炼兼容E2B的REST控制面管理Sandbox实例与模板。无需E2B SDK或E2B API密钥；身份验证使用百炼API Key作为Authorization Bearer令牌。
Base URL的解析遵循与Managed Agent相同的CLI优先级链：
```
--base-url
```
>
```
DASHSCOPE_BASE_URL
```
> 登录/配置文件中的
```
base_url
```
。使用类似
```
https://workspace.cn-beijing.maas.aliyuncs.com
```
的源地址；CLI会移除URL的路径/查询参数/片段，对于生命周期操作追加
```
/api/v1/agentstudio/sandbox
```
，对于模板文件上传追加
```
/api/v1/agentstudio/files
```
。已保存的API Key会被复用。配置文件的能力降级规则遵循共享协议中关于密钥和Base URL的约定。
如果未配置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
```
或浏览器相关子命令。

Choose the operation

选择操作

User intent	Command family
Discover built-in base image presets	`bl sandbox official-images` (offline, no authentication)
Upload a local file for template mounts	`bl sandbox file upload`
Inspect or create instances	`bl sandbox list` / `get` / `create`
Connect, pause, or resume an instance	`bl sandbox connect` / `pause` / `resume`
Release an instance	`bl sandbox delete`
Inspect or build templates	`bl sandbox template list` / `get` / `create` / `update`
Check a submitted template build	`bl sandbox template build-status`
Delete a template	`bl sandbox template delete`

Read reference/index.md and the relevant section of reference/sandbox.md for exact flags, usage, and examples, or run the matching command with

--help

. Do not guess flags.

To save the origin in an isolated Profile, use

bl auth login --config sandbox --api-key <key> --base-url <origin>

. For a one-command override, use

bl sandbox list --base-url <origin>

. Custom gateways also apply to template build-status polling.

For built-in template images, discover the preset ID or Chinese name through

sandbox official-images

, then pass it to template create/update with

--image

. This fills both

fromImage

and

imageName

;

--image-name

alone remains a display name, not an image selector. Presets override the body's image fields; explicit

--from-image

--image-name

override the corresponding preset fields. Presets are pinned cn-beijing image URLs, not a live catalog or an availability guarantee for other environments. Omitting

--image

does not change existing defaults or update a template's image implicitly. See the generated reference for the catalog and exact flags.

用户意图	对应命令族
查看内置基础镜像预设	`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

参数。请勿猜测参数。

如需将源地址保存到独立的配置文件（Profile）中，请使用

bl auth login --config sandbox --api-key <key> --base-url <origin>

。如需单次命令覆盖，请使用

bl sandbox list --base-url <origin>

。自定义网关同样适用于模板构建状态的轮询。

对于内置模板镜像，可通过

sandbox official-images

命令查看预设ID或中文名称，然后通过

--image

参数传递给模板创建/更新命令。该参数会同时填充

fromImage

和

imageName

；单独使用

--image-name

仅作为显示名称，而非镜像选择器。预设会覆盖请求体中的镜像字段；显式指定的

--from-image

--image-name

会覆盖对应的预设字段。预设是固定的cn-beijing区域镜像URL，并非实时目录，也不保证在其他环境中可用。省略

--image

不会更改现有默认值，也不会隐式更新模板的镜像。请查看生成的参考文档以获取完整目录和准确参数。

Connect to an instance

连接实例

For requests to access a running instance, open WebShell, control a browser, or show its live desktop, read assets/instance-connections.md. It contains the connection workflow, API payloads, verification steps, and official documentation links.

Obtain fresh JSON with

bl sandbox get --sandbox-id <id> --show-credentials --output json

. Use

envdAccessToken

X-Access-Token

; the control-plane Bailian API Key is a different credential.

WebShell uses the returned
```
envdUrl
```
and envd PTY RPCs. The official browser template uses port 3000 on
```
{port}-{sandboxID}.{domain}
```
for CDP and VNC. These ports and paths come from the template contract, not fields returned by
```
get
```
; do not apply them to other images without checking their documentation.
When the user asks to open or access the instance, complete the connection and verify a terminal command or rendered browser page. Returning connection JSON or a successful health check alone does not complete that request. A local proxy URL is a host-side access page, not a URL returned by the Sandbox API.

对于访问运行中实例、打开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。

Operational boundaries

操作边界

Mutating commands act on remote resources. Only perform the requested operation and scope; read-only discovery does not authorize creating, pausing, resuming, or deleting resources.
Instance and template deletion are high-risk. Follow the shared protocol: show the exact target and risk, then wait for explicit confirmation before adding
```
--yes
```
. Treat
```
requires_confirmation
```
as a stop signal, not a reason to retry automatically.
Connection credentials are redacted by default. A request to connect to or access the instance needs the tokens: use
```
--show-credentials
```
for that operation, capture the result privately, and keep tokens out of chat summaries, logs, URLs, and committed files.
Template create/update wait by polling the build-status endpoint, not template details.
```
--async
```
returns after the submission response with
```
templateID
```
/
```
buildID
```
; it does not mean the build is ready. Use those IDs with
```
template build-status
```
to check completion.
Global
```
--timeout
```
limits HTTP requests and total template-build polling.
```
--instance-timeout
```
sets instance lifetime; these are different limits. A polling timeout does not prove the remote build failed or stopped; check its status before submitting another build.
```
--body
```
accepts a JSON object inline or through
```
@path
```
; explicit flags override body fields. For local template mounts, first use
```
bl sandbox file upload
```
: it sends multipart
```
file
```
and fixed
```
source=sandbox_template
```
directly to
```
/api/v1/agentstudio/files
```
with the Bailian API Key. Use the returned
```
id
```
as
```
mntConfig[].originFileId
```
, with
```
mountPath
```
and optional
```
originFileName
```
, in template create/update
```
--body
```
. The upload and template must use the same workspace. This is not the temporary OSS upload from
```
bl file upload
```
or a transfer into a running instance.
File upload returns immediately after the upload response and does not poll security review.
```
status=checking
```
is not ready to mount; only use files whose status is
```
available
```
.
```
--quiet
```
returns the File ID only; inspect the normal/JSON response for status. Upload alone does not authorize creating a template or instance.

变更类命令会操作远程资源。仅执行用户请求的操作和范围；只读性质的查询操作不代表有权创建、暂停、恢复或删除资源。
实例和模板的删除属于高危操作。请遵循共享协议：先展示准确的操作目标和风险，等待用户明确确认后再添加
```
--yes
```
参数。将
```
requires_confirmation
```
视为停止信号，而非自动重试的理由。
连接凭证默认会被脱敏。连接或访问实例的请求需要用到令牌：请在该操作中使用
```
--show-credentials
```
参数，私下保存结果，切勿将令牌暴露在聊天摘要、日志、URL和提交的文件中。
模板创建/更新通过轮询build-status接口等待结果，而非通过模板详情接口。
```
--async
```
参数会在提交请求后立即返回
```
templateID
```
/
```
buildID
```
；这并不代表构建已完成。请使用这些ID通过
```
template build-status
```
命令检查构建是否完成。
全局
```
--timeout
```
参数限制HTTP请求和模板构建轮询的总时长。
```
--instance-timeout
```
设置实例的生命周期；这是两个不同的限制。轮询超时并不代表远程构建失败或停止；在提交新的构建请求前，请先检查其状态。
```
--body
```
参数支持内联JSON对象或通过
```
@path
```
指定文件路径；显式参数会覆盖body中的字段。对于本地模板挂载，请先使用
```
bl sandbox file upload
```
命令：该命令会将multipart格式的
```
file
```
和固定的
```
source=sandbox_template
```
参数连同百炼API Key一起直接发送到
```
/api/v1/agentstudio/files
```
。在模板创建/更新的
```
--body
```
中，将返回的
```
id
```
用作
```
mntConfig[].originFileId
```
，并搭配
```
mountPath
```
和可选的
```
originFileName
```
使用。上传操作和模板必须使用同一个工作空间。这不同于
```
bl file upload
```
的临时OSS上传，也不是向运行中实例传输文件。
文件上传在收到上传响应后立即返回，不会轮询安全审核结果。
```
status=checking
```
状态的文件尚未准备好挂载；仅可使用状态为
```
available
```
的文件。
```
--quiet
```
参数仅返回文件ID；请查看普通/JSON响应以获取状态。仅上传文件并不代表有权创建模板或实例。

Common hand-offs

常见交接场景

Refer to sibling skills by name: read them if installed; otherwise use the command's

--help

or prompt

bl skill init

Managed Agent / Session / Environment resources or
```
agents.yaml
```
IaC →
```
bailian-managed-agent
```
(
```
bl managed-agent --help
```
).

Workspace discovery or CLI login/configuration →

bailian-cli

(

bl workspace --help

bl auth --help

bl config --help

请按名称引用兄弟技能：如果已安装则读取其内容；否则使用命令的

--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

）。

references

参考资料

bailian-protocol — shared execution protocol, installed with
```
bl skill init
```
reference/ — generated command reference
Instance connections — WebShell, browser CDP, VNC, and official runtime documentation

bailian-protocol — 共享执行协议，随
```
bl skill init
```
一同安装
reference/ — 生成的命令参考文档
实例连接 — WebShell、浏览器CDP、VNC及官方运行时文档

bailian-sandbox

Original

Translation

Bailian Sandbox (
`bl sandbox`
)

百炼沙箱（
`bl sandbox`
）

Scope and setup

适用范围与设置

Choose the operation

选择操作

Connect to an instance

连接实例

Operational boundaries

操作边界

Common hand-offs

常见交接场景

references

参考资料

bailian-sandbox

Original

Translation

Bailian Sandbox (bl sandbox)

百炼沙箱（bl sandbox）

Scope and setup

适用范围与设置

Choose the operation

选择操作

Connect to an instance

连接实例

Operational boundaries

操作边界

Common hand-offs

常见交接场景

references

参考资料

Bailian Sandbox (
`bl sandbox`
)

百炼沙箱（
`bl sandbox`
）