Agent Sandbox:Mount AgenticFS dynamically

How it works

When you create a Sandbox, use metadata to mount an AgenticSpace Access Point or its subdirectory to the Sandbox, without creating a volume in advance. After the mount is complete, your application accesses data through the local mount directory.

To add a mount to a running Sandbox, see Append an AgenticFS mount.

Prerequisites

For more information about AgenticFS, see AgenticFS. The related resources are created and managed in the NAS console.

• You have created an AgenticFS file system, an AgenticSpace, and an AgenticSpace Access Point for which Resource Access Management (RAM) authentication is enabled. The Access Point is in the active state.

• You have obtained the address of the Access Point, for example, ap-<ACCESS-POINT-ID>.<FILE-SYSTEM-ID>-<SUFFIX>.<REGION>.nas.aliyuncs.com:/.

• You have prepared a Virtual Private Cloud (VPC), a vSwitch, and a security group, all of which can reach the Access Point over the network.

• You have prepared an Agent Sandbox API key and an available template.

• You have prepared a RAM role whose trust policy allows the Function Compute service to assume the role, and the role has the access permissions required by the target storage. For information about how to configure the role, see Configure a RAM role. For information about storage permission policies, see Create an AgenticFS Volume.

Install the SDK

Create and activate a Python virtual environment, and then install the E2B SDK:

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

Mount configuration

When you create a Sandbox, specify the following items in metadata:

To specify the mount configuration directly when you create a Sandbox, you must also provide the complete VPC configuration as a JSON string in fc.sandbox.network.vpc. The VPC configuration of the template or of a volume in the same request cannot replace this metadata.

The following JSON structure shows the value of fc.sandbox.storage.agenticfs. Before you submit the request, serialize the structure to a string. You cannot pass a Python dictionary or a JavaScript object:

{
  "userID": 1000,
  "groupID": 1000,
  "mountPoints": [
    {
      "serverAddr": "ap-<ACCESS-POINT-ID>.<FILE-SYSTEM-ID>-<SUFFIX>.<REGION>.nas.aliyuncs.com:/project-a",
      "mountDir": "/mnt/agenticfs"
    }
  ]
}

The metadata key must be fc.sandbox.storage.agenticfs in lowercase. Field names in the configuration are also case-sensitive. You must use userID, groupID, serverAddr, and mountDir. The platform automatically enables TLS. Do not specify enableTLS. The configuration is parsed in strict JSON mode. Undeclared fields such as readOnly cause the request to fail.

Environment variables

Mount and verify

Set the environment variables and replace the placeholders in the examples. The API endpoint, the template, and the storage must use matching regions and network configurations:

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="<TEMPLATE-ID>"

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

export SANDBOX_VPC_ID="vpc-xxxxxxxx"
export SANDBOX_SECURITY_GROUP_ID="sg-xxxxxxxx"
export SANDBOX_VSWITCH_ID="vsw-xxxxxxxx"
export SANDBOX_ROLE_ARN="acs:ram::<ACCOUNT-ID>:role/<ROLE-NAME>"

The example creates a separate test file with a random identifier in the mount directory, writes data to the file, and reads the file for verification. It then deletes the file and releases the Sandbox that is created in the process. Use a mount configuration that provides read and write permissions.

Save the following code as 12_sandbox_agenticfs.py:

import json
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"
agenticfs_config = {
    "userID": int(require_env("AGENTICFS_USER_ID")),
    "groupID": int(require_env("AGENTICFS_GROUP_ID")),
    "mountPoints": [
        {
            "serverAddr": require_env("AGENTICFS_SERVER_ADDR"),
            "mountDir": mount_dir,
        }
    ],
}
vpc_config = {
    "vpcId": require_env("SANDBOX_VPC_ID"),
    "securityGroupId": require_env("SANDBOX_SECURITY_GROUP_ID"),
    "vSwitchIds": [require_env("SANDBOX_VSWITCH_ID")],
}

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"),
        metadata={
            "fc.sandbox.storage.agenticfs": json.dumps(agenticfs_config),
            "fc.sandbox.network.vpc": json.dumps(vpc_config),
            "fc.sandbox.auth.role": require_env("SANDBOX_ROLE_ARN"),
        },
    )

    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"Unexpected file content: {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 dynamic mount read/write verification succeeded")

Run the example:

python 12_sandbox_agenticfs.py

If the output is AgenticFS dynamic mount read/write verification succeeded, the read and write verification, the test file cleanup, and the Sandbox release are complete.

Behavior notes

Releasing a Sandbox does not delete the underlying storage data. The example deletes the test file on its own. To retain or clean up other data, handle it in the storage service or through the mount directory.

Limits

• The local mount directory must be a normalized absolute Unix path. It cannot be /, and it cannot contain leading or trailing spaces, ., .., or repeated path separators.

• The local mount directory cannot be a system directory or a subdirectory of one, such as /bin, /opt, /var, or /dev, and cannot contain a hidden directory such as .cache. To access data through a hidden directory, mount the storage to a directory that meets the requirements and then create a symbolic link that points to the mount directory.

• Local mount directories cannot be duplicated in the same Sandbox, including mount directories of other storage types.

• A Sandbox supports up to five AgenticFS mount points, counted cumulatively for the mounts specified at creation and the mounts appended later. Both directly configured mounts and mounts that reference volumes are counted.

• Multiple AgenticFS mount points in the same Sandbox share one pair of userID and groupID values. All mount points within a single mount configuration share the values. The UID or GID that you specify for an append mount cannot conflict with the existing configurations of the Sandbox.

FAQ