Skip to content
Docs

Create a named sandbox

POSThttps://api.vercel.com/v2/sandboxes
Creates a named sandbox environment. Named sandboxes have a unique name within a project and support automatic snapshotting on shutdown.
https://api.vercel.com/v2/sandboxes
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": {
            "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"
                }
              }
            ]
          }
        }
      ]
    },
    "runtime": "node24",
    "architecture": "arm64",
    "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": [],
    "networkId": "example_id",
    "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);
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"
  },
  "session": {
    "abortedAt": "1750344501629",
    "activeCpuDurationMs": "42",
    "architecture": "amd64",
    "createdAt": "1750344501629",
    "cwd": "/vercel/sandbox",
    "duration": "3600000",
    "id": "sbx_123a6c5209bc3778245d011443644c8d27dc2c50",
    "memory": "2048",
    "networkPolicy": {
      "allowedCIDRs": [],
      "allowedDomains": [],
      "deniedCIDRs": [],
      "injectionRules": [
        {
          "domain": "api.vercel.com",
          "headerNames": []
        }
      ],
      "mode": "custom"
    },
    "networkTransfer": {
      "egress": "123",
      "ingress": "123"
    },
    "projectId": "prj_123a6c5209bc3778245d011443644c8d27dc2c50",
    "region": "iad1",
    "requestedAt": "1750344501629",
    "requestedStopAt": "1750344501629",
    "runtime": "node22",
    "snapshottedAt": "1750344501629",
    "sourceSandboxName": "my-sandbox",
    "sourceSnapshotId": "snap_123a6c5209bc3778245d011443644c8d27dc2c50",
    "startedAt": "1750344501629",
    "status": "running",
    "stoppedAt": "1750344501629",
    "timeout": "3600000",
    "updatedAt": "1750344501629",
    "v0": "false",
    "vcpus": "2"
  }
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Query parameters

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
networkPolicyobjectOptional2 variants
runtimestringOptional
The runtime environment for the sandbox. Determines the pre-installed language runtimes and tools available.
architecturestringOptional
CPU architecture. Inherits a snapshot or single image manifest when omitted. Image indexes default to amd64. Must match the source. ARM64 creation requires API v3 or v4 without runtime and team access.
resourcesobjectOptional
Resources to define the VM
sourceobjectOptional3 variants
projectIdstringOptional
The target project slug or ID in which the sandbox will be assigned to.
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.
imagestringOptional
Image to use for the sandbox.
timeoutintegerOptional
Maximum duration in milliseconds that the sandbox can run before being automatically stopped.
envobjectOptional
Default environment variables for the sandbox. These are inherited by all commands unless overridden.
mountsobjectOptional
List of drives to mount to the sandbox at the provided path.
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.
networkIdstringOptional
The Connect network id for the target Secure Compute private network.
namestringOptional
Name for the sandbox. Must be unique per project and URL-safe (alphanumeric, hyphens, underscores).
persistentbooleanOptional
Whether the sandbox persists its state across restarts via automatic snapshots. Defaults to true.
snapshotExpirationobjectOptional2 variants
keepLastSnapshotsobjectOptional
Protect the N most recent snapshots with different expiration/deletion behavior.
tagsobjectOptional
Key-value tags to associate with the sandbox. Maximum 5 tags.

Response

200Success
routesarrayRequired
sandboxobjectRequired
This object contains information related to a Vercel NamedSandbox.
sessionobjectRequired
This object contains information related to a Vercel Sandbox Session. v2 endpoints return "session" instead of "sandbox" as the response wrapper key.

Errors

400One of the provided values in the request body 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