sandbox-volume: transactional workspace sync for Vercel Sandbox

/sandbox-volume is a thin transactional sync layer for @vercel/sandbox.

Vercel Sandbox already gives us safe, ephemeral execution. What we wanted to add was one missing layer: workspace continuity.

import { Sandbox } from "@vercel/sandbox";
import { SandboxVolume, VercelBlobStorageAdapter } from "@giselles-ai/sandbox-volume";

const adapter = new VercelBlobStorageAdapter();
const volume = await SandboxVolume.create({
  key: "sandbox-volume",
  adapter,
  include: ["src/**", "package.json"],
  exclude: [".sandbox/**/*", "dist/**"],
});

const initialSandbox = await Sandbox.create();
await volume.mount(initialSandbox, async () => {
  await initialSandbox.runCommand("mkdir", ["workspace"]);
  await initialSandbox.runCommand("echo", ["hello!", ">", "workspace/notes.md"]);
});

const anotherSandbox = await Sandbox.create();
await anotherSandbox.mount(anotherSandbox, async () => {
  await anotherSandbox.runCommand("cat", ["workspace/notes.md"]);
  // => hello!
});

Instead of treating the sandbox filesystem as the source of truth, sandbox-volume persists workspace files to external storage such as Vercel Blob. That lets files survive beyond a single sandbox lifecycle and stay readable or writable even when no sandbox is running.

What it does:

hydrate persisted files into a sandbox path
run your code
diff against the last saved manifest
commit changes back through a pluggable storage adapter

Why this exists:

snapshots can resume a sandbox, but long-lived workspace state is a different problem
agent workflows often need state to survive across turns, steps, or sandbox restarts
external storage is a better fit for durable workspace continuity than trying to treat the sandbox itself as persistent

The package currently includes:

a memory adapter for tests and examples
a Vercel Blob adapter for lightweight persistent workspace storage
support for include / exclude path filters
a fallback scan strategy when find is unavailable

If you are building on Vercel Sandbox and need state to outlive a single run, this may be useful.

import { Sandbox } from "@vercel/sandbox"; import { SandboxVolume, VercelBlobStorageAdapter } from "@giselles-ai/sandbox-volume"; const adapter = new VercelBlobStorageAdapter(); const volume = await SandboxVolume.create({ key: "sandbox-volume", adapter, include: ["src/**", "package.json"], exclude: [".sandbox/**/*", "dist/**"], }); const initialSandbox = await Sandbox.create(); await volume.mount(initialSandbox, async () => { await initialSandbox.runCommand("mkdir", ["workspace"]); await initialSandbox.runCommand("echo", ["hello!", ">", "workspace/notes.md"]); }); const anotherSandbox = await Sandbox.create(); await anotherSandbox.mount(anotherSandbox, async () => { await anotherSandbox.runCommand("cat", ["workspace/notes.md"]); // => hello! });