--- title: create-a-sandbox product: vercel url: /docs/rest-api/sandboxes/create-a-sandbox type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about create-a-sandbox on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Create a sandbox ```http POST /v1/sandboxes ``` Creates a new sandbox environment for executing code in an isolated virtual machine. A sandbox can be initialized from various sources including Git repositories, tarballs, or existing snapshots. Once created, you can execute commands, read/write files, and manage the sandbox lifecycle. ## 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": { "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 } } }, "runtime": { "type": "string", "description": "The runtime environment for the sandbox. Determines the pre-installed language runtimes and tools available.", "enum": [ "node22", "node24", "python3.13" ], "default": "node24" }, "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 } }, "timeout": { "type": "integer", "description": "Maximum duration in milliseconds that the sandbox can run before being automatically stopped.", "minimum": 1000 }, "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. These are inherited by all commands unless overridden.", "default": {}, "additionalProperties": { "type": "string" } } } } ``` ## Responses ### 200: No description Content-Type: `application/json` ```json { "type": "object", "required": [ "routes", "sandbox" ], "properties": { "sandbox": { "type": "object", "description": "This object contains information related to a Vercel Sandbox.", "required": [ "createdAt", "cwd", "id", "memory", "region", "requestedAt", "runtime", "status", "timeout", "updatedAt", "vcpus" ], "properties": { "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": [ "failed", "aborted", "pending", "stopping", "snapshotting", "running", "stopped" ] }, "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", "deny-all", "custom" ] }, "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).", "items": { "type": "string" } }, "allowedCIDRs": { "type": "array", "description": "List of IP address ranges (in CIDR notation) the sandbox is allowed to connect to.", "items": { "type": "string" } }, "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" } }, "injectionRules": { "type": "array", "description": "HTTP header injection rules for outgoing requests matching specific domains.", "items": { "type": "object", "description": "HTTP header injection rules for outgoing requests matching specific domains.", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "The domain (or pattern) that this injection rule applies to. Supports wildcards like *.vercel.com." }, "headerNames": { "type": "array", "description": "The names of HTTP headers that have value that will be injected for requests to this domain.", "items": { "type": "string" } } } } } } }, "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 was soft-blocked for an unhandled reason. 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 ### 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)