Agent Sandbox:Mount AgenticBucket dynamically

How it works

When you create a Sandbox, specify the mount in metadata. The system then mounts the BucketSpace or its subdirectory under an AgenticBucket to the Sandbox. After the mount is complete, your application accesses data through the local mount directory.

To add a mount to a running Sandbox, see Append an AgenticBucket mount.

Prerequisites

For more information about AgenticBucket and how its resources are managed, see OSS Agentic Bucket overview.

• You have created an AgenticBucket and obtained its full name.

• You have determined the full name of the BucketSpace that you want to use. You do not need to create the BucketSpace in advance. If the BucketSpace does not exist on the first mount, the system creates it automatically.

• You have obtained the Object Storage Service (OSS) endpoint of the region in which the AgenticBucket resides. For access within the same region, use the internal endpoint. Example: https://oss-<REGION>-internal.aliyuncs.com. You do not need to configure a Virtual Private Cloud (VPC).

• You have prepared an Agent Sandbox API key and an available template.

• You have prepared a Resource Access Management (RAM) role whose trust policy allows the Function Compute service to assume the role. The role has the access permissions required by the target storage. For information about how to configure the role, see Configure a RAM role. For information about storage permission policies, see Create an AgenticBucket Volume.

Install the SDK

Create and activate a Python virtual environment, and then install the E2B SDK:

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

Mount configuration

When you create a Sandbox, provide the following configuration in metadata:

fc.sandbox.storage.agenticbucket uses the following JSON structure. Serialize the structure to a string before you submit the request. You cannot pass a Python dictionary or a JavaScript object directly:

{
  "mountPoints": [
    {
      "agenticBucket": "<AGENTIC-BUCKET-FULL-NAME>",
      "bucketName": "<BUCKET-SPACE-FULL-NAME>",
      "mountDir": "/mnt/agentic-bucket",
      "bucketPath": "/",
      "endpoint": "https://oss-<REGION>-internal.aliyuncs.com",
      "readOnly": false
    }
  ]
}

bucketName uses the full name of the BucketSpace, and bucketPath selects a path under it. To grant read-only access, set readOnly to true.

Agent Sandbox obtains Security Token Service (STS) temporary credentials through the RAM role. You do not need to disable BlockPublicAccess for the AgenticBucket, and you do not need to provide long-term AccessKey pairs (AK/SK) in the mount configuration. The mount configuration does not expand the authorization scope of the RAM role.

Environment variables

Mount and verify

Set the environment variables and replace the placeholders in the examples. The API endpoint, the template, and the storage must use matching regions and network configurations:

export E2B_API_KEY="<YOUR-E2B-API-KEY>"
export E2B_API_URL="https://api.<REGION>.sandbox.aliyuncs.com"
export E2B_DOMAIN="<REGION>.sandbox.aliyuncs.com"
export E2B_TEMPLATE="<TEMPLATE-ID>"

export AGENTIC_BUCKET_NAME="<AGENTIC-BUCKET-FULL-NAME>"
export BUCKET_SPACE_NAME="<BUCKET-SPACE-FULL-NAME>"
export OSS_ENDPOINT="https://oss-<REGION>-internal.aliyuncs.com"
export SANDBOX_ROLE_ARN="acs:ram::<ACCOUNT-ID>:role/<ROLE-NAME>"

The example creates a separate test file with a random identifier in the local mount directory, writes data to the file, and reads the file for verification. The example then deletes the file and releases the Sandbox that it created. Use a mount configuration that provides read and write permissions.

Save the following code as 11_sandbox_agentic_bucket.py:

import json
import os
from uuid import uuid4

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/agentic-bucket"
marker_path = f"{mount_dir}/hello-agentic-bucket-{uuid4().hex}.txt"
agentic_bucket_config = {
    "mountPoints": [
        {
            "agenticBucket": require_env("AGENTIC_BUCKET_NAME"),
            "bucketName": require_env("BUCKET_SPACE_NAME"),
            "mountDir": mount_dir,
            "bucketPath": "/",
            "endpoint": require_env("OSS_ENDPOINT"),
            "readOnly": False,
        }
    ]
}

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"),
        metadata={
            "fc.sandbox.storage.agenticbucket": json.dumps(agentic_bucket_config),
            "fc.sandbox.auth.role": require_env("SANDBOX_ROLE_ARN"),
        },
    )

    sandbox.files.write(marker_path, "hello agentic bucket\n")
    marker_written = True
    content = sandbox.files.read(marker_path)
    if content != "hello agentic bucket\n":
        raise RuntimeError(f"Unexpected file content: {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("AgenticBucket dynamic mount read/write verification succeeded")

Run the example:

python 11_sandbox_agentic_bucket.py

If the output is AgenticBucket dynamic mount read/write verification succeeded, the read and write verification, the test file cleanup, and the Sandbox release are complete.

Behavior notes

Releasing a Sandbox does not delete the underlying storage data. The example deletes the test file on its own. To retain or clean up other data, handle it in the storage service or through the local mount directory.

Limits

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

• The local mount directory cannot be a system directory or a subdirectory of one, such as /bin, /opt, /var, or /dev. It also cannot contain a hidden directory such as .cache. To access data through a hidden directory, mount the storage to a directory that meets the requirements and then create a symbolic link that points to the local mount directory.

• Local mount directories cannot be duplicated in the same Sandbox. This limit applies across storage types.

• A Sandbox supports up to five AgenticBucket mount points. The mount point limit includes the mounts specified at creation and the mounts appended later. Both directly configured mounts and mounts that reference volumes are counted.

FAQ