Mount an AgenticFS Volume

Prerequisites

• An AgenticFS Volume has been created for the target Team, and its Volume name is available.

• An FC Agent Sandbox API key bound to the same Team is ready. A Volume and API key cannot be used across Teams.

• A VPC, vSwitch, and security group that can reach the AgenticFS Access Point are ready.

• A function execution RAM Role is ready. The Role has AgenticFS mount and read/write permissions, and its trust policy allows the Function Compute service to assume it.

• The FC Agent Sandbox API URL, domain, and an available template are ready.

Note: Before creating a sandbox, make sure that the corresponding AgenticFS Access Point is in the active state. Otherwise, the createSandbox call may time out or fail. To check the status, log on to the AgenticFS console, find the corresponding FileSystem, go to the FileSystem details page, and click Mount and Use to view the mount point status.

Configure permissions

Attach the following permission policy to the function execution RAM Role:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "nas:ClientMount",
        "nas:ClientWrite",
        "nas:ClientRootAccess"
      ],
      "Resource": "*"
    }
  ]
}

The Role's trust policy must also allow the Function Compute service to assume it. For more information, see Policies and examples.

Install the SDK

This topic uses the E2B Python SDK. volume_mounts requires E2B Python SDK 2.31.0 or later.

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

Set the following environment variables before running the example:

export E2B_API_KEY="<your-e2b-api-key>"
export E2B_API_URL="https://api.<region>.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="<region>.e2b.fc.aliyuncs.com"
export E2B_TEMPLATE="code-interpreter-v1"

export AGENTICFS_VOLUME_NAME="agent-workspace"
export FCSANDBOX_VPC_ID="vpc-xxxxxxxx"
export FCSANDBOX_SECURITY_GROUP_ID="sg-xxxxxxxx"
export FCSANDBOX_VSWITCH_ID="vsw-xxxxxxxx"
export FCSANDBOX_ROLE_ARN="acs:ram::<account-id>:role/<execution-role>"

Mount and verify

The following example mounts the AgenticFS Volume to /mnt/agenticfs and verifies file read/write. Save the code as 02_mount_agenticfs_volume.py:

import json
import os

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


vpc_config = {
    "vpcId": require_env("FCSANDBOX_VPC_ID"),
    "securityGroupId": require_env("FCSANDBOX_SECURITY_GROUP_ID"),
    "vSwitchIds": [require_env("FCSANDBOX_VSWITCH_ID")],
}

mount_dir = "/mnt/agenticfs"
marker_path = f"{mount_dir}/hello-agenticfs.txt"
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"),
        volume_mounts={mount_dir: require_env("AGENTICFS_VOLUME_NAME")},
        metadata={
            "fc.sandbox.network.vpc": json.dumps(vpc_config),
            "fc.sandbox.auth.role": require_env("FCSANDBOX_ROLE_ARN"),
        },
    )

    info = sandbox.get_info()
    print(f"volume_mounts={info.volume_mounts}")

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

Run the example:

python 02_mount_agenticfs_volume.py

Behavior

• volume_mounts uses the {mount directory: Volume name} format, not a Volume ID.

• A sandbox restores the Volume mount after it is paused and resumed. AgenticFS data is independent of the sandbox lifecycle.

Limits

• When creating the sandbox, fc.sandbox.network.vpc must include vpcId, securityGroupId, and a non-empty vSwitchIds. VPC configuration in the template does not replace this metadata.

• A single sandbox can mount at most five AgenticFS Volumes.

• When multiple AgenticFS Volumes are mounted into one sandbox, all Volumes must use identical user_id and group_id settings.

• The mount directory has a maximum length of 128 characters and must be a normalized absolute Unix path. It cannot be /, and it cannot contain leading or trailing whitespace or ...

• Mount directories in the same sandbox cannot be duplicated. We recommend /mnt/agenticfs or a subdirectory to avoid overriding directories from the template.

FAQ