sandboxes

Update a sandbox

Changed on

Updates the configuration of a sandbox. Only the provided fields will be modified; omitted fields remain unchanged.

patch/v2/sandboxes/{name}

Request

  • Base URL: https://api.vercel.com
  • URL: https://api.vercel.com/v2/sandboxes/{name}
  • Auth: HTTP bearer

Path parameters

namestring required

The sandbox to update.

Example:my-sandbox

Query parameters

projectIdstring

The project ID that owns the named sandbox. When provided, takes precedence over OIDC project context.

resumeboolean

Whether to automatically resume a stopped named sandbox by creating a new instance from its snapshot. Defaults to false.

teamIdstring
Example:team_1a2b3c4d5e6f7g8h9i0j1k2l

The Team identifier to perform the request on behalf of.

slugstring
Example:my-team-url-slug

The Team slug to perform the request on behalf of.

Request body

runtime'node22' | 'node24' | 'node26' | 'python3.13'

The runtime environment for the sandbox. Determines the pre-installed language runtimes and tools available.

timeoutinteger

Maximum duration in milliseconds that the sandbox can run before being automatically stopped.

persistentboolean

Whether the sandbox persists its state across restarts via automatic snapshots.

region'iad1' | 'sfo1' | 'cle1' | 'cdg1' | 'fra1' | 'arn1' | 'sin1' | 'pdx1' | 'lhr1' | 'icn1' | 'bom1' | 'cpt1' | 'dub1' | 'gru1' | 'hkg1' | 'syd1' | 'yul1' | 'hnd1' | 'kix1'

The Vercel region in which to create the sandbox.

failoverRegionsstring[]

The regions the sandbox falls back to when it cannot be created in region.

mountsobject

Drives to mount to the sandbox at the provided path. Replaces the current mounts; an empty object removes them all. Changes take effect when the next session starts.

envobject

Default environment variables for the sandbox. Set to empty object to clear.

currentSnapshotIdstring

The snapshot ID to set as the current snapshot. Must be active and belong to the same project.

tagsobject

Key-value tags to associate with the sandbox. Replaces existing tags. Set to empty object to clear. Maximum 5 tags.

Example request

{
  "resources": {
    "vcpus": 2,
    "memory": 4096
  },
  "runtime": "node24",
  "timeout": 300000,
  "networkPolicy": {
    "mode": "custom",
    "allowedDomains": [
      "api.github.com",
      "*.npmjs.org"
    ],
    "allowedCIDRs": [
      "35.192.0.0/12",
      "104.16.0.0/12"
    ],
    "deniedCIDRs": [
      "35.192.0.0/12"
    ]
  },
  "region": "iad1",
  "failoverRegions": [
    "sfo1",
    "cle1"
  ],
  "env": {
    "NODE_ENV": "production",
    "HELLO": "world"
  },
  "tags": {
    "env": "staging",
    "team": "platform"
  }
}

Response

OR

Example response

{
  "sandbox": {
    "createdAt": 1750344501629,
    "cwd": "/vercel/sandbox",
    "expiresAt": 1750344801629,
    "failoverRegions": [
      "sfo1",
      "cle1"
    ],
    "image": "my-team/my-project/my-repo@sha256:2c4e8f9a1b3d5e7f091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708",
    "keepLastSnapshots": {
      "count": 5,
      "deleteEvicted": true,
      "expiration": 604800000
    },
    "memory": 1024,
    "name": "my-sandbox",
    "persistent": true,
    "region": "iad1",
    "runtime": "node22",
    "snapshotExpiration": 604800000,
    "status": "running",
    "statusUpdatedAt": 1750344501629,
    "tags": {
      "team": "hive",
      "user": "bob"
    },
    "timeout": 300000,
    "totalActiveCpuDurationMs": 5000,
    "totalDurationMs": 60000,
    "totalEgressBytes": 4096,
    "totalIngressBytes": 2048,
    "updatedAt": 1750344501629,
    "vcpus": 2
  }
}

Changes