---
title: The Complete Guide to Vercel Drives
description: Learn how Vercel Drives provide persistent storage for Vercel Sandboxes, and how to create, mount, list, and delete a drive with the Sandbox CLI and SDK.
url: /kb/guide/vercel-drives
canonical_url: "https://vercel.com/kb/guide/vercel-drives"
published: 2026-06-29
last_updated: 2026-09-11
authors: Ben Sabic
related:
  - /docs/sandbox/concepts/snapshots
  - /docs/sandbox/pricing
  - /docs/oidc
  - /docs/sandbox/concepts/regions
  - /docs/sandbox/sdk-reference
  - /docs/sandbox/concepts/persistent-sandboxes
  - /docs/sandbox/cli-reference
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

Vercel Drives give your [sandboxes](https://vercel.com/sandbox) 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.

## How 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.

## Comparing drives to snapshots

### When 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](https://vercel.com/docs/sandbox/concepts/snapshots) 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:

| Aspect                 | Drive                                                            | Snapshot                                                      |
| ---------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------- |
| Storage type           | A single directory mounted into a sandbox                        | The full sandbox filesystem                                   |
| Sharing                | Shared storage across sandboxes                                  | Independent copy per sandbox, changes are not shared          |
| Read/write access      | One read-write mount, many read-only mounts via drive snapshots  | Read-write filesystem for each sandbox                        |
| Read/write performance | NVMe-speed writes and cache-hit reads, slower cache-miss reads   | NVMe-speed reads and writes                                   |
| Storage size           | 1 TiB by default (1 GiB for Hobby), up to a 16 TiB quota         | 64 GB (filesystem size)                                       |
| Expiration             | Persists until you delete it                                     | Expires after 30 days by default, extendable to no expiration |
| Use cases              | Agent output, caching, shared data                               | Agent state, temporary data, base filesystem                  |
| Price                  | $0.05 per GB-month storage, plus reads and writes (`iad1` rates) | $0.08 per GB-month                                            |

### What 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.

## Plans 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](https://vercel.com/docs/sandbox/pricing#drive-storage) 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.

## Before 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:
  

```bash
pnpm i @vercel/sandbox
```

- A linked project so the SDK and CLI can read a [Vercel OIDC token](https://vercel.com/docs/oidc). 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`.

## How 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:

```bash
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](https://vercel.com/help) to request a quota above 16 TiB.

```bash
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](https://vercel.com/docs/sandbox/concepts/regions#regions-and-drives):

```javascript
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()`:

```typescript
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.

## How 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](https://vercel.com/docs/sandbox/concepts/regions#regions-and-drives) 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]`:

```javascript
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:

```javascript
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:

```typescript
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](https://vercel.com/docs/sandbox/sdk-reference) for the full set of mount options.

## How to list drives

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

With the CLI:

```bash
sandbox drives ls
```

Filter by name prefix and limit the results:

```bash
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:

```typescript
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.

## How 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:

```bash
sandbox drives rm workspace-cache
```

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

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

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

## Common patterns for Vercel Drives

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

### Agent 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:

```bash
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.

### Shared 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.

### Pre-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.

## Limits

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](https://vercel.com/help) 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](https://vercel.com/docs/sandbox/concepts/regions). A sandbox that mounts a drive must run in the same region, and can't have [failover regions](https://vercel.com/docs/sandbox/concepts/regions#failover-regions).
  

## Troubleshooting

### A 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.

### A 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.

### A 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.

### Reads 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.

### Creating 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.

### A 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.

## Resources and next steps

- Learn how [persistent sandboxes](https://vercel.com/docs/sandbox/concepts/persistent-sandboxes) automatically save and restore filesystem state between runs.
  
- Compare drives with [snapshots](https://vercel.com/docs/sandbox/concepts/snapshots) to decide what to persist where.
  
- Review the [Sandbox CLI reference](https://vercel.com/docs/sandbox/cli-reference) for every `sandbox drives` command.
  
- Explore the [JS SDK reference](https://vercel.com/docs/sandbox/sdk-reference) for the full `Drive` API.