How to let several Vercel Sandbox agents write the same workspace at once

Several Vercel sandboxes can't write the same Vercel Drive at once: only one sandbox at a time mounts a Drive read-write, and the others get read-only snapshots fixed at the moment they mount. To let several sandboxes read and write one workspace at the same time, mount a shared network file system in each of them instead. An Archil disk mounts over FUSE in Vercel Sandbox, and in conditional mode every sandbox can write anywhere that no other sandbox has checked out.

Can several Vercel sandboxes write the same Drive?

Vercel's Drives documentation says Drives are mounted read-write by default and that only one sandbox at a time can mount a given Drive read-write. Other sandboxes can mount read-only snapshots of it. Vercel says each snapshot mount reflects the Drive as it was at the moment you mounted it and doesn't include writes made afterwards; to pick up more recent writes, you mount a new snapshot.

A Drive fork copies the Drive's data into a new Drive, and writes to the fork don't change the original. Forks give each agent its own copy, not one shared workspace.

For one sandbox working alone, this model works well: Vercel describes Drive performance as NVMe-speed writes and cache-hit reads, with slower reads on a cache miss. The limit shows up when one agent edits code while other sandboxes run tests on it. Each test sandbox sees the code as it was when it mounted, and none of them can write results back to the Drive.

Two workarounds and where they stop

• Run every agent inside one sandbox with a shared directory. There is still one writer, but every agent now shares one VM's CPU, memory and lifetime.
• Mount a fresh read-only snapshot in each test sandbox after every edit. That works when tests run against discrete versions, but the test sandboxes still can't write to the workspace, and every new edit needs a new mount.

Mount one Archil disk read-write in every sandbox

Vercel Sandbox VMs support FUSE, so an Archil disk mounts as a regular directory. Install the client with curl -fsSL https://archil.com/install | sh and run archil mount as root with the disk's mount token; the Vercel Sandbox guide walks through it. Start the sandboxes in the Vercel region next to the disk: the guide maps aws-us-east-1 to iad1, aws-us-west-2 to pdx1 and aws-eu-west-1 to dub1.

A plain archil mount is exclusive: one client writes, and others can mount with --read-only. For several writers, mount with --conditional or --shared. Up to 5,000 clients can connect to one disk, per Archil's limits page. In Archil's published measurements inside a Vercel sandbox, mounting the disk took 51 ms (median of 5).

Mounting a disk on compute outside Archil (external mounts) needs a paid plan; the Free plan doesn't include it.

Example: an editing agent and two test runners on one disk

The script below starts three sandboxes and mounts the same disk in conditional mode in each. The editing agent takes exclusive write access to src/ with archil checkout, and each test runner writes its own log under results/. archil invalidate-cache on the mount root drops the runner's cached entries so its next read goes to the server, which is how a runner picks up an edit right away. Each sandbox runs archil unmount before it stops, so writes it buffered reach the disk and the disk is released.

import { Sandbox } from "@vercel/sandbox";
 
const { ARCHIL_DISK_ID, ARCHIL_MOUNT_TOKEN } = process.env;
 
// Start a sandbox next to the disk (aws-us-east-1 -> iad1) and mount the shared workspace
async function startAgent() {
  const sandbox = await Sandbox.create({ region: "iad1", persistent: false, timeout: 30 * 60_000 });
  const run = async (script: string, env: Record<string, string> = {}) => {
    const result = await sandbox.runCommand({ cmd: "bash", args: ["-c", script], env, sudo: true });
    if (result.exitCode !== 0) throw new Error(await result.stderr());
    return result.stdout();
  };
  await run("apt-get update -qq && curl -fsSL https://archil.com/install | sh > /dev/null");
  // --conditional: every sandbox can write anywhere no other sandbox has checked out
  await run(`mkdir -p /workspace && archil mount ${ARCHIL_DISK_ID} /workspace --region aws-us-east-1 --conditional`, {
    ARCHIL_MOUNT_TOKEN: ARCHIL_MOUNT_TOKEN!,
  });
  return { sandbox, run };
}
 
const [editor, ...testers] = await Promise.all([startAgent(), startAgent(), startAgent()]);
try {
  // The editing agent takes exclusive, local-speed writes on src/
  await editor.run("mkdir -p /workspace/src /workspace/results && archil checkout /workspace/src");
  // ... the agent edits files under /workspace/src ...
 
  // Test runners read the latest files and write their own logs
  await Promise.all(
    testers.map((t, i) =>
      t.run(`archil invalidate-cache /workspace && ls /workspace/src > /workspace/results/tester-${i}.log`),
    ),
  );
} finally {
  // Send buffered writes, release the disk, then stop each sandbox
  for (const agent of [editor, ...testers]) {
    await agent.run("archil unmount /workspace");
    await agent.sandbox.stop();
  }
}

Choosing conditional or shared mode for concurrent writers

Archil's Sharing disks page describes both modes.

• Conditional mode (archil mount --conditional): any client can write any file or directory that no other client has checked out, with no archil checkout needed. Creating, renaming and deleting run on the server before the call returns. File content writes are buffered on the client and sent in the background; closing the file or calling fsync waits for them to reach the disk. Clients don't lock files for each other: if two clients write the same part of a file, the last write to reach the disk wins.
• Shared mode (archil mount --shared): the disk is read-only to a client until it runs archil checkout <path>, which gives it exclusive write access to that path at local-disk speed. Creating a new file or directory checks it out automatically.

Other sandboxes see changes as their client caches refresh. In Archil's measurement in a Vercel sandbox, a second sandbox with the disk mounted saw a new file after about 28 s with default caching; in a Modal sandbox, a reader that ran archil invalidate-cache first saw it in about 70 ms.

A layout that avoids conflicts: the editing agent checks out the source tree, and each test runner writes only to its own results path. If two agents really must edit one file, coordinate them in your application or give one of them the path with archil checkout.

What the other sandboxes can rely on after fsync

An Archil write is durable when fsync returns: it is stored redundantly across Availability Zones. See Data durability.

Archil published a Vercel Drive fsync test with the script to rerun it. A file written to a Drive and fsynced was missing from all 10 Drive snapshots and all 11 forks taken right away, and still missing from 7 of 10 snapshots and 9 of 10 forks taken 30 s later; from 60 s it was intact. An Archil disk mounted in a new sandbox right after fsync returned had the file in 20 of 20 trials.

The side-by-side numbers, including where the Drive is faster (npm ci took 2.2 s on a Drive and 3.3 s on Archil, for one sandbox writing alone), are on the Archil vs Vercel Sandbox comparison.