How to Use Vercel Sandbox Drives

The short answer

Create a Drive once with Drive.getOrCreate(), pass it to Sandbox.create() under an absolute mount path such as /data, and keep every durable file inside that path. Stop the first sandbox before another sandbox requests read-write access. For parallel test or review sandboxes, mount drive.snapshot() instead. Those readers get a frozen view and will not receive later writes.

A Drive is closer to a detachable project room than a bigger hard disk inside one machine. The sandbox is the temporary crew and workshop. The Drive is the locked storage room that stays when the crew leaves and can be attached to the next workshop.

Vercel lists agent workspaces, on-disk memory, dependency trees, datasets, models, and build artifacts as the intended jobs for Drives. One early user also reported that a per-agent Drive let reconnects skip dependency reinstallation. That is the payoff to test: less setup work, not merely more storage.

Set up one durable workspace

Start with a Vercel project and local authentication. Vercel recommends an OIDC token for local development. vercel env pull writes that development token to .env.local, and the token expires after 12 hours. An external CI system can use a team ID, project ID, and access token instead.

The stable npm release at publication is @vercel/sandbox 3.5.0. Some older Vercel SDK copy still says private beta and suggests the beta channel, but the current Drive concept page and September 23 launch say public beta on all three plans.

npm install @vercel/sandbox@3.5.0
npx vercel link
npx vercel env pull

Now create a Drive, mount it, write a marker and a tiny cache, stop that sandbox, and read both files from a fresh sandbox:

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

const workspace = await Drive.getOrCreate({
  name: 'agent-workspace',
  region: 'iad1',
});

const first = await Sandbox.create({
  persistent: false,
  region: 'iad1',
  mounts: { '/data': workspace },
});

await first.runCommand('bash', [
  '-lc',
  "mkdir -p /data/.cache/demo && printf 'ready\\n' > /data/marker.txt && printf 'cached\\n' > /data/.cache/demo/package.txt",
]);
await first.stop();

const next = await Sandbox.create({
  persistent: false,
  region: 'iad1',
  mounts: { '/data': workspace },
});

const check = await next.runCommand('bash', [
  '-lc',
  'cat /data/marker.txt /data/.cache/demo/package.txt',
]);
console.log(await check.stdout());
await next.stop();

persistent: false keeps this example focused on the Drive. A persistent sandbox has its own snapshot-based resume behavior, while a Drive remains an independent directory that can move between different sandboxes. You can combine both when you want a reusable base environment plus a separately evolving project folder.

Run the four checks that matter

The happy path proves persistence. These four checks prove that the design will behave when several jobs touch the same workspace.

1. Prove the workspace survives a new sandbox

Write both a marker and the cache under /data, stop the writer, then create a different sandbox with the same Drive. Read the files from /data. Files elsewhere in the first sandbox are not evidence of Drive persistence.

Record four timings around your own job: first sandbox creation, initial dependency installation, first stop, and fresh sandbox creation plus cache reuse. The useful number is the setup time removed from the second run. A Drive that persists files but does not shorten the real job may still be convenient, but it has not changed the compute budget.

2. Prove that an old reader stays old

Write an initial marker, stop the writer, and create a reader with mounts: { '/data': workspace.snapshot() }. Keep that reader running. Mount the Drive read-write in another sandbox, replace the marker, and stop the writer. The existing reader should still return the original marker because its view was fixed when it mounted. Create a new snapshot reader to see the replacement.

The important mental model is a photograph, not a live mirror. Calling snapshot() describes the read-only mount; the point-in-time view is established when the reader sandbox mounts it. A Drive must also be written at least once before a snapshot can mount. An unwritten Drive returns drive_not_initialized.

3. Prove that a second writer is rejected

Keep one read-write sandbox running and attempt to create another read-write sandbox with the same Drive. Vercel permits only one read-write mount at a time. Do not turn the expected failure into retry spam. Put a lease or queue in front of writers, stop the owner cleanly, and use Drive.list() or currentSandboxName when you need to find the attachment.

Vercel's fetched documentation does not name a stable error code for this second-writer case. Treat the failed sandbox creation as the contract and avoid branching production logic on a guessed code string.

4. Prove that the main region matches

Create the Drive in iad1, then try to mount it with a sandbox whose main region is sfo1. Vercel documents that mismatch as drive_region_mismatch. A Drive's region cannot be changed after creation, and asking getOrCreate() for the same name with a different region or maximum size produces a conflict error.

Set the region on both objects even if iad1 is your default. Explicit configuration prevents a later project-default change from turning a routine restart into a region failure.

After a disposable test, stop every writer and reader, confirm the Drive is detached with Drive.list() or currentSandboxName, then call await workspace.delete(). Deletion permanently removes the files, and Vercel rejects it while a sandbox is still attached.

The bill has four different moving parts

Drive storage does not replace sandbox compute. It adds three storage meters beside the existing compute meter. In iad1, the current published rates are:

Rates vary by region. Internet downloads such as npm packages and Git repositories are free, but the CPU and provisioned memory used to install them are still metered. That distinction is why a dependency cache can pay: it removes repeated setup work, not download egress.

Here is a useful Pro or Enterprise planning example, not a benchmark. A 10 GB dependency tree stored for a full month costs $0.50. Reading the full tree in 100 runs means 1,000 GB of logical reads, or $1.50. Writing the 10 GB once costs $0.04. The Drive portion is $2.04, before compute, memory, transfer, or later writes.

Vercel's own pricing example puts a five-minute, 2-vCPU, 4 GB AI code-validation run at about $0.03 in iad1 under 100% CPU utilization. Do not assume a Drive saves that entire amount. Measure the install segment it actually removes, then compare the saved compute and human wait against the Drive's storage, read, and write bill.

Hobby lists 15 GB of included Drive storage, plus 30 GB per month each of reads and writes. Separately, an individual Hobby Drive defaults to a 1 GiB maximum. Hobby does not charge overages: new sandbox creation pauses after a quota is exceeded. On paid plans, a Drive defaults to a 1 TiB maximum if you omit maxSize, and the default quota can be configured up to 16 TiB.

Seven use cases, ranked by who gains most

1. A coding-agent product with returning projects

Give each agent workspace its own Drive, store the repository, generated files, task notes, and package cache under the mount, then attach it to a fresh sandbox for the next turn. The product team avoids rebuilding the same workspace after every sandbox lifecycle event, and the user gets continuity without keeping compute alive.

This is the strongest use because restart frequency and repeated setup compound. The one-writer rule also maps cleanly to one active agent per workspace, while previews and tests can use frozen readers.

2. A build team repeating the same dependency installation

Populate one Drive from a controlled writer, then let later jobs mount read-only snapshots of the dependency tree. The team trades repeated install CPU and wait time for one stored copy plus read charges. It pays best when dependencies are large, change less often than jobs run, and the cache path can be isolated from the source tree.

3. A multi-agent review pipeline

Let one coordinator write the candidate repository, then fan out security review, tests, linting, and documentation checks across snapshot readers. Every reviewer sees the same starting state and cannot mutate the shared source. The catch is deliberate: a reviewer that needs a later coordinator edit must be recreated with a new snapshot.

4. A data team reusing a prepared dataset

Use one writer to download, normalize, and index a dataset, then mount snapshots into short-lived analysis sandboxes. The expensive preparation happens once, while concurrent readers receive a consistent input. This is a good fit for repeatable evaluation, but not for a live dataset that every reader expects to update in place.

5. A research agent accumulating files over several sessions

Store citations, extracted text, intermediate tables, and a local search index on the Drive. A new sandbox can continue from that folder instead of scraping and indexing the same sources again. The payoff is reproducible working material; the risk is treating files as durable truth without a separate backup or provenance system.

6. A model or toolchain cache for sporadic jobs

Pre-seed a Drive with model weights, compilers, or other large inputs, then start compute only when a job arrives. The first cache-miss read can be slower because Vercel fetches from durable storage, while later cache-hit reads run at NVMe speed. This pattern pays when idle compute would cost more than keeping the used bytes stored.

7. A training platform with resumable student projects

Assign a Drive to each project, mount it into a fresh sandbox for a session, and detach it when the session ends. Students retain files while the platform releases compute. The one-writer limit is helpful for preventing two active sessions from editing the same project, but the product still needs its own identity, backup, and retention rules.

Two products worth building

Search volume is a demand signal, not a revenue forecast. The useful question is whether the capability removes a painful job for a group already looking for a solution.

Strongest: an agent workspace lease broker

Build a small control plane that maps each agent or user project to a Drive, grants one timed writer lease, creates frozen reader sandboxes for tests and previews, and exposes region, attachment, and deletion status. Teams building coding agents would pay for the coordination layer because the raw storage primitive does not decide who owns the writer.

US keyword data shows about 8,100 monthly searches for “ai powered coding agent”, with commercial intent. The adjacent market already accepts a platform bill: E2B lists Pro at $150 per month plus usage, while persistent multi-day sessions sit in its custom Enterprise tier. That is not a direct price comparison, but it is a credible budget anchor for teams buying agent infrastructure.

The smallest sellable version needs a Drive-per-workspace mapping, a writer queue with expiry, snapshot-reader creation, a usage view, and safe cleanup. The catch is the moat. Vercel or an agent framework can absorb a thin wrapper, so the product needs operational policy, audit history, recovery, and provider portability rather than a prettier getOrCreate() button.

A warm-start layer for cloud development environments

Package a repository template, Drive-backed dependency path, cache warmer, explicit region policy, and before-versus-after setup telemetry for platform teams. Sell the result as shorter cold starts inside an existing Vercel estate, not as a complete development environment.

US keyword data shows about 1,900 monthly searches for “cloud integrated development environment”, with a $9.03 CPC. That paid-search value suggests vendors compete for the audience. The MVP can be narrow: Node and pnpm first, one region, one cache policy, and a dashboard that separates storage, reads, writes, Active CPU, and memory.

The catch is scope. A Drive supplies one persistent directory. It does not provide an IDE, secret management, collaboration, image management, backup, or cross-region replication. A product that promises a full cloud workstation on this primitive alone will disappoint buyers.

Limits that should change your design

• One writer means one owner. Serialize mutations. Snapshot readers are for fan-out work, not collaborative editing.
• Readers are frozen. A running reader never receives a later write. Recreate it with a new snapshot.
• The first snapshot needs a write. Initialize the Drive before starting reader sandboxes.
• The main region must match. A Drive stays in one region and cannot be moved. Set the region explicitly.
• A sandbox gets four mounts. Each path must be absolute and mount paths cannot overlap.
• A Drive is not the whole machine. Use a sandbox snapshot for a full environment. Use a Drive for a directory that should evolve independently.
• Cold reads can be slower. Cache-hit reads and writes run at NVMe speed, but durable-storage cache misses do not.
• Deletion is final. Vercel describes drive.delete() as permanent. A Drive should not be your only backup.

There is also a live documentation conflict. The September 23 launch says sandboxes mounting Drives cannot use failover regions. The region page, dated September 22, says failover can load a Drive across regions with higher read latency. Until Vercel reconciles those statements, treat Drive failover as unsupported in your architecture and test it again before relying on it.

If your job only needs more temporary room during one run, a Drive is the wrong first move. Read the companion guide to Vercel Sandbox's larger scratch disk and keep persistence out of the design.

The Monday move

Pick one restart-heavy agent workflow next week. Put only its project files and dependency cache on one Drive, keep a single writer, and run the four checks above. Record setup time before and after, plus Drive storage, reads, writes, Active CPU, and memory as separate lines. Expand the pattern only if the shorter restart is worth the added storage bill and coordination rule.

If you want a durable agent workspace designed and instrumented for production, I build AI production systems.