# Vercel Sandbox: what changed from 2 to 3

- Product: Vercel Sandbox (https://whatsnew.fyi/product/vercel-sandbox)
- Vendor: Vercel
- Range: changelog entries numbered after 2.9.2 up to and including 3.2.1, stable releases only
- Entries below: 5 releases (newest first)
- Resolved: 2 is 2.9.2 and 3 is 3.2.1, the newest stable release of each major we track
- Carrying security changes: 0 · CVEs mentioned: 0 · Mentioning breaking changes: 0 · Removing or deprecating something: 1
- Page: https://whatsnew.fyi/product/vercel-sandbox/compare/2...3

What's New is an index, not a publisher: every entry below links to the vendor's own release notes, which are the authoritative source. Entries are labelled where they are hand-curated sample data, pre-releases, or drawn from a secondary source such as a developer blog.

Reuse: the summaries, labels and curation here are © What's New. Quote freely with attribution and a link back; wholesale republication of the corpus is not permitted — terms: https://whatsnew.fyi/terms. The vendors' own release notes remain their publishers'.

## What changed (16 changes, grouped by kind)

### Added

#### 3.2.0 (2026-08-27)

- Add a deleteOrphanSnapshots option when deleting a sandbox to also delete snapshots that no other sandbox uses

#### 3.1.0 (2026-08-21)

- Add multi-region support with new region and failoverRegions options on sandbox create, fork, and update in SDK and matching flags in CLI commands
- Add failoverRegions getter on Sandbox and regions getter on Snapshot
- Show regions in sandbox ls, sessions list, snapshots list/get, sandbox config list, and create/fork summary
- Export DEFAULT_SANDBOX_REGION to make the default region readable

#### 3.0.0 (2026-08-07)

- Add support for Vercel Managed Images in the SDK and CLI

### Changed

#### 3.2.1 (2026-08-28)

- Reject multiple tags filters on Sandbox.list() at the type level to catch unsupported multi-tag filtering at compile time instead of receiving a 400 API error

#### 3.2.0 (2026-08-27)

- Deleting a persistent sandbox now supports cleaning up orphaned snapshots via the SDK and CLI, defaulting to false to preserve existing behavior

#### 3.1.0 (2026-08-21)

- Sandbox.region and Sandbox.failoverRegions no longer return undefined and now report platform defaults (iad1 and []) when API omits fields, with types string and string[]

#### 3.0.0 (2026-08-07)

- Change default sandbox image from node24 runtime on Amazon Linux 2023 to vercel/sandbox/universal based on Ubuntu with Node.js 24, Bun, Python 3.14, coding agents, and development tools
- Passing both runtime and image parameters is now an error

### Fixed

#### 3.1.0 (2026-08-21)

- Update defineSandboxProxy to limit the JWKS issuer cache size to prevent unbounded memory usage

#### 3.0.1 (2026-08-20)

- Surface the server's error message in APIError.message so that failed API requests include actionable details instead of only reporting the status code
- Correct the ports option JSDoc to reflect the actual limit of 15 ports
- Correct the resume option JSDoc on Sandbox.get and Sandbox.getOrCreate to reflect the default value of false

### Deprecated

#### 3.0.0 (2026-08-07)

- Deprecate the runtime option in the SDK and CLI

## Release notes

### 3.2.1

- Date: 2026-08-28
- Version: 3.2.1
- Original notes: https://github.com/vercel/sandbox/releases/tag/%40vercel/sandbox%403.2.1
- Permalink: https://whatsnew.fyi/product/vercel-sandbox/releases/3.2.1

- **changed** — Reject multiple tags filters on Sandbox.list() at the type level to catch unsupported multi-tag filtering at compile time instead of receiving a 400 API error

###### 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](https://github.com/vercel/sandbox/pull/312))

### 3.2.0

- Date: 2026-08-27
- Version: 3.2.0
- Original notes: https://github.com/vercel/sandbox/releases/tag/%40vercel/sandbox%403.2.0
- Permalink: https://whatsnew.fyi/product/vercel-sandbox/releases/3.2.0

- **added** — Add a deleteOrphanSnapshots option when deleting a sandbox to also delete snapshots that no other sandbox uses
- **changed** — Deleting a persistent sandbox now supports cleaning up orphaned snapshots via the SDK and CLI, defaulting to false to preserve existing behavior

###### Minor Changes

- Add a `deleteOrphanSnapshots` option when deleting a sandbox. ([#316](https://github.com/vercel/sandbox/pull/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.

### 3.1.0

- Date: 2026-08-21
- Version: 3.1.0
- Original notes: https://github.com/vercel/sandbox/releases/tag/%40vercel/sandbox%403.1.0
- Permalink: https://whatsnew.fyi/product/vercel-sandbox/releases/3.1.0

- **added** — Add multi-region support with new region and failoverRegions options on sandbox create, fork, and update in SDK and matching flags in CLI commands
- **added** — Add failoverRegions getter on Sandbox and regions getter on Snapshot
- **added** — Show regions in sandbox ls, sessions list, snapshots list/get, sandbox config list, and create/fork summary
- **changed** — Sandbox.region and Sandbox.failoverRegions no longer return undefined and now report platform defaults (iad1 and []) when API omits fields, with types string and string[]
- **added** — Export DEFAULT_SANDBOX_REGION to make the default region readable
- **fixed** — Update defineSandboxProxy to limit the JWKS issuer cache size to prevent unbounded memory usage

###### Minor Changes

- Add multi-region support: ([#301](https://github.com/vercel/sandbox/pull/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](https://github.com/vercel/sandbox/pull/301))

###### Patch Changes

- Update `defineSandboxProxy` to limit the JWKS issuer cache size to prevent unbounded memory usage. ([#309](https://github.com/vercel/sandbox/pull/309))

### 3.0.1

- Date: 2026-08-20
- Version: 3.0.1
- Original notes: https://github.com/vercel/sandbox/releases/tag/%40vercel/sandbox%403.0.1
- Permalink: https://whatsnew.fyi/product/vercel-sandbox/releases/3.0.1

- **fixed** — Surface the server's error message in APIError.message so that failed API requests include actionable details instead of only reporting the status code
- **fixed** — Correct the ports option JSDoc to reflect the actual limit of 15 ports
- **fixed** — Correct the resume option JSDoc on Sandbox.get and Sandbox.getOrCreate to reflect the default value of false

###### 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](https://github.com/vercel/sandbox/pull/291))

- Correct the `ports` option JSDoc: the limit is 15 ports (matching the docs and API validation), not 4. ([#292](https://github.com/vercel/sandbox/pull/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](https://github.com/vercel/sandbox/pull/293))

### 3.0.0

- Date: 2026-08-07
- Version: 3.0.0
- Original notes: https://github.com/vercel/sandbox/releases/tag/%40vercel/sandbox%403.0.0
- Permalink: https://whatsnew.fyi/product/vercel-sandbox/releases/3.0.0

- **added** — Add support for Vercel Managed Images in the SDK and CLI
- **deprecated** — Deprecate the runtime option in the SDK and CLI
- **changed** — Change default sandbox image from node24 runtime on Amazon Linux 2023 to vercel/sandbox/universal based on Ubuntu with Node.js 24, Bun, Python 3.14, coding agents, and development tools
- **changed** — Passing both runtime and image parameters is now an error

###### 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](https://github.com/vercel/sandbox/pull/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.