Skip to content
Docs

Update a sandbox

PATCHhttps://api.vercel.com/v2/sandboxes/{name}
Updates the configuration of a sandbox. Only the provided fields will be modified; omitted fields remain unchanged.
https://api.vercel.com/v2/sandboxes/{name}
const response = await fetch('https://api.vercel.com/v2/sandboxes/name?projectId=string&resume=true&teamId=string&slug=string', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "resources": {
      "vcpus": "2",
      "memory": "4096"
    },
    "runtime": "node24",
    "timeout": "300000",
    "persistent": "true",
    "snapshotExpiration": "value",
    "keepLastSnapshots": "string",
    "networkPolicy": {
      "mode": "custom",
      "allowedDomains": [],
      "allowedCIDRs": [],
      "deniedCIDRs": [],
      "injectionRules": [
        {
          "domain": "string",
          "headers": "value",
          "match": {
            "path": {
              "exact": "string",
              "startsWith": "string"
            },
            "method": [],
            "queryString": [
              {
                "key": {
                  "exact": "string",
                  "startsWith": "string"
                },
                "value": {
                  "exact": "string",
                  "startsWith": "string"
                }
              }
            ],
            "headers": [
              {
                "key": {
                  "exact": "string",
                  "startsWith": "string"
                },
                "value": {
                  "exact": "string",
                  "startsWith": "string"
                }
              }
            ]
          }
        }
      ]
    },
    "region": "iad1",
    "failoverRegions": [],
    "mounts": "value",
    "networkId": "example_id",
    "env": "[object Object]",
    "ports": [],
    "currentSnapshotId": "example_id",
    "tags": "[object Object]"
  }),
});


const data = await response.json();
console.log(data);
Response
{
  "routes": [
    {
      "port": "123",
      "subdomain": "string",
      "system": "true",
      "url": "https://example.com"
    }
  ],
  "sandbox": {
    "architecture": "amd64",
    "createdAt": "1750344501629",
    "currentSessionId": "example_id",
    "currentSnapshotId": "example_id",
    "cwd": "/vercel/sandbox",
    "expiresAt": "1750344801629",
    "failoverRegions": [],
    "image": "my-team/my-project/my-repo@sha256:2c4e8f9a1b3d5e7f091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708",
    "keepLastSnapshots": {
      "count": "5",
      "deleteEvicted": "true",
      "expiration": "604800000"
    },
    "memory": "1024",
    "mounts": "value",
    "name": "my-sandbox",
    "networkId": "example_id",
    "networkPolicy": {
      "allowedCIDRs": [],
      "allowedDomains": [],
      "deniedCIDRs": [],
      "mode": "allow-all",
      "s3Key": "string"
    },
    "persistent": "true",
    "region": "iad1",
    "runtime": "node22",
    "snapshotExpiration": "604800000",
    "status": "running",
    "statusUpdatedAt": "1750344501629",
    "tags": "[object Object]",
    "timeout": "300000",
    "totalActiveCpuDurationMs": "5000",
    "totalDurationMs": "60000",
    "totalEgressBytes": "4096",
    "totalIngressBytes": "2048",
    "updatedAt": "1750344501629",
    "v0": "false",
    "vcpus": "2"
  }
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Path parameters

namestringRequired
The sandbox to update.

Query parameters

projectIdstringOptional
The project ID that owns the named sandbox. When provided, takes precedence over OIDC project context.
resumebooleanOptional
Whether to automatically resume a stopped named sandbox by creating a new instance from its snapshot. Defaults to false.
teamIdstringOptional
The Team identifier to perform the request on behalf of.
slugstringOptional
The Team slug to perform the request on behalf of.

Body

application/json
resourcesobjectOptional
Resources to define the VM
runtimestringOptional
The runtime environment for the sandbox. Determines the pre-installed language runtimes and tools available.
timeoutintegerOptional
Maximum duration in milliseconds that the sandbox can run before being automatically stopped.
persistentbooleanOptional
Whether the sandbox persists its state across restarts via automatic snapshots.
snapshotExpirationobjectOptional2 variants
keepLastSnapshotsobjectOptional
networkPolicyobjectOptional2 variants
regionstringOptional
The Vercel region in which to create the sandbox.
failoverRegionsarrayOptional
The regions the sandbox falls back to when it cannot be created in region.
mountsobjectOptional
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.
networkIdobjectOptional2 variants
envobjectOptional
Default environment variables for the sandbox. Set to empty object to clear.
portsarrayOptional
List of ports to expose from the sandbox. Each port will be accessible via a unique URL. Maximum of 15 ports can be exposed.
currentSnapshotIdstringOptional
The snapshot ID to set as the current snapshot. Must be active and belong to the same project.
tagsobjectOptional
Key-value tags to associate with the sandbox. Replaces existing tags. Set to empty object to clear. Maximum 5 tags.

Response

200Success
routesarrayRequired
sandboxobjectRequired
This object contains information related to a Vercel NamedSandbox.

Errors

400One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
401The request is not authorized.
402The account is missing a payment so payment method must be updated
403You do not have permission to access this resource.
404Error
409Error
410Error
422Error
429The concurrency limit has been exceeded.
500Error
502Error