What is a Vercel Sandbox Drive?

A Drive is persistent storage mounted as a directory inside Vercel Sandbox. Its lifecycle is separate from a sandbox, so data can survive a stopped run and be attached to a later sandbox.

Can multiple sandboxes write to the same Drive?

No. Vercel permits one read-write mount at a time. Multiple sandboxes can read concurrent point-in-time snapshots after the Drive has been written at least once.

Do Drive snapshots include later writes?

No. A read-only snapshot reflects the Drive when it is mounted. A consumer must mount a new snapshot to see changes written afterward.

How many Drives can one sandbox mount?

A sandbox can mount up to four Drives at separate paths. This supports separating a workspace, dependency cache, model data, and another durable dataset.

Can a Drive move between Vercel regions?

A Drive stays in its creation region. Any sandbox mounting it must run in that region and cannot use failover regions for that mount.

How large can a Vercel Sandbox Drive be?

The public beta defaults to 1 TiB, or 1 GiB on Hobby. Vercel says Drives can be configured up to 16 TiB, with higher limits available by request.

Should an agent store secrets on a Drive?

Long-lived secrets should come from a secret manager at runtime instead of being written into a persistent workspace. Treat Drive contents as durable data that requires tenant isolation, cleanup, and audit controls.

Vercel Sandbox Drives for Persistent Agent

Vercel Sandbox Drives add a durable directory to an otherwise disposable compute model. An agent can clone a repository, install dependencies, build an index, stop its sandbox, and attach the same Drive to a later run. The storage survives independently of the sandbox instance.

That convenience changes the architecture. A persistent workspace can carry stale dependencies, untrusted files, customer data, and broken state from one run to the next. Vercel also enforces one read-write mount at a time, pins each Drive to its creation region, and bills storage, reads, and writes separately. A useful design has to account for ownership, concurrency, isolation, cleanup, and cost from the start.

What Vercel Released

Vercel announced the public beta for Sandbox Drives on 23 September 2026 for Hobby, Pro, and Enterprise plans. The feature mounts persistent storage at a chosen directory when a sandbox starts.

Persistence is independent of compute

A Drive is not tied to one sandbox identity. The same named Drive can be attached across runs and sandbox instances, so the application can discard compute without discarding workspace state.

This is a better fit than copying an entire repository and dependency tree to object storage after every agent turn. The agent continues to use ordinary filesystem operations under the mount path, while orchestration decides which Drive and mode it receives.

One writer, several snapshot readers

Vercel permits one read-write mount at a time. After the Drive has received its first write, other sandboxes can mount point-in-time, read-only snapshots concurrently.

The snapshot is fixed when mounted. Writes made later by the active writer do not appear inside already running readers. A reader must mount a fresh snapshot to observe the newer state.

Capacity and region are explicit constraints

One sandbox can mount up to four Drives at distinct paths. The public beta defaults to a 1 TiB maximum, except Hobby where the default is 1 GiB. Vercel says the size can be configured up to 16 TiB and higher limits can be requested.

Every Drive stays in its creation region. Sandboxes that mount it must run in that region and cannot use failover regions. Storage architecture and compute placement are therefore the same decision for Drive-backed work.

Start with the Smallest Useful Mount

Creating and mounting a Drive takes little code. The design around the mount needs more thought than the SDK call.

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

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

const sandbox = await Sandbox.create({
  mounts: {
    '/workspace': workspace,
  },
})

Anything written beneath /workspace persists on the Drive after the sandbox stops. Files elsewhere follow the sandbox's normal lifecycle.

Mount at a clear boundary

Use a top-level path such as /workspace, /cache, or /models. A clear boundary makes backup, cleanup, quotas, and incident review easier. It also prevents durable state from being scattered through the sandbox filesystem.

Application code should know which paths persist. A build script that writes credentials or temporary test data into /workspace has created durable data even if the author assumed the sandbox would disappear.

Keep transient files outside

Logs needed only for the current request, extracted secrets, temporary archives, browser profiles, and scratch downloads should remain outside the Drive or be deleted before the writer releases it. Persist only what earns the recovery or reuse benefit.

This distinction reduces storage charges and cross-run contamination. It also makes a workspace easier to inspect because every durable file has an intended purpose.

Name Drives by ownership

A global name such as agent-workspace is fine for a demo and dangerous in a multitenant service. Encode the tenant, project, environment, and workspace identity in the orchestration layer, then validate the mapping before creating or retrieving a Drive.

Do not derive a storage name directly from unchecked user input. Use an internal identifier so two customers, branches, or environments cannot collide through naming.

Choose What Deserves Persistence

Four common categories benefit from Drive storage: working trees, dependency caches, model or dataset artifacts, and on-disk agent memory. They have different safety and lifecycle requirements.

Repository workspaces

A durable clone avoids fetching the repository and rebuilding local indexes for every session. It also preserves uncommitted changes when an agent pauses and resumes.

The risk is hidden drift. The working tree may contain an old branch, stale generated files, modified hooks, an interrupted merge, or malicious content introduced by an earlier task. Run a workspace health check before every new writer attaches.

git status --porcelain=v1
git remote -v
git rev-parse --show-toplevel
git fsck --no-progress

Do not automatically erase unexpected changes. Quarantine the workspace or require a recovery decision so legitimate uncommitted work is not lost.

Dependency caches

Package caches can save the most time while carrying less business data than a whole workspace. Give each ecosystem its own Drive or directory and include runtime, architecture, and lockfile information in the cache key.

A cache should be replaceable. If deleting it would destroy the only copy of important data, it is a database in disguise and needs stronger controls than a build cache.

Models and datasets

Large model files and datasets are natural Drive candidates because repeated downloads consume time and bandwidth. Record the source, checksum, license, version, and creation date beside the artifact.

Avoid letting an agent overwrite a shared model directory during inference. A controlled writer can publish a versioned artifact, and many workers can mount snapshots for read-only use.

Agent memory

On-disk memory can preserve summaries, indexes, plans, and checkpoints. Keep this data structured and scoped to the correct subject. A shared free-form memory directory can easily leak one user's context into another user's run.

Store provenance with each record. The next session should know who created it, which repository and commit it describes, and when it expires.

Design Around the Single-Writer Rule

The one-writer constraint is a consistency primitive. It prevents two sandboxes from changing the same filesystem concurrently, but the application must decide what happens when a second writer arrives.

Acquire ownership before compute

Do not create an expensive sandbox and only then discover that the Drive is busy. Resolve the workspace, acquire an application-level lease, and attach the Drive after ownership is clear.

The lease should include a writer ID, task ID, acquisition time, expiry, and fencing token. The fencing token prevents an expired writer from continuing to publish state after a new writer takes over.

type WorkspaceLease = {
  driveName: string
  writerId: string
  taskId: string
  fencingToken: number
  expiresAt: string
}

Vercel enforces the mount rule, while the lease gives your product a useful queue, timeout, and audit model.

Queue or fork competing writers

If two tasks need the same workspace, you can queue the second task or give it a separate Drive. Queueing preserves a linear history. Forking improves throughput but creates a merge problem at the repository or application layer.

Use a new Drive for independent branches, experiments, and speculative agent runs. Use one serialized writer for a shared mutable workspace whose exact filesystem state matters.

Release ownership in a finally block

Writer cleanup must run after success, failure, cancellation, and timeout. Stop the sandbox, confirm the mount is detached, persist a final status record, and release the application lease.

A crashed orchestrator can leave uncertainty even if the platform eventually tears down compute. A reconciliation job should compare active leases, running sandboxes, and Drive attachment state, then repair stale ownership safely.

Use Snapshots as Published Read Views

Read-only Drive snapshots let many sandboxes consume a consistent point in time without competing for the writer.

const workspace = await Drive.getOrCreate({
  name: 'tenant-42-repo-7-main',
})

const [review, test] = await Promise.all([
  Sandbox.create({ mounts: { '/workspace': workspace.snapshot() } }),
  Sandbox.create({ mounts: { '/workspace': workspace.snapshot() } }),
])

Vercel notes that the Drive must have been written at least once before snapshots can be mounted.

Treat a snapshot like a release

A writer should publish a marker only after the filesystem is coherent. For a repository workspace, that can mean no lock operation is active, indexes are flushed, and a manifest records the commit and dependency state.

Readers should validate the marker on startup. A point-in-time view is consistent at the storage layer, but it may still represent an application-level operation that was interrupted halfway through.

Readers do not follow the writer

An existing snapshot never sees later writes. This is useful for repeatable tests and reviews. It can surprise an application that expects a live shared folder.

Pass a snapshot or generation identifier to every consumer. When the writer publishes a new generation, start new readers or explicitly remount instead of assuming files will refresh underneath them.

Fan out immutable work

Snapshot readers are a good fit for test matrices, static analysis, review agents, search indexing, and evaluation runs. Each consumer sees the same starting state and cannot modify it.

Write results to external storage or to per-task Drives. Do not funnel every result back through the shared workspace unless one controlled writer validates and applies it.

Separate Workspace, Cache, and Results

A sandbox can mount four Drives. Use that limit to create boundaries instead of treating one large volume as a universal disk.

A practical mount layout

const sandbox = await Sandbox.create({
  mounts: {
    '/workspace': workspace,
    '/cache': dependencyCache.snapshot(),
    '/models': modelStore.snapshot(),
    '/results': taskResults,
  },
})

The workspace and results Drive may be writable depending on the workflow. Shared cache and model mounts should usually be snapshots. This prevents a task from poisoning a widely reused artifact.

Make cache promotion explicit

If a task discovers new dependencies, write them into a task-local cache. A separate validation job can verify checksums, scan packages, and promote the cache through a controlled writer.

Direct writes from arbitrary agent runs to a global cache save a step but allow one compromised task to influence many later sandboxes.

Put outputs under retention policy

Results often contain logs, patches, screenshots, test artifacts, or generated packages. Define how long each class survives and which system owns the canonical copy.

A Drive is useful working storage. Long-term records may belong in object storage, an artifact registry, or a database with retention, legal hold, and access logging.

Pin Compute to the Drive Region

Regional placement is part of correctness because a Drive cannot move with a failing sandbox. Vercel says mounted sandboxes must run in the Drive's creation region and cannot use failover regions.

Choose the region from the data owner

Create the Drive in the region selected for the tenant or project, then store that region with the Drive record. Every sandbox request should read the stored value rather than recomputing placement from current traffic.

This prevents a user routed to another geography from creating compute that cannot attach the existing workspace.

Plan for regional failure

Automatic compute failover cannot carry a region-pinned Drive. Decide whether the service will pause, rebuild from a remote canonical source, or maintain a separately replicated recovery copy.

For source-code agents, the Git remote and artifact registry may provide enough recovery. For unique on-disk memory or unpushed changes, the recovery objective requires an explicit export or backup process.

Account for data residency

A persistent workspace can contain source code, customer files, logs, and model inputs. Region selection must match contractual and regulatory requirements. Include Drive creation and deletion in your data inventory.

Do not assume that the region of the web request determines the region of durable storage. The Drive's creation record is the reliable source.

Prevent Cross-Task Contamination

Persistence preserves good work and bad residue equally. Every writer startup should evaluate the previous run before trusting the directory.

Use a workspace manifest

{
  "schemaVersion": 1,
  "tenantId": "tenant_42",
  "repositoryId": "repo_7",
  "branch": "main",
  "commit": "4d53c9e",
  "runtime": "node-24",
  "lockfileHash": "sha256:...",
  "lastWriterTask": "task_981",
  "updatedAt": "2026-09-24T12:00:00Z"
}

Validate the tenant and repository before doing anything else. Rebuild indexes or dependencies when the runtime or lockfile hash changes.

Clean known transient state

Browser profiles, test databases, sockets, PID files, lock files, temporary credentials, and tool-specific crash state can break the next session. Maintain a narrow cleanup list based on the tools you run.

Avoid broad recursive deletion at startup. It can erase legitimate agent work and makes recovery harder. Quarantine unknown files when their provenance is unclear.

Scan durable content

Run secret detection, malware scanning where appropriate, and repository policy checks before publishing a workspace to snapshot readers. Treat dependency lifecycle scripts and executable artifacts as untrusted across runs.

Persistence turns an isolated compromise into a potential future-session compromise. Scanning at the writer-to-reader boundary reduces that risk.

Keep Secrets Out of Durable Storage

Inject credentials at runtime and remove them before the sandbox stops. A token written beneath the mount path may outlive the compute and appear in future snapshots.

Use short-lived credentials

Issue a credential for the task, tenant, repository, and environment. Keep its lifetime close to the expected run duration. Prefer an identity exchange over a static secret copied from application configuration.

Configure tools to read credentials from environment variables or an in-memory agent rather than writing them to .env, Git credential files, shell history, or package-manager configuration on the Drive.

Redact logs and checkpoints

Agent logs often capture commands, HTTP headers, environment fragments, and tool output. Apply redaction before writing logs to /results or another durable path.

Checkpoints should contain references to credentials, not credential values. A resumed session can request a new token for the stored subject and scope.

Delete on revocation

When a user disconnects a repository or requests data deletion, find every Drive associated with that subject. Stop active writers, remove derived snapshots or exports, delete the Drive, and record completion outside the deleted storage.

Ownership metadata in a database makes this possible. Names alone are not a sufficient inventory.

Model Drive Costs Before Scaling

Vercel bills Drive storage, reads, and writes by region. In iad1, the launch announcement lists $0.05 per GB-month for storage, $0.0015 per GB read, and $0.004 per GB written. Hobby includes 15 GB of storage and 30 GB each of reads and writes per month.

Calculate all three meters

A 100 GB dependency tree retained for a month has a storage charge. Mounting it across many cold sandboxes can add read volume, while repeated installs or generated outputs add write volume. The cheapest design depends on reuse frequency and churn.

Measure bytes stored by Drive, bytes read by task type, bytes written by task type, and the useful cache-hit time saved. A cache that changes every run may cost more than downloading a compact artifact.

Set quotas below platform limits

The 1 TiB default and 16 TiB configurable maximum are capacity ceilings, not product defaults. Give each tenant and workspace a much smaller quota based on the workload.

Alert at soft limits, reject unexpected growth, and expose the largest directories in operations tooling. Agents can generate runaway logs or recursive build output quickly.

Garbage collect by last useful access

Track the last writer, last reader, associated branch, and canonical source. Delete abandoned branch workspaces after a recovery window. Rebuildable caches can expire sooner than unpushed work.

Deletion should respect active leases and mounts. Mark a Drive for deletion, block new writers, wait for or stop active sandboxes, then remove it.

Operate the Lifecycle Explicitly

Drive creation is the beginning of a resource lifecycle. Production systems need inventory, health, migration, and deletion paths.

Maintain a control-plane record

Store Drive ID or name, tenant, project, environment, region, size limit, state, current lease, creation time, last access, and retention class. Use this record to authorize every mount.

The control plane should be the only component allowed to call getOrCreate for user workspaces. Otherwise a naming bug can create orphaned storage that no cleanup job knows about.

Reconcile platform and application state

Run a periodic job that finds records without Drives, Drives without records, expired writer leases, old snapshots or exports, and workspaces above quota. Produce an operator-visible report before deleting uncertain resources.

Reconciliation is also where you catch a sandbox that died before updating the task database or a deployment that changed naming rules.

Version workspace formats

Agent tools, runtimes, indexes, and manifests evolve. Put a schema version in the workspace and write migrations that can run without destroying source work.

For large or risky migrations, fork to a new Drive, validate it, then switch the control-plane pointer. The old Drive becomes a rollback copy for a bounded period.

Test Failure and Recovery

The happy path proves that files persist. The production test is whether state remains understandable after interruption.

Kill the writer mid-operation

Stop a sandbox during Git checkout, dependency installation, index creation, and result publication. Start a new writer and verify that the manifest and health checks detect incomplete work.

Do not rely on a process exit hook to restore consistency. The orchestrator should be able to recover from a sandbox that disappears without cleanup.

Confirm snapshot isolation

Mount a reader snapshot, change a file through the writer, and prove the existing reader still sees the old version. Then mount a new reader and prove it sees the new version.

This test catches code that assumes live shared storage and establishes the generation semantics for developers.

Exercise region loss

Simulate the Drive region being unavailable. Confirm whether tasks pause, rebuild from Git and artifacts, or fail with a clear recovery status. Make sure global routing does not repeatedly start sandboxes in incompatible regions.

Document the recovery point for unpushed changes. If the only copy is on the Drive, say so plainly in the product and operational runbook.

A Reference Architecture

A reliable agent workspace service separates control, compute, and durable state:

The API authenticates the user and resolves a tenant-scoped workspace record.
The scheduler reads the Drive region and acquires a fenced writer lease.
The sandbox starts in that region with the workspace mounted read-write.
Runtime credentials arrive from a secret service and remain outside the mount.
Startup checks validate the manifest, repository, and transient state.
The agent works and writes results to a separate task-scoped path or Drive.
The writer flushes state, updates the manifest, and publishes a generation.
Test and review sandboxes mount read-only snapshots of that generation.
The orchestrator stops compute, releases the lease, and updates usage records.
Retention jobs delete abandoned workspaces and rebuildable caches.

This design keeps the single writer intentional and turns snapshot readers into repeatable consumers. It also gives cost, data deletion, and incident response a dependable inventory.

For related architecture decisions, compare this persistence model with Vercel Sandbox Routing and Region Selection. The evaluation side is covered in Coding Agent Evals with Harbor and Vercel Sandbox, while OpenAI Agents API Harness Patterns covers broader orchestration concerns.

Production Checklist

Before attaching a Drive to a production agent workflow:

Define a tenant-scoped name and control-plane record.
Pick the region from data residency and recovery requirements.
Mount only the directories that need persistence.
Keep temporary files and credentials outside the mount.
Acquire a fenced application lease before the read-write mount.
Decide whether competing writers queue or fork.
Publish a versioned manifest before snapshot readers start.
Treat snapshots as immutable generations that never follow later writes.
Separate workspace, cache, model, and result storage where practical.
Validate persistent content for secrets and unsafe executable residue.
Set tenant quotas well below platform maximums.
Meter storage, reads, writes, and actual time saved.
Reconcile leases, sandboxes, and Drives on a schedule.
Test interrupted writers, stale snapshots, and regional failure.
Implement deletion for disconnects, expired branches, and user requests.

Drives remove repeated setup work, but they also remove the clean slate that made disposable sandboxes easy to reason about. Keep the writer serialized, make every readable state a named generation, and treat durable agent files as real customer data.