Agent Sandbox:Append a JuiceFS mount

JuiceFS mount parameters

The following fields are in inlineVolumeMounts.juiceFS. If you specify the configuration directly, set the fields as described in the following table:

Do not print tokens or the complete request body in logs.

Local mount directory

mountDir and namedVolumeMounts[].path both specify the local mount directory in the Sandbox. The recommended location is a subdirectory of /home, /mnt, /tmp, or /data. For information about the directory limits, see Limits.

Specify the mount configuration directly

The following example appends the remote directory in the JuiceFS file system to /mnt/juicefs and verifies read and write operations. Make sure that the token and the directory permissions allow read and write operations. If the Sandbox already has a JuiceFS mount, the BASE_URL must be the same as the existing endpoint.

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="/datasets/project-a"

Save the following code as append_juicefs.py. Before you run the code, make sure that mount_dir is not used by an existing mount:

import os
from uuid import uuid4

import httpx
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 verify_read_write(sandbox: Sandbox, mount_dir: str) -> None:
    marker_path = f"{mount_dir}/mount-check-{uuid4().hex}.txt"
    expected = f"append mount check {uuid4().hex}\n"
    sandbox.files.write(marker_path, expected)
    try:
        content = sandbox.files.read(marker_path)
        if content != expected:
            raise RuntimeError(f"File content verification failed: {marker_path}")
    finally:
        sandbox.files.remove(marker_path)
    print(f"Read/write verification passed. Test file deleted: {mount_dir}")


api_key = require_env("E2B_API_KEY")
api_url = require_env("E2B_API_URL").rstrip("/")
domain = require_env("E2B_DOMAIN")
sandbox_id = require_env("SANDBOX_ID")
mount_dir = "/mnt/juicefs"

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

response = httpx.post(
    f"{api_url}/sandboxes/{sandbox_id}/fc-volume-mounts",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120.0,
)
if response.status_code != 204:
    raise RuntimeError(f"Append mount failed: HTTP {response.status_code}, {response.text}")

sandbox = Sandbox.connect(
    sandbox_id,
    timeout=300,
    api_key=api_key,
    api_url=api_url,
    domain=domain,
)

verify_read_write(sandbox, mount_dir)

python append_juicefs.py

remoteDir specifies the remote directory in JuiceFS, and mountDir specifies the local directory in the Sandbox. The platform converts remoteDir to the --subdir parameter of the client. For information about how to use remote directories, see Mount JuiceFS dynamically.

Reference an existing volume

If an Agent Sandbox volume already exists, replace the payload definition in the preceding script with the following content before the first run. Keep the rest of the code unchanged. Replace name with the name of a volume in the same team. The volume must allow read and write operations for the verification to pass.

payload = {
    "namedVolumeMounts": [{
        "name": "juicefs-workspace",
        "path": mount_dir,
    }],
}

name specifies the name of an Agent Sandbox volume, not the name of a JuiceFS file system. If you combine mount methods, envs.BASE_URL must match the baseURL of the referenced volume and the endpoint of the existing JuiceFS mounts.

The two preceding examples demonstrate one mount method each. Select one of them for each run. You cannot append to the same mount directory twice. If the mount succeeds but the verification fails, run only the connection and verification code again. Do not submit the append request again.

If you combine a direct configuration and a volume reference, put both configurations in the same request body and specify a different local mount directory for each mount point. For the complete procedure and the multi-volume examples for volume references, see Append a volume mount.

Why is the request rejected by the API key policy?

If the error message is request is not allowed by API key policy, check whether the API key policy allows the mount method and the storage type of this request. For more information, see Manage API keys. This type of rejection occurs at the API authorization stage. Adjusting the RAM role of the storage does not resolve it.

Why does the system report that the volume cannot be found when I mount by name?

Check the volume name in the request, the team that owns the API key, and the region of the API endpoint. Make sure that you use the name of a volume in the same team instead of a volume ID. For more information, see Append a volume mount.

Why does the system report that the volume is unavailable when I mount by name?

Query the status and the status reason of the volume by using GetVolume. Mount the volume only after you confirm that it is available. If a failure reason exists, resolve it first. For more information, see Append a volume mount.

Why does the append mount report that the Sandbox is not running?

If the error message is sandbox must be running, confirm that the target Sandbox is in the running state. If the Sandbox is paused, resume it first. If the Sandbox is released, recreate it.

Why does the append mount report an incomplete VPC configuration for the Sandbox?

If the error message contains FC Function complete VPC configuration is required, the missing configuration belongs to the current Sandbox. The mountConfig.vpcConfig of the append request or of a new volume does not supply the missing configuration.

When you recreate the Sandbox, you must provide a complete VPC configuration that includes vpcId, securityGroupId, and a non-empty vSwitchIds. When you create a Sandbox, provide these values by using metadata, or use the VPC configuration that the referenced volume stores.

Why does the append mount report a JuiceFS service endpoint conflict?

Check the inlineVolumeMounts.juiceFS.envs.BASE_URL in this request, the baseURL of the referenced volume, and the endpoint used by the existing JuiceFS mounts of the Sandbox. All JuiceFS mounts must use the same endpoint.

For example, if the error message contains JuiceFS Volume baseUrl conflicts with inline JuiceFS envs.BASE_URL, the endpoint that you specify directly conflicts with the endpoint of the referenced volume. Specify the same endpoint or select the corresponding volume. To connect to a different JuiceFS service, use a different Sandbox.

Why does the append mount report a duplicate mount directory?

If the error message contains duplicate mount path or duplicate mount dir, check whether the local mount directories in this request are duplicated. Also check whether a directory is already used by another mount in the Sandbox. Different storage types cannot share the same local mount directory.

Do not submit existing mounts again. Use an unused directory for the new mount. The append operation cannot overwrite or replace existing mounts.

Why is the mount limit exceeded when I append only one mount point?

The number of mounts is calculated from the existing mounts of the Sandbox and the new mounts in this request. Both directly configured mounts and mounts that reference volumes are counted. Do not check only the number of mounts in this request.

Check the number of mounts for the corresponding storage type as described in Limits of this topic. If the limit is reached, mount the new storage in another Sandbox. Changing the local mount directory does not reduce the number of existing mounts.

If the issue persists, or if the API reports that the service is temporarily unavailable, retain the complete error message and the request ID, and contact technical support.