# The Complete Guide to Vercel Drives **Author:** Ben Sabic --- 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 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. ## 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, 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. ## 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 | | Read/write performance | NVMe-speed writes and cache-hit reads, slower cache-miss reads | NVMe-speed reads and writes | | Storage size | Up to 1 TiB per drive | 32 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 | Free during the private beta | $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 in private beta on [Pro](https://vercel.com/docs/plans/pro) and [Enterprise](https://vercel.com/docs/plans/enterprise) plans. Access is gated by the beta waitlist, so [register your interest](https://vercel.com/changelog/drives-for-vercel-sandbox-in-private-beta) 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 begin 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: - 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: `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. ## 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. 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](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: `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. ## 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: `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();` ## 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: `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 the drive read-only. Read-only mounts let you reuse the same source data across runs 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 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. ## 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 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. ### 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. ## 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. --- [View full KB sitemap](/kb/sitemap.md)