Function Compute:Dynamic OSS Mounts

OSS dynamic mounting is configured through Sandbox metadata — you do not need to bake mount configuration into the template. When creating a Sandbox, pass:

• fc.sandbox.storage.oss: OSS mount configuration, as a JSON string.

• fc.sandbox.auth.role: The RAM Role ARN used to access OSS.

Prerequisites

Before use, prepare the following:

• OSS Bucket name.

• OSS Endpoint, for example https://oss-cn-hangzhou.aliyuncs.com.

• RAM Role ARN. This role must be granted the assumable permission for the Function Compute service and have OSS permissions to access the target Bucket or Bucket subdirectory.

• Mount directory inside the Sandbox, for example /mnt/oss.

Only authorize the Bucket subdirectory required by the task. Do not expose an entire Bucket as writable to untrusted code.

Mount configuration

The value of fc.sandbox.storage.oss is a JSON string with the following structure:

{
  "mountPoints": [
    {
      "bucketName": "example-bucket",
      "mountDir": "/mnt/oss",
      "bucketPath": "/e2b-test",
      "endpoint": "https://oss-cn-hangzhou.aliyuncs.com",
      "readOnly": false
    }
  ]
}

Field descriptions:

Create a Sandbox with OSS mounts

The following example creates a Sandbox with dynamic OSS mounts and lists the files under the mount directory.

import json
import os
import sys

from dotenv import load_dotenv
from e2b import Sandbox

load_dotenv()

api_key = os.environ.get("E2B_API_KEY")
api_url = os.environ.get("E2B_API_URL")
domain = os.environ.get("E2B_DOMAIN")
oss_bucket = os.environ.get("E2E_OSS_BUCKET")
oss_endpoint = os.environ.get("E2E_OSS_ENDPOINT")
role_arn = os.environ.get("E2E_ROLE_ARN")

if not api_key:
    print("Error: E2B_API_KEY environment variable not set")
    sys.exit(1)
if not oss_bucket:
    print("Error: E2E_OSS_BUCKET environment variable not set")
    sys.exit(1)
if not oss_endpoint:
    print("Error: E2E_OSS_ENDPOINT environment variable not set")
    sys.exit(1)
if not role_arn:
    print("Error: E2E_ROLE_ARN environment variable not set")
    sys.exit(1)

conn_opts = {}
if api_url:
    conn_opts["api_url"] = api_url
if domain:
    conn_opts["domain"] = domain

mount_dir = "/mnt/oss"
oss_config = {
    "mountPoints": [
        {
            "bucketName": oss_bucket,
            "mountDir": mount_dir,
            "bucketPath": "/e2b-test",
            "endpoint": oss_endpoint,
            "readOnly": False,
        }
    ]
}

sandbox = Sandbox.create(
    api_key=api_key,
    timeout=300,
    **conn_opts,
    metadata={
        "fc.sandbox.storage.oss": json.dumps(oss_config),
        "fc.sandbox.auth.role": role_arn,
    },
)

try:
    print(f"Sandbox created: {sandbox.sandbox_id}")

    files = sandbox.files.list(mount_dir)
    print(f"OSS files: {[file.name for file in files]}")
finally:
    sandbox.kill()

Set environment variables before running:

export E2B_API_KEY=your-api-key
export E2B_API_URL=your-api-url
export E2B_DOMAIN=your-domain

export E2E_OSS_BUCKET=your-bucket
export E2E_OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
export E2E_ROLE_ARN=acs:ram::1234567890123456:role/your-role

python 04_sandbox_oss.py

Read and write the mount directory

After a successful mount, you can access mountDir through the Filesystem API or commands inside the Sandbox.

mount_dir = "/mnt/oss"

# List the mount directory through the Filesystem API.
files = sandbox.files.list(mount_dir)
print([file.name for file in files])

# Write a file inside the Sandbox. This will fail when readOnly=true.
result = sandbox.commands.run(
    f"python3 - <<'PY'\n"
    f"from pathlib import Path\n"
    f"path = Path({mount_dir!r}) / 'outputs' / 'result.txt'\n"
    f"path.parent.mkdir(parents=True, exist_ok=True)\n"
    f"path.write_text('sandbox task finished\\n', encoding='utf-8')\n"
    f"print(path)\n"
    f"PY"
)
print(result.stdout.strip())

Permission recommendations

• Use readOnly: true to mount input data directories to prevent tasks from accidentally modifying or deleting source data.

• Use a separate prefix for write results, for example tenants/<tenant-id>/tasks/<task-id>/outputs/.

• Scope the RAM Policy to only the object prefixes required by the task. Grant oss:ListObjects and oss:GetObject for read-only tasks; add oss:PutObject, oss:DeleteObject, oss:AbortMultipartUpload, and oss:ListParts as needed for read-write tasks.

• Do not write long-term AK/SK into code, templates, or metadata. Access OSS through the RAM Role specified by fc.sandbox.auth.role.

Notes

• fc.sandbox.storage.oss must be a valid JSON string. Do not pass a Python dict or JavaScript object directly.

• OSS mounts require fc.sandbox.auth.role to be configured as well; otherwise the Sandbox cannot obtain permissions to access OSS.

• The endpoint must match the Bucket's region; cross-region access may cause higher latency or access failures.

• bucketPath should use absolute paths, for example /e2b-test. Use / for the root directory.

• mountDir should avoid conflicts with existing system directories in the template. Recommended paths: /mnt/oss or /home/user/oss.

• Configure OSS lifecycle cleanup rules for temporary artifacts when appropriate.