Agent Sandbox:Mount JuiceFS dynamically

How it works

The JuiceFS file system or its subdirectory is mounted through metadata when the Sandbox is created, so no volume is required 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 a JuiceFS mount.

Prerequisites

• You have created a file system in the JuiceFS Enterprise Edition console, and obtained the file system name, the access token, and the service endpoint. For instructions, see Getting started with JuiceFS Enterprise Edition.

• You have prepared a Virtual Private Cloud (VPC), a vSwitch, and a security group that can reach the JuiceFS service over the network.

• You have prepared an Agent Sandbox API key and a custom template of the second-generation runtime (MicroVM).

JuiceFS accesses a file system by using a token, so you do not need to configure a Resource Access Management (RAM) role to mount JuiceFS.

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 mount storage 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.juicefs. Before you submit the request, serialize the structure to a string. You cannot pass a Python dictionary or a JavaScript object:

{
  "mountPoints": [
    {
      "volumeName": "<JUICEFS-FILE-SYSTEM-NAME>",
      "remoteDir": "/",
      "mountDir": "/mnt/juicefs",
      "token": "<JUICEFS-TOKEN>",
      "args": []
    }
  ],
  "envs": {
    "BASE_URL": "https://<JUICEFS-SERVICE-ADDRESS>"
  }
}

A dynamic mount specifies the JuiceFS service endpoint in envs.BASE_URL. You do not need to specify the baseURL field of a volume in the creation request. If you mount the storage together with an existing JuiceFS volume, the two values must still be the same.

args specifies the additional mount parameters passed to the JuiceFS client. The examples in this topic pass the array through the JUICEFS_ARGS_JSON environment variable. If no additional parameter is required, set the value to []. The value cannot be an empty string or the JSON value null, and cannot override the --token and --subdir parameters that the platform manages.

Do not print the complete metadata, the JuiceFS token, or other credentials in logs.

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

export SANDBOX_VPC_ID="vpc-xxxxxxxx"
export SANDBOX_SECURITY_GROUP_ID="sg-xxxxxxxx"
export SANDBOX_VSWITCH_ID="vsw-xxxxxxxx"

export JUICEFS_BASE_URL="https://<JUICEFS-SERVICE-ADDRESS>"
export JUICEFS_VOLUME_NAME="<JUICEFS-FILE-SYSTEM-NAME>"
export JUICEFS_TOKEN="<JUICEFS-TOKEN>"
export JUICEFS_REMOTE_DIR="/"
export JUICEFS_MOUNT_DIR="/mnt/juicefs"

export JUICEFS_ARGS_JSON="[]"

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

Save the following code as 14_sandbox_juicefs.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


def juicefs_args() -> list[str]:
    value = json.loads(require_env("JUICEFS_ARGS_JSON"))
    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
        raise RuntimeError("JUICEFS_ARGS_JSON must be a string array")

    managed_options = ("--token", "--subdir")
    for item in value:
        if any(item == option or item.startswith(f"{option}=") for option in managed_options):
            raise RuntimeError(f"JUICEFS_ARGS_JSON cannot override the parameters that the platform manages: {item}")
    return value


mount_dir = require_env("JUICEFS_MOUNT_DIR")
marker_path = f"{mount_dir}/hello-juicefs-{uuid4().hex}.txt"

vpc_config = {
    "vpcId": require_env("SANDBOX_VPC_ID"),
    "securityGroupId": require_env("SANDBOX_SECURITY_GROUP_ID"),
    "vSwitchIds": [require_env("SANDBOX_VSWITCH_ID")],
}

juicefs_config = {
    "mountPoints": [
        {
            "volumeName": require_env("JUICEFS_VOLUME_NAME"),
            "remoteDir": require_env("JUICEFS_REMOTE_DIR"),
            "mountDir": mount_dir,
            "token": require_env("JUICEFS_TOKEN"),
            "args": juicefs_args(),
        }
    ],
    "envs": {
        "BASE_URL": require_env("JUICEFS_BASE_URL"),
    },
}

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.network.vpc": json.dumps(vpc_config),
            "fc.sandbox.storage.juicefs": json.dumps(juicefs_config),
        },
    )

    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"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("JuiceFS dynamic mount read/write verification succeeded")

Run the example in the activated Python virtual environment:

python 14_sandbox_juicefs.py

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

Behavior notes

• After the Sandbox is paused and then resumed, the JuiceFS mount is restored.

• 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, first mount the storage to a directory that meets the requirements. Then create a symbolic link at the hidden directory path 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 a maximum of 5 JuiceFS mount points, counted cumulatively for the mount points specified when the Sandbox is created and the mount points appended later. Both directly configured mounts and mounts that reference volumes are counted.

• Multiple JuiceFS mount points must use the same service endpoint. If you mount the storage together with an existing JuiceFS volume, the value of envs.BASE_URL must be the same as the value of baseURL of the volume.

FAQ