Agent Sandbox:Append an AgenticFS mount

AgenticFS mount parameters

The following fields are in inlineVolumeMounts.agenticFS. If you specify the configuration directly, configure the fields as described in the following table:

Local mount directory

mountDir and namedVolumeMounts[].path both specify the local mount directory in the Sandbox. Configure them separately from the remote directory in the Access Point address. Use a subdirectory of /home, /mnt, /tmp, or /data. For information about the directory limits, see Limits.

Specify the mount configuration directly

The following example appends the directory specified in the Access Point address to /mnt/agenticfs and verifies read and write operations. Make sure that the RAM role and the directory permissions allow read and write operations.

export AGENTICFS_SERVER_ADDR="ap-<ACCESS-POINT-ID>.<FILE-SYSTEM-ID>-<SUFFIX>.<REGION>.nas.aliyuncs.com:/"

Save the following code as append_agenticfs.py. Before you run the code, make sure that mount_dir is not used by an existing mount:

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

payload = {
    "inlineVolumeMounts": {
        "agenticFS": {
            "mountPoints": [{
                "serverAddr": require_env("AGENTICFS_SERVER_ADDR"),
                "mountDir": mount_dir,
            }],
        },
    },
}

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)

Run the example:

python append_agenticfs.py

The example does not set userID or groupID. The UID or GID of a new mount cannot conflict with the existing configuration of the current Sandbox. This requirement also applies to an append mount that references a volume by name. For information about how to configure a remote subdirectory, see Mount AgenticFS dynamically.

Reference an existing volume

If an AgenticFS volume already exists, replace the payload definition in the preceding script with the following content before the first run, and keep the rest of the code unchanged. Replace name with the name of a volume in the same team. The volume must allow read and write operations for the verification to pass.

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

Select one of the two preceding methods for a single run. You cannot append to the same mount directory twice. If the mount succeeds but the verification fails, run only the connection and verification code again. Do not submit the append request again.

If you combine a direct configuration and a volume reference, put both configurations in the same request body and specify a different local mount directory for each mount point. For the complete procedure and the multi-volume examples that reference volumes by name, see Append a volume mount.

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 Manage API keys. This type of rejection occurs at the API authorization stage. Adjusting the RAM role of the storage does not resolve it.

Why does the system report that the volume cannot be found when I mount by name?

Check the volume name in the request, the team that owns the API key, and the region of the API endpoint. Make sure that you use the name of a volume in the same team instead of a volume ID. For more information, see Append a volume mount.

Why does the system report that the volume is unavailable when I mount by name?

Query the status and the status reason of the volume by using GetVolume. Mount the volume only after you confirm that it is available. If a failure reason exists, resolve it first. For more information, see Append a volume 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 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. For more information, see Configure a RAM role.

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 of a new volume does not complete it.

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

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

If the error message contains requested storage UID/GID conflicts with the active FC Session, the UID or GID specified for the new mount conflicts with the existing configuration of the current Sandbox.

If you specify the configuration directly, check inlineVolumeMounts.agenticFS.userID and groupID. If you reference a volume, check the UID and GID configuration of the volume. Use a configuration compatible with the current Sandbox. If you need a different identity configuration, create another Sandbox. For more information about the impact of releasing and recreating a Sandbox, see Limits.

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, and whether a 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.

If the issue persists, or if the API reports that the service is temporarily unavailable, retain the complete error message and the request ID, and contact technical support.