Mount an OSS Volume

Prerequisites

• An OSS Volume has been created for the target Team, and its Volume name is available.

• An FC Agent Sandbox API key bound to the same Team is ready. A Volume and API key cannot be used across Teams.

• A function execution RAM Role is ready. The Role has permissions on the target OSS path, and its trust policy allows the Function Compute service to assume it.

• The FC Agent Sandbox API URL, domain, and an available template are ready.

Configure permissions

Attach the following permission policy to the function execution RAM Role:

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

The Role's trust policy must also allow the Function Compute service to assume it. For more information, see Policies and examples.

Install the SDK

This topic uses the E2B Python SDK. volume_mounts requires E2B Python SDK 2.31.0 or later.

python3 -m venv .venv
source .venv/bin/activate
pip install "e2b>=2.31.0"

Set the following environment variables before running the example:

export E2B_API_KEY="<your-e2b-api-key>"
export E2B_API_URL="https://api.<region>.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="<region>.e2b.fc.aliyuncs.com"
export E2B_TEMPLATE="code-interpreter-v1"

export OSS_VOLUME_NAME="oss-workspace"
export FCSANDBOX_ROLE_ARN="acs:ram::<account-id>:role/<execution-role>"

Mount and verify

The following example mounts the OSS Volume to /mnt/oss and verifies file read/write. The Volume must not be read-only. Save the code as 01_mount_oss_volume.py:

import os

from e2b import Sandbox


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


mount_dir = "/mnt/oss"
marker_path = f"{mount_dir}/hello-oss.txt"
sandbox = None
marker_written = False

try:
    sandbox = Sandbox.create(
        template=require_env("E2B_TEMPLATE"),
        timeout=300,
        api_key=require_env("E2B_API_KEY"),
        api_url=require_env("E2B_API_URL"),
        domain=require_env("E2B_DOMAIN"),
        volume_mounts={mount_dir: require_env("OSS_VOLUME_NAME")},
        metadata={
            "fc.sandbox.auth.role": require_env("FCSANDBOX_ROLE_ARN"),
        },
    )

    info = sandbox.get_info()
    print(f"volume_mounts={info.volume_mounts}")

    sandbox.files.write(marker_path, "hello oss\n")
    marker_written = True
    content = sandbox.files.read(marker_path)
    if content != "hello oss\n":
        raise RuntimeError(f"file content mismatch: {content!r}")
finally:
    try:
        if sandbox is not None and marker_written:
            sandbox.files.remove(marker_path)
    finally:
        if sandbox is not None:
            sandbox.kill()

print("OSS Volume mount read/write verification succeeded")

Run the example:

python 01_mount_oss_volume.py

Behavior

• volume_mounts uses the {mount directory: Volume name} format, not a Volume ID.

• A sandbox restores the Volume mount after it is paused and resumed. OSS data is independent of the sandbox lifecycle.

• A read-only Volume can only read files under the mount path.

Limits

• A single sandbox can mount at most five OSS Volumes.

• The mount directory must be a normalized absolute Unix path. It cannot be /, and it cannot contain leading or trailing whitespace or ...

• Mount directories in the same sandbox cannot be duplicated. We recommend /mnt/oss or a subdirectory to avoid overriding directories from the template.

FAQ