Bailian Sandbox

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

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.

Choose the operation

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.

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