Agent Sandbox:Mount a JuiceFS Volume

Step 1: Prepare the second-generation runtime image

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

A JuiceFS Volume mount requires the second-generation runtime (MicroVM). Before you build the custom template, the source image must have the JuiceFS Enterprise Edition client, the RADOS runtime library, and FUSE 2 pre-installed. The second-generation runtime uses the source image directly and does not inject the JuiceFS client when the template is built.

JuiceFS Volume mounts support only JuiceFS Enterprise Edition. JuiceFS provides the Enterprise Edition mount image in the juicedata/mount repository on Docker Hub, and the image tags start with ee-. In the image, /usr/bin/juicefs is the client launcher, and the version-pinned client executable is located at /usr/local/juicefs/mount/jfsmount.

The following example uses juicedata/mount:ee-5.3.7-58af72b. In this tag, 5.3.7 is the client version and 58af72b is the corresponding build commit. Verify the version information in the JuiceFS Command Reference. For information about how to use the image and containers, see Use JuiceFS in Docker.

Make sure that the image can be pulled, and then check the Enterprise Edition client in the image:

docker pull --platform linux/amd64 \
  juicedata/mount:ee-5.3.7-58af72b

docker run --rm --platform linux/amd64 \
  --entrypoint /usr/bin/juicefs \
  juicedata/mount:ee-5.3.7-58af72b \
  version

The client version in the output must be 5.3.7, and the build commit must be 58af72b. Do not use floating tags such as latest or ee-nightly, because the client version may change after you rebuild the template. If the build environment cannot access Docker Hub, sync the image to an accessible private image repository first, and then replace the image address of juicedata/mount in the following Dockerfile.

The following Dockerfile uses Ubuntu 22.04 by default. To build on an existing Sandbox base image, pass the image address by using the BASE_IMAGE build argument:

ARG BASE_IMAGE=ubuntu:22.04

FROM juicedata/mount:ee-5.3.7-58af72b AS juicefs-ee

FROM ${BASE_IMAGE}

ARG DEBIAN_FRONTEND=noninteractive

RUN set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends \
        ca-certificates \
        fuse \
        librados2; \
    rm -rf /var/lib/apt/lists/*

COPY --from=juicefs-ee /usr/local/juicefs/mount/jfsmount /usr/bin/juicefs

RUN set -eux; \
    chmod 0755 /usr/bin/juicefs; \
    command -v juicefs; \
    command -v fusermount; \
    mkdir -p /mnt/juicefs

WORKDIR /root

# Do not set a custom USER, ENTRYPOINT, or CMD. The Sandbox control plane takes over.

Do not write the JuiceFS token or the mount configuration into the Dockerfile or any image layer.

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

docker buildx build \
  --platform linux/amd64 \
  --build-arg BASE_IMAGE="<YOUR-SANDBOX-BASE-IMAGE>" \
  --push \
  -t "<REGISTRY>/<NAMESPACE>/microsandbox-juicefs-ee:<VERSION>" \
  .

After the build is complete, check the client, the RADOS runtime library, and FUSE 2 in the image:

docker run --rm --platform linux/amd64 \
  --entrypoint /bin/sh \
  <REGISTRY>/<NAMESPACE>/microsandbox-juicefs-ee:<VERSION> \
  -euxc '
    command -v juicefs
    command -v fusermount
    ldconfig -p | grep "librados\.so\.2"
    juicefs version
  '

This check verifies only the image content. It does not mean that the VPC, the token, or the actual mount path works. Use this image to rebuild the MicroVM template, and then run the following examples.

Step 2: Install the SDK

This topic uses the E2B Python SDK for demonstration. 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="<MICROVM-TEMPLATE-ID>"

export JUICEFS_SANDBOX_VOLUME_NAME="juicefs-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/juicefs"
marker_path = f"{mount_dir}/hello-juicefs-{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("JUICEFS_SANDBOX_VOLUME_NAME"),
        },
    )

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

    sandbox.files.write(marker_path, "hello juicefs\n")
    marker_written = True
    content = sandbox.files.read(marker_path)
    if content != "hello juicefs\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("JuiceFS Volume read/write verification passed")

python 04_mount_juicefs_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 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 it first. Submitting the mount request again does not make the volume available.

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

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

If you do not specify the VPC in the metadata, check the mountConfig.vpcConfig of the volume. If you specify it, check fc.sandbox.network.vpc. The configuration actually used must contain vpcId, securityGroupId, and a non-empty vSwitchIds. The metadata configuration takes precedence, and the fields of the volume are not used to fill in an incomplete metadata configuration.

The volume is created, but Sandbox creation times out or the mount fails

Creating a volume only stores the configuration and does not perform the actual mount. Check the corresponding configuration based on the error message. If the message does not clearly indicate the cause, troubleshoot in the following order:

1. Verify the JuiceFS Enterprise Edition client, the RADOS runtime library, and FUSE 2 as described in Step 1: Prepare the second-generation runtime image in this topic.

2. Check the VPC routes, security groups, and service addresses actually used, and confirm that the Sandbox can access the JuiceFS service.

3. Check the token, the file system name, and the remote directory, and confirm that the token allows access to the destination directory.

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