--- title: update-a-sandbox product: vercel url: /docs/rest-api/sandboxes-v2-beta/update-a-sandbox type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about update-a-sandbox on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Update a sandbox ```http PATCH /v2/sandboxes/{name} ``` Updates the configuration of a sandbox. Only the provided fields will be modified; omitted fields remain unchanged. ## Authentication **bearerToken**: HTTP bearer ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `name` | string. maxLength: 128; pattern: `^[a-zA-Z0-9_-]+$` | Yes | The sandbox to update. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `projectId` | string. maxLength: 128 | No | The project ID that owns the named sandbox. When provided, takes precedence over OIDC project context. | | `teamId` | string | No | The Team identifier to perform the request on behalf of. | | `slug` | string | No | The Team slug to perform the request on behalf of. | ## Request body Required: No Content-Type: `application/json` ```json { "type": "object", "properties": { "resources": { "type": "object", "description": "Resources to define the VM", "properties": { "vcpus": { "type": "integer", "description": "The number of virtual CPUs to allocate to the sandbox. Must be 1, or an even number.", "minimum": 1 }, "memory": { "type": "integer", "description": "The amount of memory in megabytes to allocate to the sandbox. Must equal vcpus * 2048.", "minimum": 2048 } } }, "runtime": { "type": "string", "description": "The runtime environment for the sandbox. Determines the pre-installed language runtimes and tools available.", "enum": [ "node22", "node24", "python3.13" ] }, "timeout": { "type": "integer", "description": "Maximum duration in milliseconds that the sandbox can run before being automatically stopped.", "minimum": 1000 }, "persistent": { "type": "boolean", "description": "Whether the sandbox persists its state across restarts via automatic snapshots." }, "snapshotExpiration": { "description": "Default snapshot expiration time in milliseconds. Set to 0 to disable expiration. When set, this value is used as the default expiration for all snapshots created for this sandbox.", "oneOf": [ {}, { "type": "integer" } ] }, "networkPolicy": { "type": "object", "description": "Network access policy for the sandbox.\\n Controls which external hosts the sandbox can communicate with.\\n Use \\\"allow-all\\\" mode to allow all traffic, \\\"deny-all\\\" to block all traffic or \\\"custom\\\" to provide specific rules.", "required": [ "mode" ], "properties": { "mode": { "type": "string", "description": "The network access policy mode. Use \\\"allow-all\\\" to permit all outbound traffic. Use \\\"deny-all\\\" to block all outbound traffic. Use \\\"custom\\\" to specify explicit allow/deny rules.", "enum": [ "allow-all", "deny-all", "custom", "default-allow", "default-deny" ] }, "allowedDomains": { "type": "array", "description": "List of domain names the sandbox is allowed to connect to. Only applies when mode is \\\"custom\\\". Supports wildcard patterns (e.g., \\\"*.example.com\\\" matches all subdomains).", "items": { "type": "string", "description": "A domain name pattern. Use \\\"*\\\" for wildcard matching of subdomains (e.g., \\\"*.example.com\\\")." } }, "allowedCIDRs": { "type": "array", "description": "List of IP address ranges (in CIDR notation) the sandbox is allowed to connect to. Traffic to these addresses bypasses domain-based restrictions.", "items": { "type": "string", "description": "An IP address range in CIDR notation (e.g., \\\"35.192.0.0/12\\\" for IPv4 or \\\"2001:db8::/32\\\" for IPv6)." } }, "deniedCIDRs": { "type": "array", "description": "List of IP address ranges (in CIDR notation) the sandbox is blocked from connecting to. These rules take precedence over all allowed rules.", "items": { "type": "string", "description": "An IP address range in CIDR notation to block." } } } }, "env": { "type": "object", "description": "Default environment variables for the sandbox. Set to empty object to clear.", "additionalProperties": { "type": "string" } }, "tags": { "type": "object", "description": "Key-value tags to associate with the sandbox. Replaces existing tags. Set to empty object to clear. Maximum 5 tags.", "additionalProperties": { "type": "string", "maxLength": 256 } } } } ``` ## Responses ### 200: No description Content-Type: `application/json` ```json { "type": "object", "required": [ "sandbox" ], "properties": { "sandbox": { "type": "object", "description": "This object contains information related to a Vercel NamedSandbox.", "required": [ "createdAt", "currentSessionId", "name", "persistent", "status", "statusUpdatedAt", "updatedAt" ], "properties": { "name": { "type": "string", "description": "The unique identifier of the sandbox." }, "currentSnapshotId": { "type": "string", "description": "Current snapshot ID that the named sandbox is pointing to." }, "currentSessionId": { "type": "string", "description": "Current session ID the sandbox is pointing to." }, "status": { "type": "string", "description": "The status of the current sandbox.", "enum": [ "stopping", "running", "stopped" ] }, "statusUpdatedAt": { "type": "number", "description": "The time when the sandbox status was last updated, in milliseconds since the epoch." }, "persistent": { "type": "boolean", "description": "Whether the sandbox persists its state across restarts via automatic snapshots.", "enum": [ false, true ] }, "region": { "type": "string", "description": "The region the sandbox runs in." }, "vcpus": { "type": "number", "description": "Number of virtual CPUs allocated." }, "memory": { "type": "number", "description": "Memory allocated in MB." }, "runtime": { "type": "string", "description": "Runtime identifier." }, "timeout": { "type": "number", "description": "Timeout in milliseconds." }, "snapshotExpiration": { "type": "number", "description": "Default snapshot expiration time in milliseconds. 0 means no expiration." }, "networkPolicy": { "type": "object", "description": "Network policy configuration.", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "allow-all", "deny-all", "custom", "default-allow", "default-deny" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCIDRs": { "type": "array", "items": { "type": "string" } }, "deniedCIDRs": { "type": "array", "items": { "type": "string" } } } }, "totalEgressBytes": { "type": "number", "description": "Cumulative egress bytes across all sandbox runs." }, "totalIngressBytes": { "type": "number", "description": "Cumulative ingress bytes across all sandbox runs." }, "totalActiveCpuDurationMs": { "type": "number", "description": "Cumulative active CPU duration in milliseconds across all sandbox runs." }, "totalDurationMs": { "type": "number", "description": "Cumulative wall-clock duration in milliseconds across all sandbox runs." }, "cwd": { "type": "string", "description": "The working directory of the sandbox." }, "tags": { "type": "object", "description": "Key-value tags attached to the named sandbox.", "additionalProperties": { "type": "string" } }, "createdAt": { "type": "number", "description": "The time when the named sandbox was created, in milliseconds since the epoch." }, "updatedAt": { "type": "number", "description": "The time when the named sandbox was last updated, in milliseconds since the epoch." } } } } } ``` ### 400: One of the provided values in the request body is invalid. One of the provided values in the request query is invalid. ### 401: The request is not authorized. ### 402: No description ### 403: You do not have permission to access this resource. ### 404: No description ### 410: No description ### 422: No description ### 500: No description --- ## Related - [sandboxes-v2-beta endpoints](/docs/rest-api#sandboxes-v2-beta) - [REST API overview](/docs/rest-api) - [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints) --- [View full sitemap](/docs/sitemap)