--- title: create-a-named-sandbox product: vercel url: /docs/rest-api/sandboxes/create-a-named-sandbox canonical_url: "https://vercel.com/docs/rest-api/sandboxes/create-a-named-sandbox" last_updated: 2026-08-30 type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about create-a-named-sandbox on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Create a named sandbox ```http POST /v2/sandboxes ``` Creates a named sandbox environment. Named sandboxes have a unique name within a project and support automatic snapshotting on shutdown. ## Authentication **bearerToken**: HTTP bearer ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `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": { "networkPolicy": { "oneOf": [ { "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)." }, "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." }, "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." }, "injectionRules": { "type": "array", "description": "HTTP header injection rules for outgoing requests matching specific domains. Traffic to matching domains will be intercepted instead of proxied through encrypted connections." } } }, { "type": "object", "properties": { "allow": {}, "subnets": { "type": "object" } } } ] }, "runtime": { "type": "string", "description": "The runtime environment for the sandbox. Determines the pre-installed language runtimes and tools available.", "enum": [ "node22", "node24", "node26", "python3.13" ], "default": "node24" }, "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, "default": 2 }, "memory": { "type": "integer", "description": "The amount of memory in megabytes to allocate to the sandbox. Must equal vcpus * 2048.", "minimum": 2048 } } }, "source": { "description": "The source from which to initialize the sandbox filesystem. Can be a Git repository, a tarball URL, or an existing snapshot.", "oneOf": [ { "type": "object", "description": "Clone a Git repository into the sandbox.", "required": [ "type", "url" ], "properties": { "type": { "description": "Indicates the source is a Git repository." }, "url": { "type": "string", "description": "The URL of the Git repository to clone.", "format": "uri" }, "username": { "type": "string", "description": "Username for Git authentication. Required together with password for private repositories." }, "password": { "type": "string", "description": "Password or personal access token for Git authentication. Required together with username for private repositories." }, "depth": { "type": "integer", "description": "Create a shallow clone with history truncated to the specified number of commits. Useful for faster cloning of large repositories.", "minimum": 1 }, "revision": { "type": "string", "description": "The specific commit SHA, branch name, or tag to checkout after cloning." } } }, { "type": "object", "description": "Download and extract a gzipped tarball into the sandbox.", "required": [ "type", "url" ], "properties": { "type": { "description": "Indicates the source is a tarball." }, "url": { "type": "string", "description": "URL of a gzipped tarball (.tar.gz) to download and extract.", "format": "uri" } } }, { "type": "object", "description": "Restore the sandbox filesystem from an existing snapshot.", "required": [ "type", "snapshotId" ], "properties": { "type": { "description": "Indicates the source is a snapshot." }, "snapshotId": { "type": "string", "description": "The unique identifier of the snapshot to restore." } } } ] }, "projectId": { "type": "string", "description": "The target project slug or ID in which the sandbox will be assigned to." }, "ports": { "type": "array", "description": "List of ports to expose from the sandbox. Each port will be accessible via a unique URL. Maximum of 15 ports can be exposed.", "items": { "type": "integer", "description": "A port number to expose from the sandbox. Must be between 1024 and 65535.", "minimum": 1024, "maximum": 65535 } }, "image": { "type": "string", "description": "Image to use for the sandbox.", "maxLength": 255 }, "timeout": { "type": "integer", "description": "Maximum duration in milliseconds that the sandbox can run before being automatically stopped.", "minimum": 1000 }, "env": { "type": "object", "description": "Default environment variables for the sandbox. These are inherited by all commands unless overridden.", "default": {}, "additionalProperties": { "type": "string" } }, "mounts": { "type": "object", "description": "List of drives to mount to the sandbox at the provided path.", "additionalProperties": { "type": "object", "required": [ "drive" ], "properties": { "drive": { "type": "string", "description": "Name of the drive to mount. The drive must already exist.", "pattern": "^[a-zA-Z0-9_-]+$", "maxLength": 64 }, "mode": { "type": "string", "description": "Mount the drive read-only or read-write.", "enum": [ "read-only", "read-write" ], "default": "read-write" } } } }, "region": { "type": "string", "description": "The Vercel region in which to create the sandbox.", "enum": [ "iad1", "sfo1", "cle1", "cdg1", "fra1", "arn1", "sin1", "pdx1", "lhr1", "icn1", "bom1", "cpt1", "dub1", "gru1", "hkg1", "syd1", "yul1", "hnd1", "kix1" ], "default": [ "iad1", "sfo1", "cle1", "cdg1", "fra1", "arn1", "sin1", "pdx1", "lhr1", "icn1", "bom1", "cpt1", "dub1", "gru1", "hkg1", "syd1", "yul1", "hnd1", "kix1" ] }, "failoverRegions": { "type": "array", "description": "The regions the sandbox falls back to when it cannot be created in `region`.", "items": { "type": "string", "enum": [ "iad1", "sfo1", "cle1", "cdg1", "fra1", "arn1", "sin1", "pdx1", "lhr1", "icn1", "bom1", "cpt1", "dub1", "gru1", "hkg1", "syd1", "yul1", "hnd1", "kix1" ] } }, "name": { "type": "string", "description": "Name for the sandbox. Must be unique per project and URL-safe (alphanumeric, hyphens, underscores).", "pattern": "^[a-zA-Z0-9_-]+$", "maxLength": 128 }, "persistent": { "type": "boolean", "description": "Whether the sandbox persists its state across restarts via automatic snapshots. Defaults to true.", "default": true }, "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" } ] }, "keepLastSnapshots": { "type": "object", "description": "Protect the N most recent snapshots with different expiration/deletion behavior.", "required": [ "count" ], "properties": { "count": { "type": "integer", "description": "Number of most recent snapshots to keep.", "minimum": 1, "maximum": 10 }, "expiration": { "description": "Expiration time in milliseconds for kept snapshots. Falls back to snapshotExpiration.", "oneOf": [ {}, { "type": "integer" } ] }, "deleteEvicted": { "type": "boolean", "description": "Whether to immediately delete evicted snapshots. Defaults to true." } } }, "tags": { "type": "object", "description": "Key-value tags to associate with the sandbox. Maximum 5 tags.", "additionalProperties": { "type": "string", "maxLength": 256 } } } } ``` ## Example request ### TypeScript ```typescript const response = await fetch('https://api.vercel.com/v2/sandboxes?teamId=string&slug=string', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ "networkPolicy": { "mode": "custom", "allowedDomains": [], "allowedCIDRs": [], "deniedCIDRs": [], "injectionRules": [ { "domain": "string", "headers": "value", "match": {} } ] }, "runtime": "node24", "resources": { "vcpus": "2", "memory": "4096" }, "source": { "type": "value", "url": "https://github.com/vercel/next.js.git", "username": "string", "password": "string", "depth": "1", "revision": "main" }, "projectId": "prj_abc123", "ports": [], "image": "string", "timeout": "300000", "env": "[object Object]", "mounts": "value", "region": "iad1", "failoverRegions": [], "name": "my-sandbox", "persistent": "true", "snapshotExpiration": "value", "keepLastSnapshots": { "count": "123", "expiration": "value", "deleteEvicted": "true" }, "tags": "[object Object]" }), }); const data = await response.json(); console.log(data); ``` ### Next.js ```typescript 'use server'; export async function callEndpoint() { const response = await fetch('https://api.vercel.com/v2/sandboxes?teamId=string&slug=string', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.VERCEL_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "networkPolicy": { "mode": "custom", "allowedDomains": [], "allowedCIDRs": [], "deniedCIDRs": [], "injectionRules": [ { "domain": "string", "headers": "value", "match": {} } ] }, "runtime": "node24", "resources": { "vcpus": "2", "memory": "4096" }, "source": { "type": "value", "url": "https://github.com/vercel/next.js.git", "username": "string", "password": "string", "depth": "1", "revision": "main" }, "projectId": "prj_abc123", "ports": [], "image": "string", "timeout": "300000", "env": "[object Object]", "mounts": "value", "region": "iad1", "failoverRegions": [], "name": "my-sandbox", "persistent": "true", "snapshotExpiration": "value", "keepLastSnapshots": { "count": "123", "expiration": "value", "deleteEvicted": "true" }, "tags": "[object Object]" }), next: { revalidate: 3600 } }); if (!response.ok) { throw new Error('Request failed'); } return response.json(); } ``` ### cURL ```bash curl -X POST 'https://api.vercel.com/v2/sandboxes?teamId=string&slug=string' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d "{ \"networkPolicy\": { \"mode\": \"custom\", \"allowedDomains\": [], \"allowedCIDRs\": [], \"deniedCIDRs\": [], \"injectionRules\": [ { \"domain\": \"string\", \"headers\": \"value\", \"match\": {} } ] }, \"runtime\": \"node24\", \"resources\": { \"vcpus\": \"2\", \"memory\": \"4096\" }, \"source\": { \"type\": \"value\", \"url\": \"https://github.com/vercel/next.js.git\", \"username\": \"string\", \"password\": \"string\", \"depth\": \"1\", \"revision\": \"main\" }, \"projectId\": \"prj_abc123\", \"ports\": [], \"image\": \"string\", \"timeout\": \"300000\", \"env\": \"[object Object]\", \"mounts\": \"value\", \"region\": \"iad1\", \"failoverRegions\": [], \"name\": \"my-sandbox\", \"persistent\": \"true\", \"snapshotExpiration\": \"value\", \"keepLastSnapshots\": { \"count\": \"123\", \"expiration\": \"value\", \"deleteEvicted\": \"true\" }, \"tags\": \"[object Object]\" }" ``` ## Example response ```json { "sandbox": { "name": "my-sandbox", "currentSnapshotId": "example_id", "currentSessionId": "example_id", "status": "running", "statusUpdatedAt": "1750344501629", "persistent": "true", "region": "iad1", "failoverRegions": [], "vcpus": "2", "memory": "1024", "runtime": "node22", "image": "my-repo@sha256:2c4e8f9a1b3d5e7f091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708", "timeout": "300000", "snapshotExpiration": "604800000", "keepLastSnapshots": { "count": "5", "expiration": "604800000", "deleteEvicted": "true" }, "networkPolicy": { "mode": "allow-all", "allowedDomains": [], "allowedCIDRs": [], "deniedCIDRs": [], "s3Key": "string" }, "totalEgressBytes": "4096", "totalIngressBytes": "2048", "totalActiveCpuDurationMs": "5000", "totalDurationMs": "60000", "cwd": "/vercel/sandbox", "tags": "[object Object]", "mounts": "value", "createdAt": "1750344501629", "updatedAt": "1750344501629", "expiresAt": "1750344801629" }, "session": { "sourceSandboxName": "my-sandbox", "projectId": "prj_123a6c5209bc3778245d011443644c8d27dc2c50", "id": "sbx_123a6c5209bc3778245d011443644c8d27dc2c50", "memory": "2048", "vcpus": "2", "region": "iad1", "runtime": "node22", "timeout": "3600000", "status": "running", "requestedAt": "1750344501629", "startedAt": "1750344501629", "cwd": "/vercel/sandbox", "requestedStopAt": "1750344501629", "stoppedAt": "1750344501629", "abortedAt": "1750344501629", "duration": "3600000", "sourceSnapshotId": "snap_123a6c5209bc3778245d011443644c8d27dc2c50", "snapshottedAt": "1750344501629", "createdAt": "1750344501629", "updatedAt": "1750344501629", "networkPolicy": { "mode": "custom", "allowedDomains": [], "allowedCIDRs": [], "deniedCIDRs": [], "injectionRules": [ {} ] }, "activeCpuDurationMs": "42", "networkTransfer": { "ingress": "123", "egress": "123" } }, "routes": [ { "url": "https://example.com", "port": "123", "subdomain": "string", "system": "true" } ] } ``` ## Responses ### 200: No description Content-Type: `application/json` ```json { "type": "object", "required": [ "routes", "sandbox", "session" ], "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": [ "running", "stopped", "stopping" ] }, "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 is pinned to: the region stored on the sandbox, otherwise the platform default. Where a running session actually landed is reported by `session.region`." }, "failoverRegions": { "type": "array", "description": "The regions the sandbox fails over to. Empty when it does not fail over.", "items": { "type": "string", "description": "The regions the sandbox fails over to. Empty when it does not fail over.", "enum": [ "arn1", "bom1", "cdg1", "cle1", "cpt1", "dub1", "fra1", "gru1", "hkg1", "hnd1", "iad1", "icn1", "kix1", "lhr1", "pdx1", "sfo1", "sin1", "syd1", "yul1" ] } }, "vcpus": { "type": "number", "description": "Number of virtual CPUs allocated." }, "memory": { "type": "number", "description": "Memory allocated in MB." }, "runtime": { "type": "string", "description": "Runtime identifier." }, "image": { "type": "string", "description": "Digest-pinned reference of the container image the sandbox was created from, when it was created from an image (\"{repository}@{manifestDigest}\")." }, "timeout": { "type": "number", "description": "Timeout in milliseconds." }, "snapshotExpiration": { "type": "number", "description": "Default snapshot expiration time in milliseconds. 0 means no expiration." }, "keepLastSnapshots": { "type": "object", "description": "Keep-last snapshot configuration.", "required": [ "count", "deleteEvicted" ], "properties": { "count": { "type": "number", "description": "Number of most recent snapshots to keep." }, "expiration": { "type": "number", "description": "Expiration time in milliseconds for kept snapshots." }, "deleteEvicted": { "type": "boolean", "description": "Whether to immediately delete evicted snapshots.", "enum": [ false, true ] } } }, "networkPolicy": { "type": "object", "description": "Network policy configuration.", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "allow-all", "custom", "default-allow", "default-deny", "deny-all" ] }, "allowedDomains": { "type": "array" }, "allowedCIDRs": { "type": "array" }, "deniedCIDRs": { "type": "array" }, "s3Key": { "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" } }, "mounts": { "type": "object", "description": "Key-value pairs of mount path and drive.", "additionalProperties": { "type": "object", "description": "Key-value pairs of mount path and drive.", "required": [ "drive" ] } }, "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." }, "expiresAt": { "type": "number", "description": "The time at which the currently running sandbox will time out, in milliseconds since the epoch. Only present while a session is running." } } }, "session": { "type": "object", "description": "This object contains information related to a Vercel Sandbox Session. v2 endpoints return \"session\" instead of \"sandbox\" as the response wrapper key.", "required": [ "createdAt", "cwd", "id", "memory", "projectId", "region", "requestedAt", "runtime", "sourceSandboxName", "status", "timeout", "updatedAt", "vcpus" ], "properties": { "sourceSandboxName": { "type": "string", "description": "The name of the source sandbox." }, "projectId": { "type": "string", "description": "The unique identifier of the project associated with this session." }, "id": { "type": "string", "description": "The unique identifier of the sandbox." }, "memory": { "type": "number", "description": "Memory allocated to this sandbox in MB." }, "vcpus": { "type": "number", "description": "Number of vCPUs allocated to this sandbox." }, "region": { "type": "string", "description": "The region where the sandbox is hosted." }, "runtime": { "type": "string", "description": "The runtime of the sandbox." }, "timeout": { "type": "number", "description": "The maximum amount of time the sandbox will run for in milliseconds." }, "status": { "type": "string", "description": "The status of the sandbox.", "enum": [ "aborted", "failed", "pending", "running", "snapshotting", "stopped", "stopping" ] }, "requestedAt": { "type": "number", "description": "The time when the sandbox was requested, in milliseconds since the epoch." }, "startedAt": { "type": "number", "description": "The time when the sandbox was started, in milliseconds since the epoch." }, "cwd": { "type": "string", "description": "The working directory of the sandbox." }, "requestedStopAt": { "type": "number", "description": "The time when the sandbox was requested to stop, in milliseconds since the epoch." }, "stoppedAt": { "type": "number", "description": "The time when the sandbox was stopped, in milliseconds since the epoch." }, "abortedAt": { "type": "number", "description": "The time when the sandbox was aborted, in milliseconds since the epoch." }, "duration": { "type": "number", "description": "The duration of the sandbox in milliseconds." }, "sourceSnapshotId": { "type": "string", "description": "The unique identifier of the snapshot associated with this sandbox, if any." }, "snapshottedAt": { "type": "number", "description": "The time when a snapshot was requested, in milliseconds since the epoch." }, "createdAt": { "type": "number", "description": "The time when the sandbox was created, in milliseconds since the epoch." }, "updatedAt": { "type": "number", "description": "The last time the sandbox was updated, in milliseconds since the epoch." }, "networkPolicy": { "type": "object", "description": "The network policy applied to this sandbox, if any.", "required": [ "mode" ], "properties": { "mode": { "type": "string", "description": "The network policy mode. - 'allow-all': All traffic is allowed. - 'deny-all': All traffic is blocked. - 'custom': Traffic is controlled by explicit allow/deny rules.", "enum": [ "allow-all", "custom", "deny-all" ] }, "allowedDomains": { "type": "array", "description": "List of domain names the sandbox is allowed to connect to. Supports wildcard patterns (e.g., \"*.vercel.com\" matches all subdomains)." }, "allowedCIDRs": { "type": "array", "description": "List of IP address ranges (in CIDR notation) the sandbox is allowed to connect to." }, "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." }, "injectionRules": { "type": "array", "description": "HTTP header injection rules for outgoing requests matching specific domains." } } }, "activeCpuDurationMs": { "type": "number", "description": "The amount of CPU time the sandbox consumed, if available, in milliseconds. This value is only available once the sandbox is stopped, and only if it stopped successfully." }, "networkTransfer": { "type": "object", "description": "The quantity of data transfered to and from the sandbox, in bytes. This value is only available once the sandbox is stopped, and only if it stopped successfully.", "required": [ "egress", "ingress" ], "properties": { "ingress": { "type": "number" }, "egress": { "type": "number" } } } } }, "routes": { "type": "array", "items": { "type": "object", "description": "This object represents a public route in a Vercel Sandbox.", "required": [ "port", "subdomain", "url" ], "properties": { "url": { "type": "string", "description": "A public URL to access the corresponding port in the Sandbox." }, "port": { "type": "number", "description": "The user port number that the route is mapped to." }, "subdomain": { "type": "string", "description": "The subdomain assigned to this route." }, "system": { "type": "boolean", "description": "Whether the route is reserved by the system (e.g. for internal use).", "enum": [ true ] } } } } } } ``` ### 400: One of the provided values in the request body is invalid. ### 401: The request is not authorized. ### 402: The account is missing a payment so payment method must be updated ### 403: You do not have permission to access this resource. ### 404: No description ### 409: No description ### 410: No description ### 422: No description ### 429: The concurrency limit has been exceeded. ### 500: No description --- ## Related - [sandboxes endpoints](/docs/rest-api#sandboxes) - [REST API overview](/docs/rest-api) - [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints) --- [View full sitemap](/docs/sitemap)