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 available on all plans and are billed on storage, reads, and writes. Hobby plans include a free monthly allotment.

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 and pricing to plan around.

Copy link to headingHow do Vercel Drives work?

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. A drive defaults to 1 TiB (1 GiB on Hobby), and you can configure it up to a 16 TiB quota. Drives mount in read-write mode by default, and mount paths must be absolute and cannot overlap. One sandbox at a time can mount a drive as read-write. To share a drive across sandboxes, mount a point-in-time, read-only snapshot of it: any number of sandboxes can mount snapshots of the same drive concurrently.

A drive lives in a single region (iad1 by default), and a sandbox that mounts it must run in the same region.

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.

Copy link to headingComparing drives to snapshots

Copy link to headingWhen should you use a drive instead of a snapshot?

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:

Copy link to headingWhat happens to your data when a sandbox stops or is deleted?

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.

Copy link to headingPlans and pricing for Vercel Drives

Drives are available on all plans. Vercel bills drives on three metrics: storage, reads, and writes.

• Drive Storage: the data stored on your drives, in GB per month. Storage is measured hourly on the logical used size of each drive, not the size you provisioned. Deleting a drive stops its storage charges.
• Drive Reads: the logical amount of data your sandboxes read from mounted drives, in GB.
• Drive Writes: the logical amount of data your sandboxes write to mounted drives, in GB.

In the default iad1 region, Pro and Enterprise plans pay $0.05 per GB-month for storage, $0.0015 per GB for reads, and $0.004 per GB for writes. Rates vary by region. Hobby plans include 15 GB of lifetime storage and 30 GB per month each of reads and writes at no cost. See Sandbox pricing for the rates in each region.

Snapshot storage, a separate way to persist sandbox state, is billed at $0.08 per GB-month in all regions.

Copy link to headingBefore you begin

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

• A Vercel project on a Pro or Enterprise plan with drives enabled
• The Sandbox SDK or CLI installed:

pnpm i @vercel/sandbox

npm i @vercel/sandbox

yarn add @vercel/sandbox

bun add @vercel/sandbox

• 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.

Copy link to headingHow to create a drive

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 1 TiB (1 GiB on Hobby). To set a different limit, pass --max-size in bytes, up to the 16 TiB quota. Contact Vercel Support to request a quota above 16 TiB.

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

Drives are created in iad1 by default. Set --region to store the drive in another region:

sandbox drives get-or-create workspace-cache --region sfo1

A drive's region can't change after creation. Requesting an existing drive with a different region or maximum size than it was created with fails with a conflict error.

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
  region: 'sfo1'
});

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

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

Copy link to headingHow to mount a drive in a sandbox

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. The sandbox must run in the same region as the drive.

Drives mount in read-write mode by default, and one sandbox at a time can mount a drive as read-write. Use the --mount flag with the format drive:/path[:read-write|snapshot]:

sandbox create --name my-sandbox --mount workspace-cache:/data

To share a drive across sandboxes, mount a point-in-time, read-only snapshot of it. Any number of sandboxes can mount snapshots of the same drive concurrently:

sandbox create --name reader-1 --mount workspace-cache:/data:snapshot
sandbox create --name reader-2 --mount workspace-cache:/data:snapshot

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 object to Sandbox.create(), keyed by mount path. Call drive.snapshot() to mount a read-only snapshot:

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

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

// Mount read-write (one sandbox at a time)
const writer = await Sandbox.create({
  name: 'my-sandbox',
  mounts: { '/data': drive },
});

// Mount read-only snapshots (any number of sandboxes)
const reader = await Sandbox.create({
  name: 'reader-1',
  mounts: { '/data': drive.snapshot() },
});

See the JS SDK reference for the full set of mount options.

Copy link to headingHow to list drives

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.

Copy link to headingHow to delete a drive

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();

Copy link to headingCommon patterns for Vercel Drives

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

Copy link to headingAgent workspace

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.

Copy link to headingShared cache

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.

Copy link to headingPre-seeding data

Pre-seed a drive with a dataset, model weights, or fixtures, then spin up compute on demand and mount a snapshot of the drive. Snapshot mounts are read-only, so any number of sandboxes can reuse the same source data concurrently without risking accidental writes.

Copy link to headingLimits

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

• A sandbox can mount up to 4 drives per run.
• A drive defaults to 1 TiB when you don't set a size (1 GiB for Hobby). The maximum quota is 16 TiB per drive. Contact Vercel Support to request a quota above 16 TiB.
• One sandbox at a time can mount a drive as read-write. Mount drive snapshots for concurrent read-only access.
• A drive is stored in a single region. A sandbox that mounts a drive must run in the same region, and can't have failover regions.

Copy link to headingTroubleshooting

Copy link to headingA drive won't delete

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.

Copy link to headingA mount path is rejected

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.

Copy link to headingA second sandbox can't mount the same drive

One sandbox at a time can mount a drive as read-write. Stop the sandbox that currently has the drive mounted before mounting it read-write elsewhere. For runs that only read the data, mount a snapshot of the drive instead: any number of sandboxes can mount snapshots concurrently.

Copy link to headingReads are slower than expected

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.

Copy link to headingCreating a drive fails with a conflict error

get-or-create returns the existing drive when one with that name already exists. If you request it with a different region or maximum size than it was created with, the call fails with a conflict error. Request the drive with its original settings, or delete it and create a new one.

Copy link to headingA sandbox can't mount a drive in another region

A drive is stored in the region you created it in, and its region can't change. Create the sandbox in the same region as the drive, or create a new drive in the sandbox's region. Sandboxes that mount drives also can't use failover regions.

Copy link to headingResources and next steps

• 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.