Create an OSS Volume

CreateVolume only creates Volume metadata. It does not create, delete, or copy OSS buckets or objects.

Prerequisites

For OSS product concepts and resource management, see Bucket overview.

Before you begin, prepare the following:

• Volumes are still in invitational preview. Submit an Alibaba Cloud ticket to request access.

• A Team has been created in the Agent Sandbox console, and the Team ID has been obtained.

• An OSS bucket has been created, and the bucket path to mount has been determined.

• The OSS endpoint of the bucket region has been obtained. For the valid values, see Access OSS via endpoints and bucket domains.

• The Alibaba Cloud identity that calls the OpenAPI SDK has the sandbox:CreateVolume permission. Querying Volumes requires the sandbox:ListVolumes and sandbox:GetVolume permissions, and deleting Volumes also requires the sandbox:DeleteVolume permission.

To create a Team and get its Team ID, see Create a Team.

Permission configuration

Permissions required for Resource Access Management (RAM) users to create a Volume

The RAM identity that calls the Volume API requires the following permissions.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sandbox:CreateVolume",
        "sandbox:ListVolumes",
        "sandbox:GetVolume",
        "sandbox:DeleteVolume"
      ],
      "Resource": "*"
    }
  ]
}

In production, access to Volume resources can be granted at the Team level. Replace region, account-id and team-id in the following resource ARN:

acs:sandbox:<region>:<account-id>:teams/<team-id>/volumes/*

Permissions required for the RAM role used for dynamic sandbox mounting

Add the following access policy to the RAM role configured for the Volume:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetObject",
        "oss:ListObjects",
        "oss:AbortMultipartUpload",
        "oss:CompleteMultipartUpload",
        "oss:DeleteObject",
        "oss:InitiateMultipartUpload",
        "oss:ListParts",
        "oss:PutObject",
        "oss:UploadPart",
        "oss:PutBucket"
      ],
      "Resource": "*"
    }
  ]
}

Install the SDK

Agent Sandbox Flash Edition OpenAPI currently supports the Java, Python, Go, and TypeScript SDKs. For the supported scope, installation methods, and versions, see Alibaba Cloud SDK and API guide. This topic uses Python in its examples.

python3 -m venv .venv
source .venv/bin/activate
pip install "alibabacloud_sandbox20260820>=1.2.0"

Before you run the example, set the following environment variables:

export ALIBABA_CLOUD_ACCESS_KEY_ID="<YOUR-ACCESS-KEY-ID>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<YOUR-ACCESS-KEY-SECRET>"
# When you use an STS temporary credential, also set:
# export ALIBABA_CLOUD_SECURITY_TOKEN="<YOUR-SECURITY-TOKEN>"

export SANDBOX_REGION_ID="cn-hangzhou"
export SANDBOX_ENDPOINT="sandbox.cn-hangzhou.aliyuncs.com"
export SANDBOX_TEAM_ID="<team-id>"

export OSS_BUCKET_NAME="<bucket-name>"
export OSS_BUCKET_PATH="/agent-workspace"
export OSS_ENDPOINT="https://oss-cn-hangzhou.aliyuncs.com"

SANDBOX_ENDPOINT does not include https://. If the SDK has a built-in endpoint for the target region, this variable can be omitted. The SDK then resolves the endpoint based on SANDBOX_REGION_ID.

Create an OSS Volume

For request parameters, response parameters, and error codes, see the CreateVolume - Create a Volume page in the OpenAPI portal.

OSSVolumeConfig fields:

The following example creates an OSS Volume and prints the result. Save the code as 07_create_oss_volume.py:

import os

from alibabacloud_sandbox20260820 import models
from alibabacloud_sandbox20260820.client import Client as SandboxClient
from alibabacloud_tea_openapi import utils_models as open_api_models


def require_env(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise RuntimeError(f"Missing environment variable: {name}")
    return value


config = open_api_models.Config(
    access_key_id=require_env("ALIBABA_CLOUD_ACCESS_KEY_ID"),
    access_key_secret=require_env("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
    security_token=os.environ.get("ALIBABA_CLOUD_SECURITY_TOKEN"),
    region_id=require_env("SANDBOX_REGION_ID"),
)
if os.environ.get("SANDBOX_ENDPOINT"):
    config.endpoint = os.environ["SANDBOX_ENDPOINT"]

pop_client = SandboxClient(config)
team_id = require_env("SANDBOX_TEAM_ID")

response = pop_client.create_volume(
    models.CreateVolumeRequest(
        body=models.CreateVolumeInput(
            team_id=team_id,
            volume_name="oss-workspace",
            oss_volume_config=models.OSSVolumeConfig(
                bucket_name=require_env("OSS_BUCKET_NAME"),
                bucket_path=require_env("OSS_BUCKET_PATH"),
                endpoint=require_env("OSS_ENDPOINT"),
                read_only=False,
            ),
        )
    )
)

if response.body is None or response.body.volume is None:
    raise RuntimeError("CreateVolume did not return a Volume")

volume = response.body.volume
print(f"request_id={response.body.request_id}")
print(f"volume_id={volume.volume_id}")
print(f"volume_name={volume.volume_name}")
print(f"storage_class={volume.storage_class}")
print(f"status={volume.status}")

print("OSS Volume created")

Run the example to create the Volume and print the creation result:

python 07_create_oss_volume.py

Successful creation only means that the Volume metadata has been created. See Mount an OSS Volume to mount the Volume into a sandbox and verify that the mount works by reading and writing data.

Manage Volumes

Use ListVolumes to list Volumes, GetVolume to view details, and DeleteVolume to delete Volumes that are no longer in use.

Deleting a Volume only removes the Volume metadata on the Agent Sandbox Flash Edition side. It does not delete the OSS bucket or the data in it.

Limits

• For security reasons, OSS mounts do not currently support SSE-KMS (server-side encryption with keys managed by Key Management Service).

• The OSS endpoint must match the region and network environment of the bucket.

• bucket_path is required. To mount the bucket root, set it to /.

• Volume names must be unique within a Team.

FAQ