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 in invitational preview. Submit an Alibaba Cloud support ticket to request access.

• A Team has been created in the FC Agent Sandbox console and its Team ID is known.

• An OSS Bucket has been created and the bucket path to mount has been decided.

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

• The Alibaba Cloud identity that calls the POP SDK has the fcsandbox:CreateVolume permission. Querying Volumes requires fcsandbox:ListVolumes and fcsandbox:GetVolume, and deleting Volumes requires fcsandbox:DeleteVolume.

For how to create a Team and obtain the Team ID, see Create a Team.

Permission configuration

The RAM identity that calls the Volume API needs the following permissions. Replace the placeholders:

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

In production, you can grant Volume resources at Team scope:

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

Install the SDK

The FC Agent Sandbox OpenAPI supports Java, Python, Go, and TypeScript SDKs. For the scope of support, installation, and versioning, see Alibaba Cloud SDK and API Guide. This document uses Python.

python3 -m venv .venv
source .venv/bin/activate
pip install "alibabacloud_fcsandbox20260509>=1.3.0"

Before running 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 using an STS temporary credential, also set:
# export ALIBABA_CLOUD_SECURITY_TOKEN="<your-security-token>"

export FCSANDBOX_REGION_ID="cn-hangzhou"
export FCSANDBOX_ENDPOINT="fcsandbox.cn-hangzhou.aliyuncs.com"
export FCSANDBOX_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"

FCSANDBOX_ENDPOINT does not include https://. If the SDK already ships with a built-in endpoint for the target region, this variable can be omitted; the SDK resolves it based on FCSANDBOX_REGION_ID.

Create an OSS Volume

Request parameters, response parameters, and error codes follow the OpenAPI portal page CreateVolume - Create a Volume.

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_fcsandbox20260509 import models
from alibabacloud_fcsandbox20260509.client import Client as FCSandboxClient
from alibabacloud_tea_openapi import 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("FCSANDBOX_REGION_ID"),
)
if os.environ.get("FCSANDBOX_ENDPOINT"):
    config.endpoint = os.environ["FCSANDBOX_ENDPOINT"]

pop_client = FCSandboxClient(config)
team_id = require_env("FCSANDBOX_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:

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 the mount by reading and writing files.

Manage Volumes

Use ListVolumes to list Volumes, GetVolume to view details, and DeleteVolume to delete a Volume that is no longer needed.

Deleting a Volume only removes its mount configuration from FC Agent Sandbox. It does not delete the OSS Bucket or its data.

Limits

• 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