Agent Sandbox:Append a volume mount

Step 1: Install the SDK

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

pip install e2b==2.31.0 httpx

Step 2: Append volume mounts

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

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>"

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")

mounts = [
    {"name": "oss-workspace", "path": "/mnt/oss"},
]
payload = {"namedVolumeMounts": mounts}

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,
)

for mount in mounts:
    verify_read_write(sandbox, mount["path"])

python append_volume.py

mounts = [
    {"name": "project-data", "path": "/mnt/project"},
    {"name": "project-results", "path": "/mnt/results"},
]

Step 3: Verify the mount

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

For a volume that allows only read operations, perform read verification only. Before the first run, replace the verification loop at the end of the script with the following code. This example uses /mnt/oss. Replace <EXISTING-FILE> with the relative path of a file that already exists in the mount directory:

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

If the volumes in a Sandbox have different read and write permissions, read a known file for each read-only mount, and call verify_read_write(sandbox, mount_dir) for each writable mount. Do not perform write verification on read-only mounts.

After the connection succeeds, the SDK can also return the volume names and mount directories:

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. The existence of a mount record and a directory does not mean that data access works. You must still verify file read or write access.

Why is the request rejected by the API key policy?

If the error message is request is not allowed by API key policy, check whether the API key policy allows the mount method and the storage type of this request. For more information, see Create an API Key. This type of rejection occurs at the API authorization stage. Adjusting the RAM role of the storage does not resolve it.

Why does the append mount report a UID or GID conflict for AgenticFS?

Check the UID and GID configuration of the new volume, and make sure that the configuration is compatible with the existing configuration of the current Sandbox. For more information, see Append an AgenticFS mount.

Why does the append mount report a JuiceFS service address conflict?

Check the baseURL of the new volume, and make sure that it uses the same service address as the existing JuiceFS mounts of the current Sandbox. For more information, see Append a JuiceFS mount.

Why does the append mount report that the Sandbox is not running?

If the error message is sandbox must be running, confirm that the target Sandbox is in the running state. If the Sandbox is paused, resume it first. If the Sandbox is released, recreate it.

Why does the system report that the volume cannot be found?

If the error message is volume not found, check the volume name in the request, the team that owns the API key, and the region of the API endpoint. To mount by name, use a volume that exists in the same team. Volume IDs are not supported.

Why does the system report that the volume is unavailable if the volume already exists?

If the error message contains is not available, the volume exists, but its status does not meet the mount requirements. Query the status and the status reason of the volume by using GetVolume, and mount the volume only after you confirm that it is available. If a failure reason exists, resolve it first. Submitting the mount request again does not make the volume available.

Why does the append mount report a missing RAM role?

If the error message contains FC Function execution Role is required, the current Sandbox is not configured with the required RAM role. The append mount operation uses the current role and does not set the role for the Sandbox from the mountConfig.role of the new volume.

Prepare a role that has the access permissions on the target storage, and configure the role when you recreate the Sandbox.

Why does the append mount report an incomplete VPC configuration for the Sandbox?

If the error message contains FC Function complete VPC configuration is required, the missing configuration belongs to the current Sandbox. The mountConfig.vpcConfig in the append request or in the new volume does not supply the missing configuration.

When you recreate the Sandbox, configure the complete vpcId, securityGroupId, and a non-empty vSwitchIds. When you create the Sandbox, provide these values by using metadata, or use the VPC configuration that the referenced volume stores.

Why does the append mount report a duplicate mount directory?

If the error message contains duplicate mount path or duplicate mount dir, check whether the local mount directories in this request are duplicated. Also verify that no directory is already used by another mount in the Sandbox. Different storage types cannot share the same local mount directory.

Do not submit existing mounts again. Use an unused directory for the new mount. The append mount operation cannot overwrite or replace existing mounts.

Why is the mount limit exceeded when I append only one mount point?

The number of mounts is calculated from the existing mounts of the Sandbox and the new mounts in this request. Both mounts that specify the configuration directly and mounts that reference volumes are counted. Do not check only the number of mounts in this request.

Check the number of mounts for the corresponding storage type as described in Limits of this topic. If the limit is reached, mount the new storage in another Sandbox. Changing the local mount directory does not reduce the number of existing mounts.