Manage Bailian sandbox instances and templates from the terminal: create, list, get, connect, pause, resume, and delete instances, as well as create, update, list, get, and delete templates with build-status polling.
Sandbox capabilities are currently available only to China site (aliyun.com) accounts, requiring the cn-beijing region and prior Sandbox SLR authorization.
Append --help to any command for full parameter details, e.g. bl sandbox create --help. Connection credentials are redacted by default; use --show-credentials when needed. Command details on this page are verified against bl 2.5.1.
Instance management
bl sandbox list
List Sandbox instances. Requires API Key authentication.
Usage
bl sandbox list [--template-id <id>] [--sandbox-id <id>] [--state <state>] [--limit <n>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--template-id <id> | string | no | Filter by template ID |
--sandbox-id <id> | string | no | Filter by sandbox ID |
--state <state> | string | no | Filter by state, for example running or paused |
--limit <n> | number | no | Maximum results (1-50) |
bl sandbox list --state running --limit 20
- Auth: uses a Bailian API Key as an Authorization Bearer token; no E2B key is sent.
- Base URL: --base-url > DASHSCOPE_BASE_URL > login/profile base_url. The CLI uses its origin and appends /api/v1/agentstudio/sandbox; otherwise it uses the workspace-scoped cn-beijing endpoint.
- Without a configured base URL, workspace is required: --workspace-id > BAILIAN_WORKSPACE_ID > config workspace_id.
- Sandbox is currently available in cn-beijing only and requires prior SLR authorization.
- Global --timeout limits HTTP requests and total template-build polling; --instance-timeout maps to the Sandbox API lifetime field.
bl sandbox get
Get Sandbox instance details. Requires API Key authentication.
Usage
bl sandbox get --sandbox-id <id> [--show-credentials]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--sandbox-id <id> | string | yes | Sandbox instance ID |
--show-credentials | switch | no | Print envd and traffic access tokens instead of redacting them |
bl sandbox get --sandbox-id sbx-xxx
- Auth: uses a Bailian API Key as an Authorization Bearer token; no E2B key is sent.
- Base URL: --base-url > DASHSCOPE_BASE_URL > login/profile base_url. The CLI uses its origin and appends /api/v1/agentstudio/sandbox; otherwise it uses the workspace-scoped cn-beijing endpoint.
- Without a configured base URL, workspace is required: --workspace-id > BAILIAN_WORKSPACE_ID > config workspace_id.
- Sandbox is currently available in cn-beijing only and requires prior SLR authorization.
- Global --timeout limits HTTP requests and total template-build polling; --instance-timeout maps to the Sandbox API lifetime field.
bl sandbox create
Create a Sandbox instance. Requires API Key authentication.
Usage
bl sandbox create (--template-id <id> | --body <json|@path>) [flags]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--body <json|@path> | string | no | JSON request body, inline or loaded from an @file path; explicit flags override it |
--template-id <id> | string | no | Ready template ID; may alternatively be supplied as templateID in --body |
--instance-timeout <seconds> | number | no | Sandbox lifetime after this operation (300-604800 seconds) |
--allow-internet-access <bool> | boolean | no | Allow public internet access |
--metadata <key=value> | array | no | Instance metadata entry; repeat for multiple values |
--env <key=value> | array | no | Instance environment variable; repeat for multiple values |
--auto-pause <bool> | boolean | no | Pause the instance when its timeout expires |
--auto-resume <bool> | boolean | no | Automatically resume a paused instance when connecting |
--allow-out <address> | array | no | Outbound allow-list entry; repeat for multiple values |
--deny-out <address> | array | no | Outbound deny-list entry; repeat for multiple values |
--mask-request-host <host> | string | no | Override the outbound request Host header |
--show-credentials | switch | no | Print envd and traffic access tokens instead of redacting them |
bl sandbox create --template-id tpl-xxx --instance-timeout 3600
- Auth: uses a Bailian API Key as an Authorization Bearer token; no E2B key is sent.
- Base URL: --base-url > DASHSCOPE_BASE_URL > login/profile base_url. The CLI uses its origin and appends /api/v1/agentstudio/sandbox; otherwise it uses the workspace-scoped cn-beijing endpoint.
- Without a configured base URL, workspace is required: --workspace-id > BAILIAN_WORKSPACE_ID > config workspace_id.
- Sandbox is currently available in cn-beijing only and requires prior SLR authorization.
- Global --timeout limits HTTP requests and total template-build polling; --instance-timeout maps to the Sandbox API lifetime field.
bl sandbox connect
Connect to a Sandbox instance and return connection information. Requires API Key authentication.
Usage
bl sandbox connect --sandbox-id <id> [--instance-timeout <seconds>] [--show-credentials]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--sandbox-id <id> | string | yes | Sandbox instance ID |
--body <json|@path> | string | no | JSON request body, inline or loaded from an @file path; explicit flags override it |
--instance-timeout <seconds> | number | no | Sandbox lifetime after this operation (300-604800 seconds) |
--show-credentials | switch | no | Print envd and traffic access tokens instead of redacting them |
bl sandbox connect --sandbox-id sbx-xxx --instance-timeout 3600
bl sandbox pause
Pause a Sandbox instance. Requires API Key authentication.
Usage
bl sandbox pause --sandbox-id <id>
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--sandbox-id <id> | string | yes | Sandbox instance ID |
bl sandbox pause --sandbox-id sbx-xxx
- Auth: uses a Bailian API Key as an Authorization Bearer token; no E2B key is sent.
- Base URL: --base-url > DASHSCOPE_BASE_URL > login/profile base_url. The CLI uses its origin and appends /api/v1/agentstudio/sandbox; otherwise it uses the workspace-scoped cn-beijing endpoint.
- Without a configured base URL, workspace is required: --workspace-id > BAILIAN_WORKSPACE_ID > config workspace_id.
- Sandbox is currently available in cn-beijing only and requires prior SLR authorization.
- Global --timeout limits HTTP requests and total template-build polling; --instance-timeout maps to the Sandbox API lifetime field.
bl sandbox resume
Resume a Sandbox instance and return connection information. Requires API Key authentication.
Usage
bl sandbox resume --sandbox-id <id> [--instance-timeout <seconds>] [--show-credentials]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--sandbox-id <id> | string | yes | Sandbox instance ID |
--body <json|@path> | string | no | JSON request body, inline or loaded from an @file path; explicit flags override it |
--instance-timeout <seconds> | number | no | Sandbox lifetime after this operation (300-604800 seconds) |
--show-credentials | switch | no | Print envd and traffic access tokens instead of redacting them |
bl sandbox resume --sandbox-id sbx-xxx --instance-timeout 3600
bl sandbox delete
Release a Sandbox instance. Requires API Key authentication.
Usage
bl sandbox delete --sandbox-id <id>
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--sandbox-id <id> | string | yes | Sandbox instance ID |
--yes | switch | no | Confirm this high-risk operation |
This permanently releases the Sandbox instance and cannot be undone.
bl sandbox delete --sandbox-id sbx-xxx --dry-run
- Auth: uses a Bailian API Key as an Authorization Bearer token; no E2B key is sent.
- Base URL: --base-url > DASHSCOPE_BASE_URL > login/profile base_url. The CLI uses its origin and appends /api/v1/agentstudio/sandbox; otherwise it uses the workspace-scoped cn-beijing endpoint.
- Without a configured base URL, workspace is required: --workspace-id > BAILIAN_WORKSPACE_ID > config workspace_id.
- Sandbox is currently available in cn-beijing only and requires prior SLR authorization.
- Global --timeout limits HTTP requests and total template-build polling; --instance-timeout maps to the Sandbox API lifetime field.
Template management
bl sandbox template list
List Sandbox templates. Requires API Key authentication.
Usage
bl sandbox template list [--limit <n>] [--cursor <cursor>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--limit <n> | number | no | Maximum results (1-100) |
--cursor <cursor> | string | no | Server-side pagination cursor |
bl sandbox template list --limit 100 --output json
- The API response does not expose a next cursor, so automatic --all pagination is unavailable.
bl sandbox template get
Get Sandbox template details. Requires API Key authentication.
Usage
bl sandbox template get --template-id <id>
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--template-id <id> | string | yes | Sandbox template ID |
bl sandbox template get --template-id tpl-xxx
- Auth: uses a Bailian API Key as an Authorization Bearer token; no E2B key is sent.
- Base URL: --base-url > DASHSCOPE_BASE_URL > login/profile base_url. The CLI uses its origin and appends /api/v1/agentstudio/sandbox; otherwise it uses the workspace-scoped cn-beijing endpoint.
- Without a configured base URL, workspace is required: --workspace-id > BAILIAN_WORKSPACE_ID > config workspace_id.
- Sandbox is currently available in cn-beijing only and requires prior SLR authorization.
- Global --timeout limits HTTP requests and total template-build polling; --instance-timeout maps to the Sandbox API lifetime field.
bl sandbox template create
Create a Sandbox template. Requires API Key authentication.
Usage
bl sandbox template create (--name <name> --cpu-count <cores> --memory-mb <mb> | --body <json|@path>) [flags]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--body <json|@path> | string | no | JSON request body, inline or loaded from an @file path; explicit flags override it |
--image <preset> | string | no | Built-in image ID or Chinese name; fills fromImage and imageName |
--name <name> | string | no | Template name |
--cpu-count <cores> | number | no | vCPU count |
--memory-mb <mb> | number | no | Memory in MB |
--from-image <image> | string | no | Base image identifier |
--image-name <name> | string | no | Base image display name |
--env <key=value> | array | no | Template environment variable; repeat for multiple values |
--allow-out <address> | array | no | Outbound allow-list entry; repeat for multiple values |
--deny-out <address> | array | no | Outbound deny-list entry; repeat for multiple values |
--auto-pause-time <seconds> | number | no | Automatically pause after 300-604800 seconds |
--max-running-time <seconds> | number | no | Maximum running lifetime in seconds (300-604800) |
--description <text> | string | no | Template description |
--tag <tag> | array | no | E2B tag; repeat for multiple values |
--alias <alias> | string | no | E2B template alias |
--async | switch | no | Return the submitted templateID/buildID immediately without polling |
--poll-interval <seconds> | number | no | Template build polling interval (default: 5 seconds) |
bl sandbox template create --name browser --image browser --cpu-count 1 --memory-mb 2048
- --image overrides body fromImage/imageName; explicit --from-image/--image-name override the corresponding preset fields. Without --image, image behavior is unchanged.
- For local file mounts, use sandbox file upload first; put the available file's id into --body mntConfig[].originFileId with mountPath and optional originFileName. Upload and template must use the same workspace. Other complete nested structures can also be supplied through --body.
- By default the command waits for build status ready; --async returns the submitted build immediately.
bl sandbox template update
Update a Sandbox template. Requires API Key authentication.
Usage
bl sandbox template update --template-id <id> (--body <json|@path> | [fields])
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--template-id <id> | string | yes | Sandbox template ID |
--body <json|@path> | string | no | JSON request body, inline or loaded from an @file path; explicit flags override it |
--image <preset> | string | no | Built-in image ID or Chinese name; fills fromImage and imageName |
--name <name> | string | no | Template name |
--cpu-count <cores> | number | no | vCPU count |
--memory-mb <mb> | number | no | Memory in MB |
--from-image <image> | string | no | Base image identifier |
--image-name <name> | string | no | Base image display name |
--env <key=value> | array | no | Template environment variable; repeat for multiple values |
--allow-out <address> | array | no | Outbound allow-list entry; repeat for multiple values |
--deny-out <address> | array | no | Outbound deny-list entry; repeat for multiple values |
--auto-pause-time <seconds> | number | no | Automatically pause after 300-604800 seconds |
--max-running-time <seconds> | number | no | Maximum running lifetime in seconds (300-604800) |
--description <text> | string | no | Template description |
--async | switch | no | Return the submitted templateID/buildID immediately without polling |
--poll-interval <seconds> | number | no | Template build polling interval (default: 5 seconds) |
bl sandbox template update --template-id tpl-xxx --image all-in-one
- --image overrides body fromImage/imageName; explicit --from-image/--image-name override the corresponding preset fields. Without --image, image behavior is unchanged.
- Supplying envConfig or --env replaces the template's complete environment map.
- Use sandbox file upload for local mount files. In --body mntConfig[], set originFileId to the available file's id and supply mountPath; upload and template must use the same workspace.
- By default the command waits for build status ready; --async returns the submitted build immediately.
bl sandbox template build-status
Get Sandbox template build status. Requires API Key authentication.
Usage
bl sandbox template build-status --template-id <id> --build-id <id>
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--template-id <id> | string | yes | Sandbox template ID |
--build-id <id> | string | yes | Template build ID |
bl sandbox template build-status --template-id tpl-xxx --build-id build-xxx
- Auth: uses a Bailian API Key as an Authorization Bearer token; no E2B key is sent.
- Base URL: --base-url > DASHSCOPE_BASE_URL > login/profile base_url. The CLI uses its origin and appends /api/v1/agentstudio/sandbox; otherwise it uses the workspace-scoped cn-beijing endpoint.
- Without a configured base URL, workspace is required: --workspace-id > BAILIAN_WORKSPACE_ID > config workspace_id.
- Sandbox is currently available in cn-beijing only and requires prior SLR authorization.
- Global --timeout limits HTTP requests and total template-build polling; --instance-timeout maps to the Sandbox API lifetime field.
bl sandbox template delete
Delete a Sandbox template. Requires API Key authentication.
Usage
bl sandbox template delete --template-id <id>
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--template-id <id> | string | yes | Sandbox template ID |
--yes | switch | no | Confirm this high-risk operation |
This permanently deletes the Sandbox template and cannot be undone.
bl sandbox template delete --template-id tpl-xxx --dry-run
- The server rejects deletion while running or paused instances still use the template.
Built-in images and file upload
bl sandbox official-images
List the built-in Sandbox base images (offline). No authentication required.
Usage
bl sandbox official-images
bl sandbox official-images --output json
- Use a preset ID or Chinese name with template create/update --image. These are pinned cn-beijing images; other environments may differ. Use --from-image for a custom image.
bl sandbox file upload
Upload a workspace file for Sandbox template mounts. Requires API Key authentication.
Usage
bl sandbox file upload --path <path> [--filename <name>] [--mime-type <type>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--path <path> | string | yes | Local file path |
--filename <name> | string | no | Remote filename override |
--mime-type <type> | string | no | Multipart file MIME type (default: application/octet-stream) |
bl sandbox file upload --path ./config.json --output json
- POST /api/v1/agentstudio/files with multipart fields file and source=sandbox_template. Uses a Bailian Bearer API Key, not Console authentication or an E2B key; no agents.yaml is needed.
- Base URL follows Sandbox: --base-url > DASHSCOPE_BASE_URL > login/profile base_url. Without one, --workspace-id > BAILIAN_WORKSPACE_ID > config workspace_id selects the cn-beijing origin. The upload path has no /sandbox prefix.
- Returns the upload response immediately; --quiet prints only its id. Upload does not wait for security review: status=checking is not ready to mount. Use an available file's id as mntConfig[].originFileId in template create/update --body, together with mountPath and optional originFileName, in the same workspace. This does not transfer files into a running instance.
- The file size limit is 50 MB. The type is validated by extension:
.csv, .yml, .sh, .whl, and .tar.gz are not supported; .yaml is accepted. The full supported range is determined by the service.
- For template mounts,
mntConfig[].mountPath must start with /home/user/workspace/uploads/. Use a full file path. If the path is outside this directory, the API accepts the configuration but the file does not appear in the instance.
- For upload parameters, file types, and a full example, see File upload.
- --dry-run previews the endpoint, source, and local path without reading or uploading the file. The service detects the MIME type and enforces upload limits.
