Skip to content

Agent Workspace Volumes: Picking the Persistence Boundary

Persist an agent's workspace or cached dependencies when reuse justifies storage costs and the volume's concurrency and file-count limits fit the workload.

A workspace persistence boundary is the single filesystem path that separates what survives an agent's sandbox from what dies with it. In Vercel's example the rule is positional. With a drive mounted at /workspace, "everything under /workspace persists on the drive. Everything else belongs to the sandbox" (Vercel, 2026-10-15). Agents resume in a differently configured environment: "Agents can mount the same drive in a new environment configured for the next task and continue where they left off" (Vercel, 2026-10-15). On Vercel the price is one writer, one region, and a slower cold read.

Choosing the boundary

Northflank recommends a default for independent tasks: "Use ephemeral AI sandboxes by default for independent, reproducible tasks" (Northflank).

  1. Weigh saved work and setup time against retained-state costs. Vercel documents drives for project files and cached dependencies (Vercel docs). Northflank says reuse reduces setup, but adds dependency drift and cleanup obligations (Northflank).
  2. The workload fits the writer contract. Vercel permits one writer; Google's stateful reference gives each agent a private workspace, and Google also documents a shared mode. Vercel: "Only one sandbox at a time can mount a given drive as read-write" (Vercel docs). Google's Agent Sandbox reference uses ReadWriteOnce, where "an agent starts up with a private isolated storage directory it has sole read and write access to" (Google Cloud). Modal allows concurrent writers but has no locking: "Last write wins in case of concurrent modification of the same file" (Modal). It recommends no more than five writers on Volumes v1. Google's ReadWriteMany collaborative workspace is the shared option on GKE (Google Cloud).
  3. The file count fits the volume version. Modal recommends Volumes v1 hold "less than 50,000 files and directories", because "The latency to attach or modify a Volume scales linearly with the number of files in the Volume" (Modal). Count the files you plan to mount against that figure before you mount them. Modal now recommends v2 for new volumes, with support for more files and concurrent writes from hundreds of containers (Modal).

Isolate fan-out writes

Vercel shares a dataset through read-only, point-in-time mounts: "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" (Vercel docs). Google documents an exploration-branching mode that reaches the same shape through access modes, where you "mount the template folder as read-only and providing a separate writable scratchpad" (Google Cloud). Readers write results elsewhere: "They use the shared files as input and save their results separately" (Vercel, 2026-10-15).

Forking a workspace gives each branch its own writable copy, and the reconciliation is yours to build: "Forks don't merge back into the original drive" (Vercel, 2026-10-15). Forking the whole environment instead is sandbox forking.

Why it works

Vercel distinguishes a drive's mounted directory from a snapshot's full sandbox filesystem. Its combined example uses a snapshot with tools installed, then a drive for "project files and cached dependencies" (Vercel docs). This supports both preserving work and avoiding repeated dependency setup. Google sorts the same decision by data lifecycle into stateful, point-in-time-restore, and ephemeral workspace patterns (Google Cloud). Northflank, which sells both lifecycles, lands on the same split: "combine both when an agent needs a durable workspace plus disposable execution" (Northflank).

When this backfires

  • Retained dependencies need maintenance. Northflank lists the costs: "dependency drift, accumulated temporary files, compromised state surviving reconnection, and abandoned volumes consuming storage" (Northflank).
  • Failures stop being attributable. Reset the writable state and "a package installed by one task cannot quietly change the next" (Northflank).
  • Two agents share a tree. Modal's semantics are last-write-wins, so "any data the last writer didn't have when committing changes will be lost" (Modal). Even on Volumes v2, "any particular file should only be written to by a single container at a time" (Modal).
  • Placement and start latency are tight. A drive pins to one region and "A sandbox's main region must match a drive's region" (Vercel docs). On GKE the stateful reference is "applicable to agents that tolerate multi-second startup latency", and going sub-second through warm pools "requires custom scripting and a privileged DaemonSet" (Google Cloud).
  • The workspace holds fetched content. A volume that outlives the sandbox keeps whatever the agent wrote into it, and every later mount sees it. Northflank lists the result as "compromised state surviving reconnection" (Northflank).
  • Reads are hot and uncached. Vercel rates a drive at "NVMe speed writes and cache hit reads, slower cache miss reads" against a snapshot's "NVMe speed reads and writes" (Vercel docs).

Example

An agent works one repository across several sessions. The mount itself is two commands (Vercel, 2026-10-15):

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

Vercel's documented combination keeps installed tools in the sandbox snapshot and project files plus cached dependencies on the drive (Vercel docs). Reusing dependencies saves setup work but retains state that needs cleanup (Northflank). On Modal Volumes v1, attach latency scales linearly with file count (Modal). That latency claim is specific to Modal's volume implementation.

Vercel's limits bound the shape: drives "default to 1 TiB, or 1 GiB on Hobby, with up to 16 TiB available" (Vercel, 2026-10-15), and "A sandbox can mount up to 4 drives per run" (Vercel docs).

Key Takeaways

  • In Vercel's example the boundary is positional: everything under the mount point persists on the drive and everything else belongs to the sandbox
  • Compare dependency setup time with retained-state maintenance costs. Vercel supports cached dependencies on drives; Modal Volumes v1 also adds attach latency as file count grows
  • Vercel permits one writable mount; Google documents a private workspace per agent. Modal allows concurrent writers with last-write-wins per file, and Google also documents a shared mode. Give fan-out workers separate result paths
  • The costs are vendor-specific. Vercel drives are single-region and read slower on a cache miss. GKE's stateful reference suits agents that tolerate multi-second startup, and sub-second start needs warm pools
  • A workspace that outlives its sandbox keeps whatever the agent wrote into it; Northflank lists "compromised state surviving reconnection" as a cost
Emerging — single recent source Last reviewed: 2026-10-28