Agent Sandbox:Mount an AgenticBucket Volume

Step 1: Prepare the second-generation runtime image

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.

If you use a custom template of the second-generation runtime (MicroVM), you must pre-install ossfs2 2.0.9 or later in the source image before you build the template. The second-generation runtime uses the source image directly and does not inject ossfs2 when the template is built. ossfs2 2.0.x installation packages support only linux/amd64. The following Dockerfile uses Ubuntu 22.04 and ossfs2 2.0.9 as an example:

FROM ubuntu:22.04

ARG DEBIAN_FRONTEND=noninteractive
ARG OSSFS2_DEB_URL=https://gosspublic.alicdn.com/ossfs/ossfs2_2.0.9_linux_x86_64.deb
ARG OSSFS2_DEB_SHA256=33b5d16e870f53680a595b6369fd34eda18928807bae5fd934940f079cc04f6e

RUN set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends ca-certificates curl fuse3; \
    curl --fail --location --retry 3 \
        "${OSSFS2_DEB_URL}" \
        --output /tmp/ossfs2.deb; \
    echo "${OSSFS2_DEB_SHA256}  /tmp/ossfs2.deb" | sha256sum -c -; \
    apt-get install -y --no-install-recommends /tmp/ossfs2.deb; \
    rm -f /tmp/ossfs2.deb; \
    rm -rf /var/lib/apt/lists/*

WORKDIR /root

When you upgrade the installation package, update both OSSFS2_DEB_URL and OSSFS2_DEB_SHA256. Do not skip the SHA-256 verification, and do not write storage credentials or mount configurations into the image.

Before you build and push the linux/amd64 image, replace the placeholders with actual values:

docker buildx build \
  --platform linux/amd64 \
  --push \
  -t <REGISTRY>/<NAMESPACE>/microsandbox-ossfs2:2.0.9 \
  .

After the build is complete, verify that the ossfs2 version in the image is 2.0.9 or later:

docker run --rm --platform linux/amd64 \
  <REGISTRY>/<NAMESPACE>/microsandbox-ossfs2:2.0.9 \
  sh -euxc '
    test -x /usr/local/bin/ossfs2
    installed_version="$(dpkg-query -W ossfs2 | cut -f2)"
    dpkg --compare-versions "${installed_version}" ge "2.0.9"
  '

This check verifies only the image content. It does not mean that the permissions, the endpoint, or the actual mount operation works.

Step 2: Install the SDK

This topic uses the E2B Python SDK as an example. 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

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

export AGENTIC_BUCKET_VOLUME_NAME="<VOLUME-NAME>"

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/agentic-bucket"
marker_path = f"{mount_dir}/hello-agentic-bucket-{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("AGENTIC_BUCKET_VOLUME_NAME"),
        }
    )

    sandbox.files.write(marker_path, "hello agentic bucket\n")
    marker_written = True
    content = sandbox.files.read(marker_path)
    if content != "hello agentic bucket\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("AgenticBucket Volume mount read/write verification succeeded")

python 03_mount_agentic_bucket_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 a volume by name, use an existing volume in the same team. Do not specify a volume ID.

The volume exists, but the system reports 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 it first. Submitting the mount request again does not make the volume available.

Sandbox creation reports a missing RAM role

If the error message contains AgenticBucket mount requires Function role, the Sandbox creation request did not obtain the RAM role required for the mount.

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

The mount fails when the Sandbox is created

Based on the error message, check the endpoint and the full names of the AgenticBucket and BucketSpace stored in the volume. If the message indicates that access to the storage is denied, check the RAM role that the Sandbox actually uses and the access control of the AgenticBucket. For information about how the role is selected, see Configure a RAM role.

If you use a custom template of the second-generation runtime, also verify that ossfs2 is installed as described in Step 1: Prepare the second-generation runtime image in this topic.

The volume is mounted, but write operations fail

First, check whether the volume is configured with readOnly: true. If the volume allows read and write operations, check whether the RAM role that the Sandbox actually uses has write permissions. Also check whether the access control of the AgenticBucket allows the operations.

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