Agent Drive overview

Agent Drive is a distributed filesystem mountable to multiple sandboxes or agents simultaneously, with concurrent read-write access and built-in replication.

This feature is currently in private preview. During the preview, the Agent Drive feature is only available in the us-was-1 region. Both your drive and your sandbox must be created in this region. Drive size is not configurable at the moment. A quotas system for drive storage is coming soon. Request access.

Agent Drive is a distributed filesystem that can be mounted to multiple sandboxes or agents at any time, including while they are already running. Drives support concurrent read-write access (RWX) from multiple sandboxes simultaneously, with built-in replication for durability.

Unlike volumes, which are block storage devices attached at sandbox creation to a single sandbox, drives behave like a shared cloud filesystem, but mounted directly into a sandbox’s file tree. An optimized FUSE client built specifically for this filesystem is added directly to the sandbox or agent to give a POSIX-compliant interface.

• A drive can be attached to an already-running sandbox at any mount path, without needing to recreate the sandbox
• Multiple sandboxes can mount the same drive simultaneously with full read-write access.
• A specific subdirectory of a drive can be mounted using drivePath (instead of mounting the entire drive).
• Drives scale automatically with no fixed capacity limits. Pre-provisioning or run-time resizing is not required.

Use cases

Some examples of use cases are:

• Passing data or files from one sandbox to another directly, without needing intermediary storage or services
• Storing tool call outputs and context histories for use in other agents
• Sharing common datasets across agents
• Creating a shared filesystem cache of package dependencies to speed up future agent/sandbox deployments

Create a drive

Learn more about authentication on Blaxel

The Blaxel SDK requires two environment variables to authenticate:

Variable	Description
BL_WORKSPACE	Your Blaxel workspace name
BL_API_KEY	Your Blaxel API key

You can create an API key from the Blaxel console. Your workspace name is visible in the URL when you log in to the console (e.g. app.blaxel.ai/{workspace}).

Set them as environment variables or add them to a .env file at the root of your project:

export BL_WORKSPACE=my-workspace
export BL_API_KEY=my-api-key

When developing locally, you can also log in to your workspace with Blaxel CLI (as shown above). This allows you to run Blaxel SDK functions that will automatically connect to your workspace without additional setup. When you deploy on Blaxel, authentication is handled automatically — no environment variables needed.

Create a standalone drive by specifying a unique name and region. You can also optionally specify the display name and labels for the drive.

TypeScript

import { DriveInstance } from "@blaxel/core";

const drive = await DriveInstance.create({
  name: "my-drive",
  region: "us-was-1",
  displayName: "My Project Drive", // optional; defaults to `name`
  labels: { env: "dev", project: "my-project" }, // optional; labels
});

from blaxel.core.drive import DriveInstance
drive = await DriveInstance.create(
    {
        "name": "my-drive",
        "region": "us-was-1",
        "display_name": "My Project Drive", # optional; defaults to `name`
        "labels": {"env": "dev", "project": "my-project"},  # optional; labels
    }
)

bl drive create --name my-drive --region us-was-1

You can also use createIfNotExists() to retrieve an existing drive or create a new one if it doesn’t exist:

TypeScript

const drive = await DriveInstance.createIfNotExists({
  name: "my-drive",
  region: "us-was-1",
  displayName: "My Project Drive", // optional; defaults to `name`
  labels: { env: "dev", project: "my-project" }, // optional; labels
});

from blaxel.core.drive import DriveInstance
drive = await DriveInstance.create_if_not_exists(
    {
        "name": "my-drive",
        "region": "us-was-1",
        "display_name": "My Project Drive", # optional; defaults to `name`
        "labels": {"env": "dev", "project": "my-project"},  # optional; labels
    }
)

Mount a drive to a sandbox

Mount a drive to a running sandbox by specifying the driveName, the mountPath (where the drive will appear in the sandbox’s filesystem), and optionally the drivePath (a subdirectory within the drive to mount).

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");

await sandbox.drives.mount({
  driveName: "my-drive",
  mountPath: "/mnt/data",
  drivePath: "/",   // optional; defaults to root of the drive
});

from blaxel.core import SandboxInstance

sandbox = await SandboxInstance.get("my-sandbox")

await sandbox.drives.mount(
    drive_name="my-drive",
    mount_path="/mnt/data",
    drive_path="/", # optional; defaults to root of the drive
)

bl drive mount --sandbox my-sandbox --drive my-drive --mount-path /mnt/data

Once mounted, any file written to /mnt/data inside the sandbox will be stored on the drive and persist even after the sandbox is deleted.

Mount a subdirectory

You can mount a specific subdirectory of a drive rather than its root. This is useful when a single drive contains multiple project directories:

TypeScript

await sandbox.drives.mount({
  driveName: "my-drive",
  mountPath: "/app/project",
  drivePath: "/projects/alpha",
});

await sandbox.drives.mount(
    drive_name="my-drive",
    mount_path="/app/project",
    drive_path="/projects/alpha",
)

bl drive mount --sandbox my-sandbox --drive my-drive --mount-path /app/project --drive-path /projects/alpha

drivePath / drive_path controls the subtree visible to the sandbox. When combined with drive permissions, you can restrict a workload to a specific subfolder of a drive using the path field in a permission rule.

Mount a drive as read-only

You can mount a drive in read-only mode:

TypeScript

await sandbox.drives.mount({
  driveName: "my-drive",
  mountPath: "/mnt/shared",
  readOnly: true,
});

await sandbox.drives.mount(
    drive_name="my-drive",
    mount_path="/mnt/shared",
    read_only=True,
)

bl drive mount --sandbox my-sandbox --drive my-drive --mount-path /mnt/shared --read-only

The same drive can be mounted read-write in one sandbox and read-only in others. However, any write attempt to a drive mounted as read-only will fail with a permission error.

When drive permissions are configured with mode: "read", read-only access is enforced both at the FUSE mount level and at the storage server level. The workload’s identity token is validated against the permission rules, preventing unauthorized remounting in read-write mode.

List mounted drives

List all drives currently mounted to a sandbox:

TypeScript

const mounts = await sandbox.drives.list();
console.log(mounts);

mounts = await sandbox.drives.list()
print(mounts)

bl drive mounts --sandbox my-sandbox

List all drives

To retrieve all drives in your workspace, use the built-in SDK pagination helper functions.

Pagination is recommended for list operations because retrieving all available resources in a single request is slow and resource-intensive, and therefore does not scale well.

TypeScript

import { DriveInstance } from "@blaxel/core";

const drives = await DriveInstance.list({ limit: 50 });
for await (const drive of drives) {
  console.log(drive.name);
}

import asyncio
from blaxel.core.drive import DriveInstance

async def main():
    drives = await DriveInstance.list(limit=50)
    async for drive in drives.auto_paging_iter():
        print(drive.name)

asyncio.run(main())

bl drive list

For more information on the SDK pagination helpers, refer to the SDK reference documentation.

Pagination is also available via the Management API list endpoint.

Request the first page:

curl 'https://api.blaxel.ai/v0/drives?limit=50' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY' \
  -H 'Blaxel-Version: 2026-04-28'

The response includes a data array and a meta object:

{
  "data": [ ... ],
  "meta": {
    "hasMore": true,
    "nextCursor": "...",
    "total": 24
  }
}

Pass meta.nextCursor as cursor on the next request and repeat until meta.hasMore is false:

curl 'https://api.blaxel.ai/v0/drives?limit=50&cursor=NEXT_CURSOR' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY' \
  -H 'Blaxel-Version: 2026-04-28'

For accounts with multiple workspaces, specify the workspace as an additional request parameter, such as ?workspace=WORKSPACE_NAME&..., or via an additional X-Blaxel-Workspace: WORKSPACE_NAME header in the request.

For more information, refer to the API reference documentation.

Get drive details

Retrieve details about a specific drive:

CLI

bl drive get my-drive

Unmount a drive

Unmount a drive from a running sandbox by specifying the mount path:

TypeScript

await sandbox.drives.unmount("/mnt/data");

await sandbox.drives.unmount("/mnt/data")

bl drive unmount --sandbox my-sandbox --mount-path /mnt/data

Delete a drive

TypeScript

import { DriveInstance } from "@blaxel/core";

// Class-level
await DriveInstance.delete("my-drive");

// Or instance-level
const drive = await DriveInstance.get("my-drive");
await drive.delete();

from blaxel.core.drive import DriveInstance

# Class-level
await DriveInstance.delete("my-drive")

# Or instance-level
drive = await DriveInstance.get("my-drive")
await drive.delete()

bl drive delete my-drive

Complete code examples demonstrating all operations are available in Blaxel’s GitHub repositories, for TypeScript, for Python, and for Go.

Full example

The following example creates a drive, creates a sandbox from a custom sandbox image using its image ID, mounts the drive, writes a file to the mounted path, and reads it back:

TypeScript

import { SandboxInstance, DriveInstance } from "@blaxel/core";

// 1. Create a drive
const drive = await DriveInstance.createIfNotExists({
  name: "agent-storage",
  region: "us-was-1",
});

// 2. Create a sandbox
//    Use the image ID of the custom sandbox image
const sandbox = await SandboxInstance.createIfNotExists({
  name: "my-agent-sandbox",
  image: "my-sandbox-image-id",
  memory: 2048,
  region: "us-was-1",
});

// 3. Mount the drive to the sandbox
await sandbox.drives.mount({
  driveName: "agent-storage",
  mountPath: "/mnt/storage",
  drivePath: "/",
});

// 4. Write a file to the mounted drive
await sandbox.fs.write("/mnt/storage/hello.txt", "Hello from the drive!");

// 5. Read it back
const content = await sandbox.fs.read("/mnt/storage/hello.txt");
console.log(content); // "Hello from the drive!"

// 6. List mounted drives
const mounts = await sandbox.drives.list();
console.log(mounts);

import asyncio
from blaxel.core.drive import DriveInstance
from blaxel.core import SandboxInstance

async def main():
    # 1. Create a drive
    drive = await DriveInstance.create_if_not_exists(
        {
            "name": "agent-storage",
            "region": "us-was-1",
        }
    )

    # 2. Create a sandbox
    sandbox = await SandboxInstance.create_if_not_exists(
        {
            "name": "my-agent-sandbox",
            "image": "my-sandbox-image-id",
            "memory": 2048,
            "region": "us-was-1",
        }
    )

    # 3. Mount the drive to the sandbox
    await sandbox.drives.mount(
        drive_name="agent-storage",
        mount_path="/mnt/storage",
        drive_path="/",
    )

    # 4. Write a file to the mounted drive
    await sandbox.fs.write("/mnt/storage/hello.txt", "Hello from the drive!")

    # 5. Read it back
    content = await sandbox.fs.read("/mnt/storage/hello.txt")
    print(content)  # "Hello from the drive!"

    # 6. List mounted drives
    mounts = await sandbox.drives.list()
    print(mounts)

asyncio.run(main())