The Complete Guide to Vercel Drives

Vercel Drives give your sandboxes persistent storage that outlives any single run. You create a drive once, mount it in a sandbox at a path you choose, and the data stays put after the sandbox stops, ready to be attached to the next run. Drives are useful when an agent needs to reuse a workspace, cache dependencies, or share large inputs across sessions, rather than rebuilding everything from scratch. Drives are in private beta on Pro and Enterprise plans, and they're free to use during the beta.

In this guide, you'll learn how drives differ from snapshots and when to reach for each. You'll create, mount, list, and delete a drive with the Sandbox CLI and the JavaScript SDK, walk through the patterns agents use most, and see the limits to plan around while Drives are in beta.

A drive is persistent storage with a lifecycle that's independent from any sandbox. You create a drive in your Vercel project, give it a name that's unique within that project, then mount it into a sandbox by passing the drive name and an absolute mount path when you start the sandbox. While the sandbox runs, your code reads and writes to the mounted path as if it were any other directory. When the sandbox stops, the drive detaches and keeps its contents, so a later sandbox can mount the same drive and pick up where the last run left off.

Each sandbox can mount up to 4 drives, and each drive holds up to 1 TiB of data. You can mount a drive in read-write (the default) or read-only mode, and mount paths must be absolute and cannot overlap. During the private beta, one sandbox can mount a drive in read-write mode at a time, since drives are single-reader, single-writer.

Writes and cache-hit reads run at NVMe speed, while reads that miss the cache are slower because the data is fetched from durable storage. That trade-off makes it a good fit for caching and large datasets, where the first read warms the cache and subsequent reads remain fast.

Use a drive for caching and storing large amounts of data shared across several sandbox runs. Use a snapshot to capture and restore a full sandbox filesystem, including installed packages and environment configuration.

Many workflows combine both: a snapshot of the base environment and a drive for working data that grows over time. The table below compares the two:

Drives retain their contents independently of the sandbox they were mounted on. When the sandbox stops, the drive detaches, and the data stays put, ready for the next sandbox to mount. When you delete the sandbox, its drives are untouched, because a drive's lifecycle isn't tied to any sandbox. A drive's data is removed only when you delete the drive yourself with sandbox drives rm or drive.delete(), which is also why you can't delete a drive while it's still attached to a running sandbox.

Snapshots work the opposite way. It belongs to the sandbox that produced it, so deleting that sandbox also deletes its snapshots, and each snapshot expires 30 days after its last use unless you extend it. Reach for a drive when the data needs to outlive the sandbox and its snapshots, and use a snapshot when you want the environment and its state to travel together as one unit.

Drives are in private beta on Pro and Enterprise plans. Access is gated by the beta waitlist, so register your interest to enable drives for your team. While Drives are in private beta, they're free to use. Snapshot storage, a separate way to persist sandbox state, is billed at $0.08 per GB-month.

Treat beta drives as non-critical storage. Vercel recommends using drives for caching and similar workloads during the beta, and advises against storing production data on a drive until the feature is generally available.

Before you create your first drive, make sure you have:

• A Vercel project on a Pro or Enterprise plan with drives enabled
• The beta Sandbox SDK or CLI installed. Drives ship in the beta channel:

pnpm i @vercel/sandbox@beta

• A linked project so the SDK and CLI can read a Vercel OIDC token. Run vercel link and vercel env pull in your project to download a development token.

Drives belong to a Vercel project, and drive names are unique within that project. Pick names you can recognize later, such as workspace-cache or model-weights.

Create a drive before mounting it in a sandbox. The get-or-create command returns the existing drive if one with that name already exists, or creates it if it doesn't.

With the CLI:

sandbox drives get-or-create workspace-cache

A drive defaults to a maximum size of 100 GiB. To set a different limit, pass --max-size in bytes, up to 1 TiB:

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

With the JavaScript SDK, use Drive.getOrCreate():

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

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

console.log(drive.name, drive.maxSize);

The maxSize value is the drive's size limit in bytes. The example above uses 200 GiB.

Mount a drive by passing its name and an absolute mount path when you create a sandbox. Mount paths can't overlap with each other, and you can mount up to 4 drives in a single run.

Drives mount in read-write mode by default. Use the --mount flag with the format drive:/path[:read-write|read-only]:

# Mount read-write (the default)
sandbox create --name my-sandbox --mount workspace-cache:/data

# Mount read-only
sandbox create --name my-sandbox --mount workspace-cache:/data:read-only

Once the sandbox is running, your code reads and writes /data like any other directory, and the contents persist on the drive after the sandbox stops.

To mount drives programmatically, pass a mounts array to Sandbox.create() in the JavaScript SDK. See the JS SDK reference for the full set of mount options.

List drives to see their sizes, creation dates, and which sandbox each is attached to.

With the CLI:

sandbox drives ls

Filter by name prefix and limit the results:

sandbox drives ls --name-prefix workspace --limit 10

With the JavaScript SDK, use Drive.list(). It returns the matching drives and a pagination cursor, and supports async iteration:

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

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

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

The currentSandboxName accessor returns the sandbox a drive is mounted on, or undefined when the drive is detached.

Deleting a drive permanently removes every file stored on it. You can't delete a drive while it's attached to a running sandbox, so stop the sandbox first.

With the CLI:

sandbox drives rm workspace-cache

With the JavaScript SDK, call delete() on a drive instance:

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

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

Drives fit a few recurring workflows where persisting data across sandbox runs saves time and compute.

Store an agent's working directory on a drive so it builds context over time rather than starting from scratch on every run. Create the drive once, then mount it into each sandbox the agent uses:

sandbox drives get-or-create agent-workspace
sandbox create --name agent-run --mount agent-workspace:/workspace

Later runs mount the same drive and resume from the files the previous run left behind.

Cache dependencies, build artifacts, or other large data on a drive so repeated runs skip slow downloads and rebuilds. The first run warms the cache with NVMe-speed writes, and later cache-hit reads stay fast.

Pre-seed a drive with a dataset, model weights, or fixtures, then spin up compute on demand and mount the drive read-only. Read-only mounts let you reuse the same source data across runs without risking accidental writes.

Keep these constraints in mind while Drives are in private beta:

• A sandbox can mount up to 4 drives per run.
• A drive holds up to 100 GiB by default, configurable up to 1 TiB with --max-size.
• Drives are single reader, single writer. One sandbox can mount a drive in read-write mode at a time, and support for multiple readers is coming soon.
• Vercel recommends drives for caching and other non-critical use cases during the beta, not production data.

A drive can't be deleted while it's attached to a running sandbox. Stop or delete the sandbox that has the drive mounted, confirm the drive is detached (its currentSandboxName reads as detached when you list drives), then delete it.

Mount paths must be absolute, and the paths for two drives mounted into the same sandbox can't overlap. Give each drive its own top-level path, such as /data and /cache, rather than nesting one inside the other.

Drives can be mounted read-write by only one sandbox at a time, since drives are single-reader, single-writer. Stop the sandbox that currently has the drive mounted before mounting it elsewhere, or mount the drive read-only where a run only needs to read the data.

Writes and cache-hit reads run at NVMe speeds, but reads that miss the cache are fetched from durable storage and run more slowly. Warm the cache by reading the data once at the start of a run, or use a snapshot instead if you need consistent NVMe-speed reads across the whole filesystem.

• Learn how persistent sandboxes automatically save and restore filesystem state between runs.
• Compare drives with snapshots to decide what to persist where.
• Review the Sandbox CLI reference for every sandbox drives command.
• Explore the JS SDK reference for the full Drive API.