Agent Sandbox:Append an AgenticBucket mount

How it works

When you append a mount to a Sandbox in the running state, you can specify the AgenticBucket mount configuration directly, or reference an existing AgenticBucket volume by name.

This topic describes how to append an AgenticBucket mount to a running Sandbox. To specify the mount configuration when you create a Sandbox, see Mount AgenticBucket dynamically.

Prerequisites

• The Sandbox is in the running state. If the Sandbox is paused, resume it first.

• The API key that is used in the request belongs to the same team as the target Sandbox.

• An AgenticBucket is created, and you know the full name of the BucketSpace that you want to access. 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.

• The Sandbox is configured with a Resource Access Management (RAM) role, and the role has the access permissions on the target AgenticBucket and BucketSpace.

• You have obtained the Object Storage Service (OSS) endpoint of the region in which the AgenticBucket resides. For access within the same region, the internal endpoint is recommended and requires no additional Virtual Private Cloud (VPC) configuration.

• If you reference an existing volume, create the volume in the same team as described in Create an AgenticBucket Volume, and obtain the name of an available volume.

An append mount uses the current RAM role of the Sandbox. The append mount operation does not set or replace the role. If you reference an existing volume, the mountConfig.role of the volume does not replace the current role. For information about how to configure the role when you create a Sandbox, see Configure a RAM role.

For information about storage permission policies, see "Configure storage access permissions" in Create an AgenticBucket Volume. For information about the client requirements of the second-generation runtime, see Mount an AgenticBucket Volume.

The 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 in code or in the mount configuration. An append mount does not expand the authorization scope of the RAM role.

API operation and parameters

POST /sandboxes/{sandboxID}/fc-volume-mounts

The request headers must include X-API-Key and Content-Type: application/json. If the call succeeds, the API returns 204 No Content with an empty response body.

The request body supports both a direct mount configuration and references to existing volumes. The two methods can be combined in a single request:

The request must contain at least one valid mount point. The mount configuration in an append request is a JSON object, instead of the metadata parameter or a JSON string that is used when you create a Sandbox. Note the letter case: the metadata key that is used at creation is fc.sandbox.storage.agenticbucket, but the field in an append request is agenticBucket.

Install the SDK

The example uses httpx to call the append mount operation, and then uses the E2B SDK to connect to the existing Sandbox and verify read and write operations.

pip install e2b==2.31.0 httpx

Environment variables

AGENTIC_BUCKET_NAME, BUCKET_SPACE_NAME, and OSS_ENDPOINT are specific to the storage type and are used only when you specify the mount configuration directly. If you reference an existing volume, you do not need to set these variables.

Append mount examples

Set the connection information in your local terminal and replace the placeholders with actual values:

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 SANDBOX_ID="<SANDBOX-ID>"

The following code runs on your local machine and accesses files in the Sandbox through the SDK. The example creates a separate test file with a random identifier, writes data to the file, reads the file for verification, deletes the file, and retains the Sandbox. Use a mount configuration that provides read and write permissions. If the mount allows only read operations, modify the verification code as described in Verify the mount.

Sandbox.connect() updates the timeout of the Sandbox. The example uses timeout=300 to set the timeout after the connection to 300 seconds. Adjust the value based on your task.

Select one of the following methods, or combine both methods in a single request:

• Specify the mount configuration directly: provide the AgenticBucket mount parameters in inlineVolumeMounts.agenticBucket of the request body.

• Reference an existing volume: reference a volume in the same team by name in namedVolumeMounts of the request body.

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"

import os
from uuid import uuid4

import httpx
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


def verify_read_write(sandbox: Sandbox, mount_dir: str) -> None:
    marker_path = f"{mount_dir}/mount-check-{uuid4().hex}.txt"
    expected = f"append mount check {uuid4().hex}\n"
    sandbox.files.write(marker_path, expected)
    try:
        content = sandbox.files.read(marker_path)
        if content != expected:
            raise RuntimeError(f"File content verification failed: {marker_path}")
    finally:
        sandbox.files.remove(marker_path)
    print(f"Read/write verification passed. Test file deleted: {mount_dir}")


api_key = require_env("E2B_API_KEY")
api_url = require_env("E2B_API_URL").rstrip("/")
domain = require_env("E2B_DOMAIN")
sandbox_id = require_env("SANDBOX_ID")
mount_dir = "/mnt/agentic-bucket"

payload = {
    "inlineVolumeMounts": {
        "agenticBucket": {
            "mountPoints": [{
                "agenticBucket": require_env("AGENTIC_BUCKET_NAME"),
                "bucketName": require_env("BUCKET_SPACE_NAME"),
                "bucketPath": "/",
                "endpoint": require_env("OSS_ENDPOINT"),
                "mountDir": mount_dir,
                "readOnly": False,
            }],
        },
    },
}

response = httpx.post(
    f"{api_url}/sandboxes/{sandbox_id}/fc-volume-mounts",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120.0,
)
if response.status_code != 204:
    raise RuntimeError(f"Append mount failed: HTTP {response.status_code}, {response.text}")

sandbox = Sandbox.connect(
    sandbox_id,
    timeout=300,
    api_key=api_key,
    api_url=api_url,
    domain=domain,
)

verify_read_write(sandbox, mount_dir)

python append_agentic_bucket.py

payload = {
    "namedVolumeMounts": [{
        "name": "agentic-bucket-workspace",
        "path": mount_dir,
    }],
}

Verify the mount

The example connects to the Sandbox and verifies file read and write operations only after the API returns 204. The output "Read/write verification passed. Test file deleted" indicates that the write operation, the content comparison, and the deletion are complete.

A read-only mount verifies only read operations. If you specify the mount configuration directly, set readOnly to True. If you reference a volume, use an existing read-only volume. Before the first run, replace verify_read_write(sandbox, mount_dir) at the end of the example with the following code. Then replace <EXISTING-FILE> with the relative path of a file that already exists in the mount directory. A newly created BucketSpace may be empty, so the read verification requires an existing file.

file_path = f"{mount_dir}/<EXISTING-FILE>"
content = sandbox.files.read(file_path, format="bytes")
print(f"Read succeeded: {file_path}, {len(content)} bytes")

For a mount that references a volume, you can also query the mount through the SDK after the connection succeeds:

print(sandbox.get_info().volume_mounts)

In the SDK, the volume_mounts field corresponds to the GET /sandboxes/{sandboxID} response, where the field is named volumeMounts. Mounts that use a direct configuration do not appear in this field and must be verified through file access. The existence of a directory does not mean that data access works.

Behavior notes

Releasing a Sandbox does not delete the data in the BucketSpace. Clean up test files and task data separately in the storage service or through the 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, and 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 mount directory.

• Local mount directories cannot be duplicated in the same Sandbox, including mount directories of different storage types.

• The operation only adds mounts. It does not unmount or replace existing mounts. To remove an existing mount, release and recreate the Sandbox. Omitting an existing mount in a request does not delete it, and submitting the same mount again returns 400.

• The total number of existing and new AgenticBucket mount points cannot exceed 5. Do not count only the mount points in this request.

• The AgenticBucket, BucketSpace, OSS endpoint, and Sandbox must use matching regions and network environments.

• Do not concurrently modify the mounts of the same Sandbox.

FAQ