Agent Sandbox:Append an OSS mount

How it works

When a Sandbox is in the running state, specify the OSS mount configuration directly or reference an existing OSS volume by name.

To specify the mount configuration when you create a Sandbox, see Dynamic OSS Mounts.

Prerequisites

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

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

• The Sandbox is configured with a Resource Access Management (RAM) role, and the role has the permissions to access the destination OSS bucket and object prefix. An OSS mount does not require an additional Virtual Private Cloud (VPC) configuration.

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

The append mount operation uses the current RAM role of the Sandbox. The 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 either. For information about how to configure the role when you create a Sandbox, see Configure a RAM role.

For the template and client requirements, see the image requirements of the second-generation runtime in Mount an OSS Volume.

When you mount OSS, Agent Sandbox obtains Security Token Service (STS) temporary credentials through the RAM role. Agent Sandbox limits the permissions of the credentials based on the bucket, object prefix, and read/write mode that are actually used. The effective permissions cannot exceed the authorization scope of the RAM role. For information about the storage permission policy, see Create an OSS Volume.

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. A single request can combine both methods:

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 or JSON string format used when you create a Sandbox.

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

The storage-specific environment variables are used 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 OSS mount parameters in inlineVolumeMounts.oss of the request body.

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

export OSS_BUCKET_NAME="<BUCKET-NAME>"
export OSS_BUCKET_PATH="/datasets"
export OSS_ENDPOINT="oss-<REGION>.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/datasets"

payload = {
    "inlineVolumeMounts": {
        "oss": {
            "mountPoints": [{
                "bucketName": require_env("OSS_BUCKET_NAME"),
                "bucketPath": require_env("OSS_BUCKET_PATH"),
                "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_oss.py

payload = {
    "namedVolumeMounts": [{
        "name": "oss-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.

If the mount is read-only, verify read operations only. If you specify the 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. In the code, replace <EXISTING-FILE> with the relative path of an existing file in the mount directory:

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

Mounts that reference a volume can also be queried 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 OSS. Clean up test files and task data separately in the storage service or through the mount directory.

Limits

• For security reasons, OSS mounts do not support Key Management Service (KMS) server-side encryption (SSE-KMS).

• 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, even across different storage types.

• The append mount 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.

  Warning

  Releasing a Sandbox cannot be undone. After the Sandbox is released, it cannot be reconnected or resumed. Data that is written only to the local file system of the Sandbox is unavailable, while data in the mounted OSS bucket is retained, as described in Behavior notes.

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

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

FAQ