How to Persist Agent Workspace Files Across Sandboxes With Vercel Drives

The practical answer, per Vercel’s GA announcement on October 15, 2026: create one named drive, mount it at /workspace when the sandbox is created, and keep every file the agent must survive inside that path. A fresh sandbox, even one running a different runtime, then finds the cloned repo, intermediate artifacts, and logs exactly where the previous run left them. Two constraints come with the feature, and they shape the whole workflow. Only the mounted path persists; everything else dies with the environment. And drive forks, the mechanism for parallel exploration, never merge back into the original drive, so any branching strategy needs a manual merge plan.

One disclosure before the walkthrough: every GA-specific fact in this article comes from that single Vercel blog post, published two days before this writing. Drive storage pricing, durability and backup guarantees, snapshot mechanics, mount latency, and whether two sandboxes can safely write the same mounted drive concurrently are all unverified as of October 17, 2026. The announcement points to Vercel’s documentation for configuration, snapshots, and limits; the rest are not addressed in the announcement or the pricing page. The setup below is what the vendor says works; treat the operational safety questions as open until you check them yourself.

The failure mode Drives addresses

Vercel’s own documentation describes Sandbox as “isolated, ephemeral execution environments” for running untrusted or agent-generated code. Ephemeral is the point, and also the problem. When an agent’s work outgrows its sandbox, because the environment needs to be rebuilt with different tools, a different runtime, or simply replaced, everything the agent wrote inside it is discarded.

Drives changes what has to be snapshotted. In Vercel’s words: “We built Vercel Drives to keep an agent’s files independent of its execution environment… Agents can mount the same drive in a new environment configured for the next task and continue where they left off.” State outlives the environment, so checkpointing reduces to naming a drive. The tradeoff is coupling: the resume workflow now depends on Vercel Sandbox’s mount API rather than on a portable container image.

The persistence boundary is explicit and worth internalizing, because it is the most common way this setup will fail. From the announcement: “In this example, everything under /workspace persists on the drive. Everything else belongs to the sandbox. The next sandbox that mounts the drive finds the repository, and anything else the agent wrote there, where the previous run left it.” Anything the agent writes outside the mount, a downloaded model in /tmp, a cache in the home directory, a database initialized somewhere else, is gone on the next sandbox. The discipline this imposes is real: every durable output of the agent’s run has to be steered into the mounted path, either by convention or by configuration.

Walkthrough: create once, mount at create time

The workflow is two steps, and both are documented in the GA post.

From the CLI:

sandbox drives get-or-create agent-workspace
sandbox create --mount agent-workspace:/workspace

The first command is idempotent by name; the drive is created if it does not exist and reused if it does. That create-or-reuse behavior is read out of the command name, since the announcement documents the command without spelling out its reuse semantics. The second mounts that drive into the new sandbox at /workspace at creation time. Mounting happens at sandbox-create, not later, so the mount decision is part of the sandbox specification rather than a runtime configuration step.

From the Sandbox SDK, per the same announcement:

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

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

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

await sandbox.runCommand('git', ['clone', repoUrl, '/workspace/repo']);

The SDK example makes the intended pattern concrete: the agent’s first action clones into the mounted path, and from then on the repo lives on the drive, not in the sandbox. When the run finishes or the sandbox is replaced, the next sandbox created with the same mount argument resumes from that state.

Runtime switching is where this pays off most. Vercel’s documentation notes that you can “give Sandbox a custom image” for the code an agent executes. A task that starts in a general-purpose image and then needs, say, a different toolchain can move to a new sandbox built on a different image, with the same drive mounted, without copying the workspace. The vendor states the agent “can resume work in a new sandbox or switch runtimes without transferring its workspace.” Vercel also ships a one-click starter template built on eve, its open-source filesystem-first agent framework, if you want a reference implementation rather than wiring the mount yourself.

Mounted drive, fork, or rebuild: choosing a persistence strategy

Three options cover most agent workflows, and the choice turns on persistence scope and merge cost.

The mounted drive is the default for any agent doing multi-session work: one canonical workspace, no merge step, resume by name. Forks are the right tool when several agents should try different approaches to the same starting state in parallel, Vercel’s example is different transformations of a dataset, without interfering with each other. Rebuild-from-scratch remains the right call when the workspace itself is suspect: if an agent has been operating on untrusted input, persisting its entire filesystem also persists whatever it picked up along the way.

Two cells in that table deserve emphasis because they contradict plausible assumptions. First, forking is not branching. The announcement is unambiguous: “Forks don’t merge back into the original drive.” If three agents explore three approaches on three forks, someone, a human or a fourth agent, has to compare the forks and apply the winner’s changes to the original drive by hand. Budget for that step before fanning out. Second, the Hobby plan ceiling is 1 GiB, not 1 TiB. The announcement reads: “Drives default to 1 TiB, or 1 GiB on Hobby, with up to 16 TiB available.” One GiB is a repository plus modest artifacts, not a dataset workspace. Check the plan before designing around the default.

Running parallel agents against shared state

The announcement documents two sharing patterns. Other sandboxes can mount the same drive, and agents can mount read-only copies of a shared dataset “to analyze the data or generate reports without rebuilding the dataset.” Read-only sharing is the safe, documented case: many readers, one dataset, no coordination problem.

What the announcement does not say is whether concurrent writable mounts of one drive are safe. It says other sandboxes can mount the same drive, full stop. That sentence does not specify locking, conflict behavior, or consistency guarantees, and the fork feature’s existence suggests Vercel’s intended answer to parallel writes is isolation, not shared mutable state. My Read of the evidence: if your workflow has multiple agents writing simultaneously, use forks with an explicit merge step, or serialize writes yourself. Do not infer safe multi-writer semantics from a sentence that was probably written about read sharing. This is an inference from what the vendor chose to document, not a measured finding, and it should be one of the first things you verify if concurrent writers matter to your design.

The no-merge-back property also has a workflow consequence worth planning around. Forks are disposable branches with no pull-request equivalent. A practical pattern is to treat the original drive as canonical, have each forked agent write a machine-readable summary of what it changed and why (diffs, metrics, a decision note) into a known location on its fork, and have a merge step, human or agent, apply the chosen result back to the original. That adds orchestration you do not get for free, and it is the honest cost of the parallel-exploration feature.

Ceilings and quotas that bite

Beyond the drive size limits, the sandbox itself is quota-bounded, and on Hobby those bounds are tight. The Hobby plan includes per month, from Vercel’s pricing page: 5 hours of Sandbox Active CPU, 420 GB-hours of provisioned memory, 5,000 sandbox creations, 20 GB of data transfer, 10 concurrent sandboxes, and 15 GB of snapshot storage.

Read together with the drive limits, the Hobby tier supports evaluation and light sequential agent work, not a parallel-agent fan-out. Five hours of active CPU and ten concurrent sandboxes do not coexist for long, and a 1 GiB drive plus 20 GB of monthly transfer rules out dataset-heavy exploration. This is not a criticism of the tier; it is a sizing input. If the workflow you are designing assumes dozens of forks and large persisted artifacts, the plan decision comes before the mount command.

What the announcement does not say

The operational details a production decision actually hinges on are absent from the announcement and pricing page, and they are worth listing explicitly because a launch post is structurally unlikely to dwell on them:

• Drive storage pricing. Vercel’s pricing page lists no drive-storage line item. What a persisted 1 TiB drive costs per month is unverified.
• Durability and backups. No replication, durability, or backup guarantee appears in the announcement. Whether a drive can be lost, and what recovery looks like, is unknown.
• Snapshot mechanics. The announcement points to Vercel’s documentation for configuration, snapshots, and limits; check there before relying on snapshot behavior. How drive snapshots relate to the 15 GB sandbox snapshot storage quota is unverified.
• Mount latency and I/O performance. Nothing on attach time, throughput, or IOPS. For an agent that starts by reading a large repo from the drive, cold-start latency may matter and is unmeasured.
• Concurrent-writer semantics. Covered above; the announcement documents read-only sharing and, without specifying behavior, that other sandboxes can mount the same drive.

There is also a security caveat from outside the vendor’s material. According to Wikipedia’s account, Vercel disclosed a breach on April 19, 2026, originating from a compromised third-party AI tool, in which attackers accessed some Vercel environments and environment variables not marked as sensitive. The relevance here is narrow but real: a drive persists across sandbox replacements, so whatever lands on it persists too. Keep credentials and tokens out of the mounted path; the persistence that makes the drive useful makes it a worse place for secrets than the environment it replaces.

Verdict

For agents whose work should survive a sandbox replacement, mount one named drive at /workspace at create time, put everything durable inside it, and resume by mounting the same drive in the next sandbox. Use forks for parallel exploration only with a manual merge plan, because no merge-back path exists. Confirm your plan’s ceiling, 1 GiB on Hobby versus 1 TiB default, against the size of the workspace before committing.

Before production data goes on a drive, close the open operational questions listed above in Vercel’s documentation or with support.

Frequently Asked Questions

What is the maximum drive size on the Hobby plan?

Drives default to 1 TiB, or 1 GiB on Hobby, with up to 16 TiB available.

Do drive forks merge back into the original drive?

Forks don’t merge back into the original drive.