Skip to main content
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

​
Prerequisites

These steps are only required during the private preview stage.
For the Agent Drive preview, a custom sandbox template is required. Run: 
bl login
bl new sandbox my-sandbox
This will create a new folder containing a Dockerfile and additional configuration files. To ensure compatibility with the Agent Drive preview, update the following line in the Dockerfile. Replace: 
COPY --from=ghcr.io/blaxel-ai/sandbox:latest /sandbox-api /usr/local/bin/sandbox-api
With: 
COPY --from=ghcr.io/blaxel-ai/sandbox:develop-e6a4ef8 /sandbox-api /usr/local/bin/sandbox-api
From inside the newly created folder, run: 
bl deploy
Obtain the sandbox template’s image ID: 
bl get sandboxes my-sandbox -ojson | jq -r '.[0].spec.runtime.image'
Your sandbox will now be ready to use with the Agent Drive preview.

​
Create a drive

Create a standalone drive by specifying a unique name and region. You can also optionally specify the display name and labels for the drive. 
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
});
You can also use createIfNotExists() to retrieve an existing drive or create a new one if it doesn’t exist: 
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
});

​
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). 
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
});
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: 
await sandbox.drives.mount({
  driveName: "my-drive",
  mountPath: "/app/project",
  drivePath: "/projects/alpha",
});

​
List mounted drives

List all drives currently mounted to a sandbox: 
const mounts = await sandbox.drives.list();
console.log(mounts);

​
List all drives

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

const drives = await DriveInstance.list();
Or via CLI: 
bl get drives

​
Unmount a drive

Unmount a drive from a running sandbox by specifying the mount path: 
await sandbox.drives.unmount("/mnt/data");

​
Delete a drive

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();
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 the custom sandbox template using its image ID, mounts the drive, writes a file to the mounted path, and reads it back: 
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 template
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);