Sandbox create instance API: POST /sandboxes-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Create a sandbox instance from a template that has finished building. On success, the response returns the instance sandboxID for subsequent access and management. Compatible with the E2B create-sandbox protocol. Returns 409 if the template has not finished building.

Prerequisites

Configure the endpoint and authentication first. See API overview and authentication.

Endpoint

POST /sandboxes

Create a sandbox instance from a template that has finished building. Compatible with the E2B create-sandbox protocol. Returns 409 if the template has not finished building.

Request body

Field	Required	Type	Description
`templateID`	Yes	string	ID of a template that has been created and finished building.
`timeout`	No	integer	Instance lifetime in seconds. Valid range: [300,604800].
`allow_internet_access`	No	boolean	Whether the instance can access the internet.
`metadata`	No	object	Custom metadata. Both keys and values are strings.
`envVars`	No	object	Instance-level environment variables. Both keys and values are strings.
`autoPause`	No	boolean	Whether to pause the instance when `timeout` expires.
`autoResume`	No	boolean	Whether to resume automatically on connect. The object form `{"enabled": true}` is also accepted.
`lifecycle`	No	object	Lifecycle configuration. Sub-fields: `on_timeout` (string, behavior on expiry; `pause` pauses the instance; an object carrying `action` is also accepted), `auto_resume` (boolean, whether connecting to a paused instance resumes it automatically).
`network`	No	object	Instance-level network configuration. Sub-fields: `allowOut` (array<string>, egress allowlist), `denyOut` (array<string>, egress denylist), `maskRequestHost` (string, optional request Host override), `rules` (object, extended network rules). The aliases `allow_public_traffic`, `allow_out`, `deny_out`, and `mask_request_host` are also accepted.

Request example

curl -X POST "$BASE_URL/sandboxes" \
  -H "Authorization: Bearer $BAILIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "your-template-id",
    "timeout": 3600,
    "allow_internet_access": true,
    "metadata": {"team": "data"},
    "envVars": {"STAGE": "dev"},
    "autoPause": true,
    "lifecycle": {"on_timeout": "pause", "auto_resume": true}
  }'

BASE_URL is https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sandbox, and BAILIAN_API_KEY is your Alibaba Cloud Model Studio API key.

Response example

Returns 201 on success.

{
  "clientID": "your-client-id",
  "sandboxID": "sbx-xxx",
  "bailianSandboxId": "your-bailian-sandbox-id",
  "templateID": "your-template-id",
  "alias": "your-template-alias",
  "envdVersion": "your-envd-version",
  "domain": "your-sandbox-domain",
  "envdAccessToken": "your-envd-access-token",
  "trafficAccessToken": "your-traffic-access-token",
  "envdUrl": "your-envd-url",
  "state": "running"
}

Response fields

Field	Type	Description
`clientID`	string	Client identifier.
`sandboxID`	string	Unique instance ID, used for subsequent lifecycle and data-plane calls.
`bailianSandboxId`	string	Alibaba Cloud Model Studio extension identifier. Usually not needed by developers.
`templateID`	string	Template ID.
`alias`	string	Template alias.
`envdVersion`	string	envd version.
`domain`	string	Data-plane access domain.
`envdAccessToken`	string	envd access token.
`trafficAccessToken`	string	Traffic access token.
`envdUrl`	string	envd access URL.
`state`	string	Instance state, for example `running`.