Agent Sandbox:Mount an AgenticFS Volume

Step 1: Prepare the second-generation runtime image

If you already have a template that meets the requirements, go to Step 2: Install the SDK.

If you use a custom template of the second-generation runtime (MicroVM), you must pre-install the AgenticFS client in the source image before you build the template. The current AgenticFS installation package supports only linux/amd64. The following Dockerfile uses Ubuntu 22.04 by default. You can switch to Debian 12 by using a build argument:

ARG BASE_IMAGE=ubuntu:22.04
FROM ${BASE_IMAGE}

ARG DEBIAN_FRONTEND=noninteractive
ARG ALINAS_DEB_URL=https://aliyun-alinas-eac-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-alinas-utils_2.4-0.20260908115139.ac23e3.amd64.deb
ARG ALINAS_DEB_SHA256=e0866d4a4a8b9fa7dbb3b0dea8ee086e7c8bfe3e79160a5e415935a86ec3367d

RUN set -eux; \
    test -n "${ALINAS_DEB_URL}"; \
    test -n "${ALINAS_DEB_SHA256}"; \
    apt-get update; \
    apt-get install -y --no-install-recommends \
        ca-certificates \
        curl \
        nfs-common; \
    curl -fL --retry 3 \
        "${ALINAS_DEB_URL}" \
        -o /tmp/aliyun-alinas-utils.deb; \
    echo "${ALINAS_DEB_SHA256}  /tmp/aliyun-alinas-utils.deb" \
        | sha256sum -c -; \
    apt-get install -y --no-install-recommends \
        /tmp/aliyun-alinas-utils.deb; \
    rm -f /tmp/aliyun-alinas-utils.deb; \
    rm -rf /var/lib/apt/lists/*; \
    command -v mount.alinas; \
    command -v mount.nfs; \
    mkdir -p /mnt/agenticfs

WORKDIR /root

# Do not set USER, ENTRYPOINT, or CMD. The MicroVM control plane takes over.

AgenticFS is mounted over Network File System (NFS). You do not need to install fuse3, and the mount does not depend on /dev/fuse. Do not write credentials such as AccessKey pairs or tokens into the Dockerfile or image layers. The credentials must be injected in a secure manner at runtime. When you upgrade the installation package, you must update both ALINAS_DEB_URL and ALINAS_DEB_SHA256. Do not skip the SHA-256 verification.

In the directory that contains the Dockerfile, build the Ubuntu 22.04 image:

docker buildx build \
  --platform linux/amd64 \
  --load \
  -t microsandbox-agenticfs:ubuntu22.04-alinas-utils-2.4 \
  .

Build the Debian 12 image:

docker buildx build \
  --platform linux/amd64 \
  --build-arg BASE_IMAGE=debian:12-slim \
  --load \
  -t microsandbox-agenticfs:debian12-alinas-utils-2.4 \
  .

--load loads the build result into your local Docker environment. To push the image directly to an image repository, log on to the repository first, replace --load with --push, and change the name after -t to the full image address.

After the build is complete, verify the client and the mount directory in each image:

Ubuntu 22.04

docker run --rm --platform linux/amd64 \
  microsandbox-agenticfs:ubuntu22.04-alinas-utils-2.4 \
  sh -euxc '
    command -v mount.alinas
    command -v mount.nfs
    dpkg-query -W aliyun-alinas-utils nfs-common
    test -d /mnt/agenticfs
  '

Debian 12

docker run --rm --platform linux/amd64 \
  microsandbox-agenticfs:debian12-alinas-utils-2.4 \
  sh -euxc '
    command -v mount.alinas
    command -v mount.nfs
    dpkg-query -W aliyun-alinas-utils nfs-common
    test -d /mnt/agenticfs
  '

If all of the preceding commands succeed, the AgenticFS client is correctly installed in the image. This does not indicate that the VPC, the permissions, or the actual mount path works.

After you create a custom template of the second-generation runtime (MicroVM) from the preceding image, set E2B_TEMPLATE to the ID or alias of that template in the mount example in Step 3. For more information, see Manage custom templates in the console.

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, resolve the reason 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, this creation 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 that is 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 that is 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 are specified as required.

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 that is 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 the AgenticFS client as described in Step 1: Prepare the second-generation runtime image 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 GID, and whether the RAM role that is 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.