Drives

Drives provide persistent storage that you mount into a sandbox as a working directory. Your agent can generate code, download dependencies, and build up context in that directory, keeping its progress across sessions.

Files written to a drive persist after the sandbox stops. Mount the same drive in a later run to pick up where you left off, even when starting from a different sandbox environment. You can mount up to four drives in a sandbox, each at its own path alongside the sandbox's own filesystem.

You currently need to mount a drive into a sandbox to read and write files using the sandbox's drive mount path.

A sandbox snapshot captures a sandbox's filesystem at a point in time, including installed tools and project files. Use it to create or resume a sandbox from that saved environment. Sandboxes created from the same snapshot each get an independent copy of the filesystem.

Use a drive when you want a directory of files to persist independently of that environment. You mount the drive as an additional directory and keep updating its contents across sandbox runs. Drives are also useful for caching dependencies and build artifacts so later runs can reuse them.

You can use both together. For example, start a sandbox from a snapshot with your tools installed, then mount a drive for your project files and cached dependencies. This lets you reuse the working files with a different starting environment later.

Drives also support read-only snapshots for sharing a point-in-time view of a drive with multiple sandboxes. These are separate from the sandbox snapshots compared below.

• Agent workspace: store an agent workspace that persists across sandbox runs, building context over time.
• Shared cache: cache dependencies, build artifacts, or other large data.
• Pre-seeding data: pre-seed a drive with data, then spin up compute on demand when needed.

You run an agent that installs the same 10 GB of dependencies on every sandbox. With a snapshot, each sandbox gets its own copy, reinstalling and storing them separately every time. With a drive, they all read from one shared copy that persists across runs.

import { Sandbox, Drive } from '@vercel/sandbox';
 
const cache = await Drive.getOrCreate({ name: 'shared-deps' });
 
// One sandbox populates the cache (single read-write mount)
const writer = await Sandbox.create({
  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({
  mounts: { '/cache': cache.snapshot() },
});

A snapshot copies the entire filesystem per sandbox. A drive is one directory that many sandboxes share, so there is one copy to update and every sandbox reads from it.

Create a drive before mounting it into a sandbox. Drive names are unique within a Vercel project.

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

If you omit the maximum size, the drive defaults to 1 TiB (1 GiB for Hobby). Set maxSize in TypeScript, max_size_bytes in Python, or --max-size in the CLI to specify the maximum drive size in bytes. The size must be a multiple of 4096 bytes. The default maximum quota is 16 TiB.

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

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.

Mount a drive by passing the drive name and mount path when creating a sandbox. The sandbox's main region must match the drive's region. Mount paths must be absolute and cannot overlap with each other.

Drives are mounted as read-write by default. Only one sandbox at a time can mount a given drive as read-write: use snapshots for shared access.

import { Sandbox, Drive } from '@vercel/sandbox';
 
const drive = await Drive.getOrCreate({ name: 'workspace-cache' });
 
// Mount as read-write once
const sandbox = await Sandbox.create({
  name: 'my-sandbox',
  mounts: {
    '/data': drive
  },
});

In the CLI, --mount uses the format drive:/path[:read-write|snapshot].

You can also mount a drive by taking a point-in-time, read-only snapshot of it. Snapshots allow multiple sandboxes to mount the same drive concurrently. Each snapshot mount reflects the drive as it was at the moment you mounted it, and does not include any writes made to the drive thereafter. Mount a new snapshot to pick up more recent writes.

import { Sandbox, Drive } from '@vercel/sandbox';
 
const drive = await Drive.getOrCreate({ name: 'shared' });
 
// Mount many snapshots of the same drive
const firstReader = await Sandbox.create({
  name: 'reader-1',
  mounts: {
    '/data': drive.snapshot()
  },
});
const secondReader = await Sandbox.create({
  name: 'reader-2',
  mounts: {
    '/data': drive.snapshot()
  },
});

In the CLI, --mount uses the format drive:/path[:read-write|snapshot].

You can fork an existing drive into a new drive, copying the drive's data and inheriting its region and maximum size. The fork belongs to the same project. Writes to a forked drive do not change the original drive, allowing you to safely edit a copy while preserving the source data. This can be useful to start a fleet of agents, each working independently on their own read-write copy forked from a base drive.

import { Drive, Sandbox } from '@vercel/sandbox';
 
const drive = await Drive.get({ name: 'workspace-cache' });
const forkedDrive = await drive.fork({ name: 'workspace-cache-fork' });
 
const sandbox = await Sandbox.create({
  region: forkedDrive.region,
  mounts: { '/data': forkedDrive },
});

You can mount a forked drive like any other drive. A fork inherit its parent drive data but stores its own changes independently. Use parentDriveId to identify the source drive and rootDriveId to identify the original drive in a chain of forks.

List drives to view the currently attached sandboxes (if any) and metadata such as creation date and size.

import { Drive } from '@vercel/sandbox';
 
const result = await Drive.list({
  namePrefix: 'workspace',
  sortBy: 'name',
  sortOrder: 'asc',
  limit: 10,
});
 
for (const drive of result.drives) {
  console.log(drive.name, drive.currentSandboxName ?? 'detached');
}

Deleting a drive permanently removes all data stored in the drive. A drive cannot be deleted if it is currently attached to a running sandbox.

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

• A sandbox can mount up to 4 drives per run
• A drive defaults to 1 TiB when you do not set a size (1 GiB for Hobby). The default maximum quota is 16 TiB
• A drive is stored in a single region. A sandbox's main region must match a drive's region.

Drives are billed on three metrics: storage, reads, and writes. Storage is measured hourly on the logical used size in GB of each drive. Reads and writes measure the logical read and write usage in GB of each drive.

See Sandbox pricing for the rates in each region and the Hobby allotments.

Deploy an eve template to start building AI agents that store and search files on a drive:

eve Vercel Drives Starter

An eve agent that reads and saves your team's files on a Vercel Drive.

Open in v0

eve Contentful Agent

Slack-based Contentful assistant built on eve, with Vercel Drives providing a searchable copy of your content.

Open in v0

• Persistent sandboxes: Learn how persistent sandboxes automatically save and restore state.
• Snapshots: Save and restore a full sandbox filesystem.
• CLI Reference: Command reference for the Sandbox CLI.
• JS SDK Reference: Full API documentation for the JavaScript SDK.
• Python SDK Reference: Full API documentation for the Python SDK.