Vercel Sandbox

Minor Changes

• Expose the source image of a sandbox as a property on Sandbox, populated when the sandbox was created from a container image (#253)

Patch Changes

• Clarify that network policies can only contain one of transform or forwardURL (#251)

Patch Changes

• Expose a typed error when creating a sandbox user whose username already exists. (#250)

Minor Changes

• Add multi-user and group management: createUser, asUser, createGroup, addUserToGroup, and removeUserFromGroup on the Sandbox class, plus a SandboxUser class that scopes command and file operations to a specific user's context (#116)

Minor Changes

• Add support for drives via a new Drive class and CLI commands. (#196)

Minor Changes

• Commands now surface how long they took to execute with the durationMs field (#243)

Minor Changes

• Report the live timeout deadline of running sandboxes. Sandbox.list and Sandbox.get now expose expiresAt, reflecting the current session's deadline including any timeout extensions, and sandbox list renders it in the TIMEOUT column. Sandbox.update({ timeout }) (and sandbox config timeout) now also extends the currently running session so an increased timeout takes effect immediately instead of only applying to future sessions. (#239)

Minor Changes

• Support creating a sandbox from a custom image via the new image option on Sandbox.create and the --image flag on sandbox create / sandbox run. (#232)

Patch Changes

• Single API call to run, wait and get logs of command (#223)

Patch Changes

• Fix scope inference failing with a raw Zod validation error. Teams missing updatedAt are now kept and malformed team entries are skipped. The CLI also no longer leaks raw validation details when scope can't be determined, showing a friendly hint instead. OAuth response parse failures are masked the same way. (#225)

Minor Changes

• Move the interactive shell server out of the sandbox and into the sandbox-controller. sandbox connect/ssh (CLI) and the new Sandbox.openInteractive() (SDK) now request a WebSocket URL and token from the API and connect to the controller-hosted PTY, instead of installing and bootstrapping the vc-interactive-server binary inside the sandbox at connect time. This removes the bundled server binary along with the @vercel/pty-tunnel and @vercel/pty-tunnel-server packages. (#222)

Patch Changes

• Upgrade Zod to v4 and update validators for Zod 4 compatibility. (#219)

Minor Changes

• Add support for drives via a new Drive class and CLI commands. (#196)

Patch Changes

• Update Undici version to fix incompatibility with Node.js 26 (#220)

Minor Changes

• Add timeoutMs to runCommand (SDK) and a --timeout <duration> flag to sandbox exec (CLI). (#212)

Patch Changes

• Show the current snapshot's siblings in snapshots tree. The tree now reads the API's anchor node so snapshots sharing the current snapshot's parent are listed, and siblings are rendered by snapshot ID instead of source session ID. (#211)

Patch Changes

• Add updatedAt getter to the Snapshot class (#208)

Major Changes

• Introduce named and long-lived sandboxes (#177)

Minor Changes

• Add L7 request matchers and forward URLs support to network policy rules. (#177)

• Support pagination (CLI and SDK) when listing sandboxes, snapshots, sessions (#177)

• Add defineSandboxProxy helper in @vercel/sandbox/proxy to easily implement network policies forwarding rules (#188)

• Rename sandbox to session, namedSandbox to sandbox (#177)

• Support keepLastSnapshots feature for CLI and SDK (#193)

• Add sandbox port replacement support through update. (#177)

• Support default snapshot expiration for persistent sandboxes (#177)

• Refactor the sandbox update and deprecate old network-policy update (#177)

• Support a new method: Sandbox.getOrCreate() (#177)

• Rename snapshotOnShutdown to persistent (#177)

• Automatically scale memory to vcpu when updating (#177)

• Move to cursor pagination. Support new sortyBy parameter for lists. Support new statusUpdatedAt filter (#177)

• Add Sandbox.fork(...) to the SDK and sandbox fork <source> to the CLI for forking an existing sandbox into a new one. (#205)

• Remove support for blocking parameter in .stop() and default to always blocking. Improve CLI output when stopping a sandbox. (#177)

• Lists now unwrap the json and return the items and pagination fields directly (#177)

• Support new onResume parameter in Sandbox.create and Sandbox.get (#177)

• Support snapshot tree pagination (#191)

Patch Changes

• Add support for tags (#177)

• Fix an 422 error when trying to resume a sandbox after snapshotting (#177)

• Add Node 26 support. (#177)

• Add support for patch + delete v2 endpoints for named sandboxes. (#177)

• Fix readFile writing the API error JSON into the destination when the file response is not an octet-stream. The SDK now rejects any non-application/octet-stream response (including 2xx with a JSON error body) instead of piping it verbatim to the caller's stream. (#202)

• Fix bug where the first ssh connection hang (#177)

• Support updading current-snapshot-id of an existing sandbox (#177)

• Fix JsDocs, messages and double-error message bug (#177)

Minor Changes

• Add Sandbox.fork(...) to the SDK and sandbox fork <source> to the CLI for forking an existing sandbox into a new one. The fork copies as many config parameters as the server exposes — resources (vcpus), timeout, networkPolicy, tags, ports, persistent, snapshotExpiration, keepLastSnapshots — and lets the caller override any of them. Environment variables are not copied (encrypted server-side) and must be re-supplied via env / --env. (#205)

  Breaking: removed sandbox create --sandbox-snapshot <name> and Snapshot.fromSandbox(name). Use sandbox fork <name> / Sandbox.fork({ sourceSandbox: name }) instead. Raw snapshot IDs are still supported via sandbox create --snapshot <id> and Sandbox.create({ source: { type: "snapshot", snapshotId } }).

Patch Changes

• Fix readFile writing the API error JSON into the destination when the file response is not an octet-stream. The SDK now rejects any non-application/octet-stream response (including 2xx with a JSON error body) instead of piping it verbatim to the caller's stream. (#202)

Minor Changes

• Add defineSandboxProxy helper in @vercel/sandbox/proxy to easily implement network policies forwarding rules (#188)

• Support snapshot tree pagination (#191)

Minor Changes

• Support keepLastSnapshots feature for CLI and SDK (#193)

Minor Changes

• Support new CLI --sandbox-snapshot parameter and new SDK static method Snapshot.fromSandbox() (#189)

• Add sandbox port replacement support through update. (#177)

Patch Changes

• Add Node 26 support. (#181)

Patch Changes

• Add Node 26 support. (#179)

Minor Changes

• Add L7 request matchers and forward URLs support to network policy rules. (#173)

Patch Changes

• Update auth API base URL (#166)

Patch Changes

• Support updading current-snapshot-id of an existing sandbox

Minor Changes

• Expose Filesystem api from Sandbox (#112)

Patch Changes

• Reuse Undici Agent across instances (#143)

• Smarter fallback team selection for scope inference: tries defaultTeamId first, then the best hobby-plan OWNER team (personal team or most recently updated). Filters fallback candidates by billing.plan === 'hobby' to avoid selecting pro/enterprise teams. Skips teams that return 403 and shows a helpful error when no team allows sandbox creation. (#120)

• Add workflow serialization support for the Snapshot class via WORKFLOW_SERIALIZE / WORKFLOW_DESERIALIZE, fixing serialization errors when a Snapshot instance is returned from a workflow step. (#140)

Minor Changes

• Support new onResume parameter in Sandbox.create and Sandbox.get

Minor Changes

• Rebase from main

Patch Changes

• Handle abort signal and early stream close in runCommand to avoid misleading Zod error (#135)

Patch Changes

• Fix stdout()/stderr()/output() failing on deserialized Command instances with "logs() requires an API client" error. (#130)

Patch Changes

• Build and publish both ESM and CJS outputs for the SDK package. (#84)

• Support useworkflow serialization for sandboxes and commands (#72)

• Fix a Size mismatch when encoding binaries during write operations (#127)

• Accept string and Uint8Array in writeFiles() content, not just Buffer. (#128)

Patch Changes

• Fix an 422 error when trying to resume a sandbox after snapshotting

Minor Changes

• Support default snapshot expiration for persistent sandboxes

Minor Changes

• Add support for setting file permissions (mode) in the writeFiles API. Files can now include an optional mode property to set permissions on the tarball, avoiding the need for a separate chmod command. (#90)

  await sandbox.writeFiles([
    {
      path: "/usr/local/bin/myscript",
      content: Buffer.from("#!/bin/bash\necho hello"),
      mode: 0o755,
    },
  ]);
  

Minor Changes

• Move to cursor pagination. Support new sortyBy parameter for lists. Support new statusUpdatedAt filter

Patch Changes

• Fix an error with resuming while reading a file