Agent Sandbox:Create a JuiceFS Volume

Storage configuration

The fields of juiceFSVolumeConfig correspond to the Python SDK parameters as follows:

remoteDir specifies the remote directory in the JuiceFS file system, which is different from the local mount directory in the Sandbox. If you set the parameter to /datasets/project-a, the mounted content comes from this subdirectory. If the directory does not exist, the system creates the directory during the mount. Use a remote absolute path that starts with /, and make sure that the token has the permissions required to create and access the destination directory.

The platform converts remoteDir into the --subdir parameter of the JuiceFS client.

Do not print the request body, the JuiceFS token, or other credentials in logs.

Mount configuration

mountConfig.vpcConfig stores the VPC configurations required to access the JuiceFS service. The configurations are used when a Sandbox is created. The corresponding Python SDK parameter is mount_config.vpc_config, which is constructed by using models.CreateVolumeInputMountConfigVpcConfig.

mountConfig.vpcConfig is optional. If you configure the parameter, you must specify all the vpcId, securityGroupId, and vSwitchIds fields. The example in this topic stores the VPC configurations in the volume and reuses the configurations when a Sandbox is created. The VPC configurations can also be provided by using fc.sandbox.network.vpc in the metadata when you create a Sandbox. If the configurations are specified in both locations, the metadata takes precedence.

JuiceFS uses a token to access a file system. To mount JuiceFS, you do not need to configure mountConfig.role. The local mount directory in the Sandbox is specified by volume_mounts during the mount.

Environment variables

The following environment variables are read by the example in this topic. Configure the access credentials as described in the SDK instructions in Step 1, and set the other parameters in the creation example.

Creation example

In a terminal in which the access credentials are configured, set the following parameters and replace the placeholders with actual values. For the value of each variable, see Environment variables in this topic.

export SANDBOX_REGION_ID="<REGION>"
export SANDBOX_ENDPOINT="sandbox.${SANDBOX_REGION_ID}.aliyuncs.com"

export SANDBOX_TEAM_ID="<TEAM-ID>"
export SANDBOX_VOLUME_NAME="juicefs-workspace"

export JUICEFS_VOLUME_NAME="<JUICEFS-FILE-SYSTEM-NAME>"
export JUICEFS_BASE_URL="https://<JUICEFS-SERVICE-ADDRESS>"
export JUICEFS_TOKEN="<JUICEFS-TOKEN>"
export JUICEFS_REMOTE_DIR="/"

export SANDBOX_VPC_ID="<VPC-ID>"
export SANDBOX_SECURITY_GROUP_ID="<SECURITY-GROUP-ID>"
export SANDBOX_VSWITCH_ID="<VSWITCH-ID>"

Save the following code as 01_create_juicefs_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"),
    endpoint=require_env("SANDBOX_ENDPOINT"),
)

pop_client = SandboxClient(config)
response = pop_client.create_volume(
    models.CreateVolumeRequest(
        body=models.CreateVolumeInput(
            team_id=require_env("SANDBOX_TEAM_ID"),
            volume_name=require_env("SANDBOX_VOLUME_NAME"),
            mount_config=models.CreateVolumeInputMountConfig(
                vpc_config=models.CreateVolumeInputMountConfigVpcConfig(
                    vpc_id=require_env("SANDBOX_VPC_ID"),
                    security_group_id=require_env("SANDBOX_SECURITY_GROUP_ID"),
                    v_switch_ids=[require_env("SANDBOX_VSWITCH_ID")],
                ),
            ),
            juice_fsvolume_config=models.JuiceFSVolumeConfig(
                volume_name=require_env("JUICEFS_VOLUME_NAME"),
                base_url=require_env("JUICEFS_BASE_URL"),
                remote_dir=require_env("JUICEFS_REMOTE_DIR"),
                token=require_env("JUICEFS_TOKEN"),
                args=[],
            ),
        )
    )
)

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}")

Run the script in the same terminal:

python 01_create_juicefs_volume.py

CreateVolume does not check the network connectivity of the JuiceFS service, and does not perform the actual mount. Create a Sandbox as described in Mount a JuiceFS Volume, and confirm that the mount is available by reading and writing data.