What changed in Vercel Sandbox from 2 to 3

Patch Changes

• Reject multiple tags filters on Sandbox.list() at the type level. The API supports filtering by a single tag, so passing more than one key in tags is now a compile-time error instead of a 400 from the API. (#312)

Minor Changes

• Add a deleteOrphanSnapshots option when deleting a sandbox. (#316)

  Deleting a persistent sandbox left all of its snapshots alive until they expired. sandbox.delete({ deleteOrphanSnapshots: true }) in the SDK and sandbox remove <name> --delete-orphan-snapshots in the CLI now also delete the snapshots of that sandbox that no other sandbox uses. It defaults to false, so the existing behaviour is unchanged.

Minor Changes

• Add multi-region support: (#301)

  • New region and failoverRegions options on sandbox create, fork, and update (SDK), with matching flags on sandbox create, fork, run, sh, and the sandbox config region / sandbox config failover-regions commands (CLI).
  • New failoverRegions getter on Sandbox and regions getter on Snapshot.
  • Regions are now shown in sandbox ls, sessions list, snapshots list/get, sandbox config list, and the create/fork summary.

• Sandbox.region and Sandbox.failoverRegions no longer return undefined: the getters now report the platform defaults (iad1 and []) when the API omits the fields, so their types are string and string[]. The new DEFAULT_SANDBOX_REGION export makes the default region readable. (#301)

Patch Changes

• Update defineSandboxProxy to limit the JWKS issuer cache size to prevent unbounded memory usage. (#309)

Patch Changes

• Surface the server's error message in APIError.message. Failed API requests previously reported only Status code 400 is not ok, hiding the actionable detail (e.g. Invalid request: `ports` should NOT have more than 15 items.) in error.json. The message now includes it directly. (#291)

• Correct the ports option JSDoc: the limit is 15 ports (matching the docs and API validation), not 4. (#292)

• Correct the resume option JSDoc on Sandbox.get and Sandbox.getOrCreate: the default is false (the client omits the param and the API defaults to not resuming), not true. A stopped persistent sandbox still auto-resumes on the first SDK call that needs a running session. (#293)

Major Changes

• Add support for Vercel Managed Images and deprecate the runtime option in the SDK and CLI. Runtime-based creation remains supported through the legacy v2 API; image-based and default creation use the v3 API. Passing both runtime and image is an error. (#276)

  Sandboxes that do not specify an image now use vercel/sandbox/universal. The previous default was the node24 runtime on Amazon Linux 2023. The new default is based on Ubuntu and includes Node.js 24, Bun, Python 3.14, coding agents, and common development and debugging tools.

  Existing runtime calls continue to work, it's recommended to migrate to Vercel managed images when possible:

  • Not using runtime: omit image to use the new Universal image, or set image: "vercel/sandbox/node:24" for an Ubuntu-based Node.js equivalent to the previous default.
  • Using runtime: "node22": use image: "vercel/sandbox/node:22" for an Ubuntu-based equivalent.
  • Using runtime: "node24": use image: "vercel/sandbox/node:24" for an Ubuntu-based equivalent.
  • Using runtime: "node26": use image: "vercel/sandbox/node:26" for an Ubuntu-based equivalent.
  • Using runtime: "python3.13": use image: "vercel/sandbox/python:3.14" for an Ubuntu-based equivalent, and note the Python version upgrade.