Mount an AgenticFS Volume

Step 1: Pre-install storage clients when you create a template

This step applies only if you use a custom template of the second-generation runtime (MicroVM). If you already have a template that meets the requirements, skip this step and go to Step 2: Install the SDK.

When you create a custom template with the second-generation runtime (MicroVM), use buildConfig.installStorageClients to automatically install the persistent storage clients. This parameter supports only the second-generation runtime. Set generation: 2 in runtimeConfig.sandboxConfig.

For a request body example and the complete limits, see the "Install storage clients" section in Build and manage custom templates with code.

After you enable this parameter, Template Build pre-installs the aliyun-alinas-utils (mount.alinas) client and the nfs-common package that this topic requires, together with their dependencies, into the template image. This parameter does not create storage resources, perform mounts, or configure the network and access credentials. When you create a Sandbox, you must still configure the mount parameters, the network, and the access credentials as described in this topic. Then verify that the mount is available by performing actual read and write operations.

Step 2: Install the SDK

This topic uses the E2B Python SDK for demonstration. volume_mounts requires E2B Python SDK 2.31.0.

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

Step 3: Mount and verify

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 E2B_TEMPLATE="code-interpreter-v1"

export AGENTICFS_VOLUME_NAME="agent-workspace"

import os
from uuid import uuid4

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


mount_dir = "/mnt/agenticfs"
marker_path = f"{mount_dir}/hello-agenticfs-{uuid4().hex}.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")},
    )

    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 read/write verification passed")

python 02_mount_agenticfs_volume.py

The system reports 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. When you mount by name, use an existing volume in the same Team. Do not specify a volume ID.

The volume exists, but why does the system report that it is unavailable?

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, address the cause first. Submitting the mount request again does not make the volume available.

Sandbox creation reports a missing RAM role

If the error message contains AgenticFS mount requires Function role, the system did not obtain the RAM role required for the mount.

The example in this topic obtains the role from the mountConfig.role of the volume. If the metadata of the creation request explicitly sets fc.sandbox.auth.role, that value takes precedence. Check the role configuration actually used, add a valid role ARN (Alibaba Cloud Resource Name), and then submit the creation request again. For information about how to configure the role, see Configure a RAM role.

The VPC is configured, but why does the system report an incomplete configuration?

If the error message contains mount requires complete VPC config, the VPC configuration used for this creation is missing required fields.

If you did not specify a VPC in the metadata, check the mountConfig.vpcConfig of the volume. If you specified a VPC, check fc.sandbox.network.vpc. The configuration actually used must contain vpcId, securityGroupId, and a non-empty vSwitchIds. The metadata configuration takes precedence. The system does not use the fields of the volume to complete an incomplete metadata configuration.

Sandbox creation times out or the mount fails

If the error message does not indicate a specific parameter issue, check the actual mount conditions in the following order:

1. Make sure that the Access Point is in the active state, and that the address and the remote directory match the values you set when creating the volume.

2. Check the routes of the VPC used by the Sandbox, the security group, and the connectivity between the Sandbox and the Access Point.

3. Check the RAM role actually used. Make sure that the trust policy allows the Function Compute service to assume the role and that the role has the access permissions required by the destination storage.

4. If you use a custom template of the second-generation runtime, verify that the AgenticFS client is installed. For the installation steps, see Step 1: Pre-install storage clients when you create a template in this topic.

The volume is mounted, but file read and write operations fail

First, make sure that your application accesses the local mount directory that you specified. Then, based on the error returned for the file operation, check the directory permissions, the UID, and the GID. Verify whether the RAM role actually used has the read and write permissions. The access status of the Access Point must also be normal.

To troubleshoot further, retain the complete error message and the request ID.