sandbox-volume: transactional workspace sync for Vercel Sandbox

Showcase
1

@giselles-ai/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.

2 Likes
Vercel Weekly (2026-03-23)