Skip to main content

Cloud-hosted Environment

The execution sandbox invoked by the runtime environment definition tool. Created and managed on the Console Environments page, and reusable across multiple sessions.

Sandbox containers hosted by Alibaba Cloud Bailian involve underlying cloud resources and services. When using them, you must comply with the network and data security provisions in Article 6 of the Alibaba Cloud Product Service Agreement, must not install or use pirated software, and bear full responsibility for the consequences of software you install and operations you perform.

Types

TypeDescription
CloudA sandbox container hosted by Bailian, ready to use out of the box and reusable across sessions. With pre-installed packages configured, warm-up may be required first — see Environment warm-up.

Configuration Fields

On the Environments page, click Add Environment, then fill in the following fields:
FieldRequiredEditableDescription
NameYesYesUnique identifier within the workspace
DescriptionNoYesDescription of the environment's purpose
Hosting TypeNoNocloud (cloud-hosted), managed by Bailian. Cannot be changed after creation
Pre-installed PackagesNoYesDeclared per package manager (apt / pip / npm); automatically installed during environment creation
Network PolicyNoYesunrestricted: allows all outbound traffic (API-only setting; not visible in Console)
ScopeNoYesorganization (default): accessible to all workspace members (API-only setting; not visible in Console)
MetadataNoYesCustom key-value pairs (corresponding to the API's metadata field); does not affect runtime behavior
When creating an environment via API, specify the sandbox type and pre-installed packages. For full parameter and response field details, see the Environment API. 
curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/environments" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-sandbox",
    "description": "Data analysis sandbox",
    "config": {
      "type": "cloud",
      "packages": {
        "apt": ["ffmpeg"],
        "pip": ["pandas", "numpy", "matplotlib"]
      },
      "networking": {"type": "unrestricted"}
    }
  }'

Supported Package Managers

Pre-installed packages are declared using the following package managers:
  • apt: System-level packages (e.g., ffmpeg)
  • pip: Python packages (e.g., pandas, numpy)
  • npm: Node.js packages

Environment warm-up

An environment with pre-installed packages may need warm-up time after creation to install dependencies; the duration depends on the number and size of the packages and can take several minutes or more. Until installation completes, the environment is in the preparing state and cannot be referenced by sessions: session creation returns invalid_parameter with the message The environment is still being prepared. Please wait until it is ready and try again.. Once warm-up completes, binding works normally; an environment without pre-installed packages is available immediately after creation. Create environments ahead of time and allow for warm-up before binding sessions.

Archiving and Deletion

Environments support two lifecycle operations:
  • Archiving: The environment is retained but hidden from default listings; sessions already bound to it remain functional.
  • Deletion: Permanent removal — both the environment and its configuration are irreversibly deleted. To preserve configuration, archive instead of deleting.
To archive an environment via API, see the Environment API. 
curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/environments/env_xxx/archive" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"
To delete an environment via API: 
curl -X DELETE "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/environments/env_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Next Steps

Agent Development
Agent Context
Agent Governance & Evolution
Store
Application Marketplace
Use Cases
Support