How Vercel Drives work and how to use them

Vercel Drives give your agents persistent storage that lives independently of the sandbox running them. Agents often handle work that spans multiple runs, and each run may require a different environment with different tools, runtimes, or compute resources. Without storage that outlives a specific sandbox, moving to a new environment requires cloning repositories, reinstalling dependencies, and rebuilding context before the agent can resume its work.

You mount a drive into a Vercel Sandbox as a directory, and any files written there remain after the sandbox stops. Later runs and new sandboxes can mount the same drive to continue the work, even when they use a different image, runtime, or set of tools. Drives also let you share files between sandboxes. Many agents can read the same prepared dataset or dependency cache through read-only drive snapshots, or you can fork a drive so each agent works on its own writable copy.

Copy link to headingOverview

In this guide, you'll learn how to:

• Decide when to use a drive instead of a sandbox snapshot or a persistent sandbox
• Create a drive and choose its region and maximum size
• Mount a read-write drive to keep an agent's workspace across runs
• Share one drive with many sandboxes using read-only drive snapshots
• Fork a drive so parallel agents can each work on an independent copy
• List drives, change a sandbox's mounts, and delete drives
• Resolve common errors and plan for limits and pricing

Copy link to headingHow Vercel Drives work

In Vercel Drives, a drive is a single directory of persistent storage that you attach to a sandbox at a mount path, such as /workspace. Everything a sandbox writes under the mount path is stored on the drive, and everything outside the mount path belongs to the sandbox's own filesystem.

Vercel Drives separate an agent's files from its execution environment. When an agent's next task needs different tools, a different runtime, or more compute, you create a new sandbox configured for that task and mount the same drive. The new sandbox finds the files exactly where the previous run left them, so the agent never has to transfer or rebuild its workspace.

Each drive belongs to one Vercel project and is stored in one region. Drive names are unique within a project. Sandboxes can mount up to four drives at the same time, with each drive at its own absolute path.

Copy link to headingWhat are the ways to access a drive?

You can access a drive in three ways, depending on whether sandboxes need to write and whether they need to run at the same time.

Read-write is the default mount mode. Drive snapshot mounts don't show writes made after you mount them, so mount a new drive snapshot to see newer files. Forks store their own changes and never merge back into the source drive.

Drive snapshots are separate from sandbox snapshots, even though the names are similar. Drive snapshots give a read-only, point-in-time view of one drive, while sandbox snapshots capture a sandbox's full filesystem.

Copy link to headingWhen to use a drive instead of a sandbox snapshot

Use a drive when files need to outlive a specific sandbox environment or be shared between sandboxes. Use a sandbox snapshot, or a persistent sandbox, when you want to save and restore the full environment of a single sandbox.

Vercel Sandboxes are persistent by default.

When a persistent sandbox stops, the filesystem is snapshotted and restored the next time that sandbox resumes. That state stays tied to the one sandbox. Sandboxes created from the same sandbox snapshot each get an independent copy of the filesystem, so their changes aren't shared.

Drives work differently. Many sandboxes can read the same drive, and its files persist regardless of which sandbox mounts it next. This makes drives a good fit for agent output, caches, and shared datasets.

You can use both together. Start a sandbox from a sandbox snapshot that already has your tools installed, then mount a drive for project files and cached dependencies. Later, you can mount the same drive into a sandbox built from a different snapshot or image. For example:

• Switch environments between tasks: Run a coding task in a sandbox built from a snapshot with your Node.js toolchain, then mount the same drive in a sandbox built from a Python snapshot for data analysis. The agent's repository and notes are already on the drive, so only the environment changes.
• Reuse caches across builds: Start each build from a snapshot with your build tools installed, and mount a drive containing the package store and build artifacts. Each run reuses what earlier runs cached instead of reinstalling dependencies, and you can update the toolchain by changing the snapshot without rebuilding the cache.

Copy link to headingPrerequisites

Before you begin, make sure you have:

• A Vercel account
• Vercel CLI installed (npm i -g vercel)
• Node.js 22+ and a package manager

Install the Vercel Sandbox SDK:

pnpm i @vercel/sandbox

npm i @vercel/sandbox

yarn add @vercel/sandbox

bun add @vercel/sandbox

The Vercel Sandbox SDK authenticates with a Vercel OpenID Connect (OIDC) token.

How you get the OIDC token depends on where your code runs:

• Local development: Run vercel link to link your project, then run vercel env pull to download its development environment variables, which include the OIDC token.
• Refreshing the local token: The local token expires after 12 hours. Run vercel env pull again if commands start failing with an OIDC credentials error.
• Production on Vercel: Authentication is automatic,.

To manage drives from the terminal, install the Sandbox CLI globally with your package manager, then log in with sandbox login. The CLI is optional, because every step in this guide also shows the SDK equivalent.

The examples in this guide use the TypeScript SDK and the Sandbox CLI. The Python SDK also supports drives, view the SDK reference.

Copy link to headingSteps

Copy link to heading1. Create or retrieve a drive

Drive.getOrCreate() returns the drive with the given name, or creates it if it doesn't exist yet. Create a drive before you mount it into a sandbox.

import { Drive } from '@vercel/sandbox';

const drive = await Drive.getOrCreate({
  name: 'workspace-cache',
  region: 'sfo1',
  maxSize: 200 * 1024 * 1024 * 1024, // 200 GiB
});

console.log(drive.region); // "sfo1"

With the Sandbox CLI, run:

sandbox drives get-or-create workspace-cache --region sfo1 --max-size 214748364800

The CLI equivalents of region and maxSize are --region and --max-size. In the Python SDK, the size parameter is max_size_bytes.

Once a drive exists, its region and maximum size are fixed.

Calling Drive.getOrCreate() for an existing drive with a different region or maxSize fails with a conflict error. To retrieve a drive that already exists without passing its settings, use Drive.get({ name: 'workspace-cache' });

Copy link to heading2. Mount a drive read-write to persist a workspace

Pass the drive in the mounts option of Sandbox.create(), keyed by an absolute mount path. Drives mounted this way are read-write, and everything the sandbox writes under that path persists on the drive.

import { Sandbox, Drive } from '@vercel/sandbox';

const drive = await Drive.getOrCreate({ name: 'agent-workspace' });

const sandbox = await Sandbox.create({
  region: drive.region,
  mounts: { '/workspace': drive },
});

await sandbox.runCommand('git', [
  'clone',
  'https://github.com/your_org_here/your_repo_here.git',
  '/workspace/repo',
]);

await sandbox.stop();

The next sandbox that mounts agent-workspace finds the cloned repository, and anything else the agent wrote under /workspace, where the previous run left it. That sandbox can use a different image or resources:

const nextSandbox = await Sandbox.create({
  image: 'vercel/sandbox/node:26',
  region: drive.region,
  mounts: { '/workspace': drive },
});

const result = await nextSandbox.runCommand('ls', ['/workspace']);
console.log(await result.stdout()); // repo

For the CLI, use --mount with the format drive:/path[:read-write|snapshot].

The mode defaults to read-write:

sandbox create --mount agent-workspace:/workspace

Or run a single command with the drive mounted:

sandbox run --mount agent-workspace:/workspace -- ls /workspace

Keep these rules in mind when mounting a drive:

• Match the region: The sandbox's main region must match the drive's region. The project default sandbox region isn't applied to sandboxes that mount drives, so pass region explicitly whenever the drive isn't in iad1.
• One writer at a time: Only one sandbox at a time can mount a given drive read-write. Stop the writing sandbox before another sandbox mounts the drive read-write, or use drive snapshots for concurrent readers.
• Use absolute, separate paths: Mount paths must be absolute and can't overlap with each other.
• Write once before sharing: Mount the drive read-write and write to it at least once before you mount a drive snapshot of it or fork it.

Copy link to heading3. Share a drive with read-only drive snapshots

Call drive.snapshot() to mount a point-in-time, read-only view of a drive. Many sandboxes can mount drive snapshots of the same drive at the same time, which makes drive snapshots the way to share prepared files with a fleet of readers.

import { Sandbox, Drive } from '@vercel/sandbox';

const drive = await Drive.getOrCreate({ name: 'shared-dataset' });

const firstReader = await Sandbox.create({
  name: 'reader-1',
  region: drive.region,
  mounts: { '/data': drive.snapshot() },
});

const secondReader = await Sandbox.create({
  name: 'reader-2',
  region: drive.region,
  mounts: { '/data': drive.snapshot() },
});

With the Sandbox CLI, add the snapshot mode to the mount:

sandbox create --mount shared-dataset:/data:snapshot

Each drive snapshot mount reflects the drive as it was at the moment you mounted it. Writes made to the drive afterward don't appear in that mount. To pick up newer files, mount a new drive snapshot in a new sandbox or session.

Copy link to heading4. Fork a drive for parallel, independent work

drive.fork() creates a new drive from an existing drive’s data, in the same project and with the same region and maximum size. Writes to a fork stay in that fork and never change the source drive, other forks, or the original.

Forks let a fleet of agents start from the same files, each with its own writable workspace. In this example, three workers each fork a base drive, run against their copy, and then delete it:

import { Sandbox, Drive } from '@vercel/sandbox';

const base = await Drive.get({ name: 'base-drive' });

await Promise.all(
  [0, 1, 2].map(async (i) => {
    const fork = await base.fork({ name: `worker-${i}` });

    const sandbox = await Sandbox.create({
      region: fork.region,
      mounts: { '/data': fork },
    });

    // Run this worker's session against its own copy in /data
    await sandbox.runCommand('ls', ['/data']);

    // Stop the sandbox so the fork is detached, then delete the fork
    await sandbox.stop();
    await fork.delete();
  }),
);

Deleting a fork discards its changes. To keep a worker's results, skip the fork.delete() call and mount the fork later like any other drive.

With the Sandbox CLI, pass the source drive name and a new unique name:

sandbox drives fork base-drive worker-0

parentDriveId returns the ID of the drive a fork was created from, and rootDriveId returns the ID of the original drive at the start of a chain of forks. Both return undefined for a drive that wasn’t created by forking.

const fork = await base.fork({ name: 'worker-3' });
console.log(fork.parentDriveId === base.driveId); // true

Copy link to heading5. List your drives

Drive.list() returns the drives in your project, along with metadata such as the sandbox each drive is attached to. The result supports async iteration across pages.

import { Drive } from '@vercel/sandbox';

const result = await Drive.list({
  namePrefix: 'workspace',
  sortBy: 'name',
  sortOrder: 'asc',
  limit: 10,
});

for await (const drive of result) {
  console.log(drive.name, drive.region, drive.currentSandboxName ?? 'detached');
}

All Drive.list() parameters are optional.

With the Sandbox CLI, the output includes a REGION column for each drive:

sandbox drives list --name-prefix workspace --sort-order asc

Each Drive object exposes these properties:

{
  driveId: 'your_drive_id_here',
  name: 'worker-0',
  projectId: 'your_project_id_here',
  region: 'iad1',
  maxSize: 1099511627776, // bytes
  currentSessionId: 'your_session_id_here', // undefined when not mounted
  currentSandboxName: 'my-sandbox', // undefined when not mounted
  createdAt: Date,
  updatedAt: Date,
  parentDriveId: 'your_base_drive_id_here', // undefined if not a fork
  rootDriveId: 'your_base_drive_id_here', // undefined if not a fork
}

Copy link to heading6. Change the drives mounted on an existing sandbox

sandbox.update() replaces a sandbox’s mounts for its next session. The running session keeps its current mounts.

Pass the new mounts in the mounts option, keyed by mount path. Each mount path takes one of three values:

• Drive object: Mounts the drive with read-write access.
• drive.snapshot(): Mounts a read-only drive snapshot.
• Object with the drive name and mode: Mounts the drive by name, with mode set to read-write or snapshot, as shown in the code below.

await sandbox.update({
  mounts: {
    '/data': { drive: 'workspace-cache', mode: 'read-write' },
    '/shared': { drive: 'shared-dataset', mode: 'snapshot' },
  },
});

console.log(sandbox.mounts);

With the Sandbox CLI, replace the mounted drives for new sessions:

sandbox config mounts my-sandbox --mount workspace-cache:/data --mount shared-dataset:/shared:snapshot

Remove all drive mounts from new sessions with sandbox config mounts my-sandbox.

Copy link to heading7. Delete a drive

drive.delete() permanently removes a drive and all data stored on it, and stops its storage charges. You can't delete a drive while it's attached to a sandbox, so stop the sandbox first.

import { Drive } from '@vercel/sandbox';
const drive = await Drive.get({ name: 'workspace-cache' });
await drive.delete();

With the Sandbox CLI, you can delete one or more drives at once:

sandbox drives delete workspace-cache build-artifacts

Copy link to headingCommon patterns for Vercel Drives

Copy link to headingKeep an agent workspace across runs

Mount the same drive read-write in each run so an agent builds up context over time. Store the agent's repository, generated code, notes, and file-based memory under the mount path, and let each run use whichever sandbox environment fits.

Copy link to headingShare a dependency cache across sandboxes

Sharing one drive avoids having to reinstall the same dependencies in every sandbox. If an agent installs 10 GB of dependencies on each run, sandbox snapshots store a separate copy per sandbox, while a drive keeps one shared copy that persists multiple runs.

One sandbox populates the cache read-write, and later sandboxes read it:

import { Sandbox, Drive } from '@vercel/sandbox';

const cache = await Drive.getOrCreate({ name: 'shared-deps' });

// One sandbox populates the cache with the single read-write mount
const writer = await Sandbox.create({
  region: cache.region,
  mounts: { '/cache': cache },
});
await writer.runCommand('pnpm', ['install', '--store-dir', '/cache']);
await writer.stop();

// Later sandboxes read the same cache without reinstalling
const sandbox = await Sandbox.create({
  region: cache.region,
  mounts: { '/cache': cache.snapshot() },
});

Copy link to headingPrepare a dataset once and analyze it in many sandboxes

One agent can build a dataset on a drive, and other agents can mount drive snapshots of it to analyze the data or generate reports without rebuilding the dataset. Because drive snapshot mounts are read-only, readers save their results somewhere else, such as their own drive. This pattern also works for pre-seeding a drive with data, models, or build artifacts and then starting compute on demand.

Copy link to headingRun a fleet of agents from a base drive

Fork a base drive once per agent so each agent explores a different approach on its own writable copy. Agents can try different transformations of the same dataset in parallel without changing the original or affecting one another.

Copy link to headingPair a sandbox snapshot with a drive

Use a sandbox snapshot for the environment and a drive for the files. The sandbox snapshot provides installed tools, and the drive provides the working files, so you can later swap the environment without moving any files:

const sandbox = await Sandbox.create({
  source: { type: 'snapshot', snapshotId: 'your_snapshot_id_here' },
  region: drive.region,
  mounts: { '/workspace': drive },
});

Copy link to headingHow eve agents use Vercel Drives

Two eve templates show complete agents built on Vercel Drives, which you can deploy and adapt.

Copy link to headingeve Vercel Drives Starter

The eve Vercel Drives Starter is an agent that reads and saves your team's files on a drive, through Slack or your terminal. It combines two drive patterns:

• Reading through drive snapshots: Each session mounts a read-only drive snapshot at /drive, and the agent explores the files with shell commands such as ls, find, and grep.
• Writing through a short-lived sandbox: The save_to_drive tool runs in the app rather than the agent's sandbox. It starts a short-lived sandbox that mounts the drive read-write, writes the file, and stops. If another save or upload holds the read-write mount, the tool reports drive_busy and the agent offers to retry.

Sessions can't mount the drive until it has been written to, so upload files with the template’s script or ask the agent to save one before your first chat. Set the DRIVE_NAME and DRIVE_REGION environment variables to choose which drive the agent uses.

Copy link to headingeve Contentful Agent

The eve Contentful Agent is a Slack-based Contentful assistant that keeps a searchable copy of your content on Vercel Drives. Local development sessions can't access that copy and query Contentful directly instead, so test drive-backed searches through the deployed agent in Slack.

You can also set up per-user workspaces and shared reference data in an eve agent with Vercel Drives.

Copy link to headingWhat are the limits for Vercel Drives?

Copy link to headingHow Vercel Drives pricing works

Vercel Drives bills separately for storage, reads, and writes. Storage is measured hourly on the logical used size of each drive, not the size you provisioned, so a 1 TiB drive holding 20 GB of files is billed for 20 GB. Reads and writes measure the logical data your sandboxes read from and write to mounted drives.

These rates apply to the default iad1 region, and drive rates vary by region. See regional pricing page in the docs for the rates in each region.

For example, a Pro team in iad1 that stores 100 GB on a drive for a full month, reads 500 GB, and writes 100 GB pays about $5.00 for storage, $0.75 for reads, and $0.40 for writes, for an estimated $6.15. On Pro, Sandbox usage is first charged against the $20 monthly credit. Deleting a drive stops its storage charges.

Copy link to headingTroubleshooting

Copy link to headingconflict error when calling Drive.getOrCreate()

The drive already exists with a different region or maximum size than the values you passed. The region and maximum size of a drive can't change after creation.

Pass the drive's original values, omit them, or use Drive.get({ name }) to retrieve the existing drive.

Copy link to headingdrive_not_initialized error when mounting a drive snapshot or forking

This error means the drive has never been written to. Drive snapshots and forks need existing data, so mount the drive read-write in a sandbox, write at least one file under the mount path, and then try again. For example, this code initializes a drive by writing a README to it:

import { Sandbox, Drive } from '@vercel/sandbox';

const drive = await Drive.get({ name: 'shared-dataset' });

const sandbox = await Sandbox.create({
  region: drive.region,
  mounts: { '/data': drive },
});

await sandbox.writeFiles([
  { path: '/data/README.md', content: Buffer.from('# Shared data\n') },
]);

// Release the read-write mount
await sandbox.stop();

After the write completes, you can mount drive.snapshot() or call drive.fork().

Copy link to headingdrive_region_mismatch error when creating a sandbox

The sandbox's main region doesn't match the drive's region. The project default sandbox region isn't applied to sandboxes that mount drives, so pass region: drive.region to Sandbox.create(). In the CLI, check the drive's region in the REGION column of sandbox drives list.

Copy link to headingA second sandbox can't mount a read-write drive

Only one sandbox at a time can mount a drive read-write. Stop the sandbox that holds the read-write mount and retry, or mount drive.snapshot() if the second sandbox only needs to read. To find the sandbox using the drive, check currentSandboxName in the output of Drive.list().

Copy link to headingNew files don't appear in a drive snapshot mount

Drive snapshots reflect the drive at the moment they were mounted, so later writes don’t appear in an existing snapshot mount.

To see newer files, mount a new drive snapshot in a new sandbox, or pass drive.snapshot() to sandbox.update() so the sandbox picks it up in its next session. In the eve Vercel Drives Starter, snapshot timing explains why a saved file appears in new sessions but might not appear in the session that saved it.

Copy link to headingMount changes don't apply to a running sandbox

sandbox.update({ mounts }) and sandbox config mounts apply to the sandbox's next session. Stop the sandbox and resume it to use the new mounts.

Copy link to headingThe drive can't be deleted

You can't delete a drive while it's attached to a sandbox. Stop the sandbox that has the drive mounted, then call drive.delete() or run sandbox drives delete.

Copy link to headingRelated resources and next steps

• Read the Drives documentation for the full concept reference.
• Read the source for the eve Vercel Drives Starter and the eve Contentful Agent to see how each agent mounts and writes to drives. In the Starter, the drive helpers are in agent/lib/drive.ts and the session mount is in agent/sandbox.ts.