Skip to content
Docs

Fork a named sandbox

POSThttps://api.vercel.com/v2/sandboxes/{name}/fork
Forks a named sandbox, creating a new named sandbox from the source's configuration. Resources, timeout, ports, tags, network policy, mounts, Connect network, image, persistence, snapshot settings and — unlike the SDK-side fork — environment variables are copied from the source automatically (interactive is not). When the source has a snapshot the fork starts from it; otherwise it starts from the source's runtime/image. Any field provided in the request body overrides the value copied from the source.
https://api.vercel.com/v2/sandboxes/{name}/fork
const response = await fetch('https://api.vercel.com/v2/sandboxes/name/fork?projectId=string&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"
                }
              }
            ]
          }
        }
      ]
    },
    "resources": {
      "vcpus": "2",
      "memory": "4096"
    },
    "ports": [],
    "image": "string",
    "timeout": "300000",
    "env": "[object Object]",
    "mounts": "value",
    "region": "iad1",
    "failoverRegions": [],
    "networkId": "example_id",
    "name": "my-sandbox-fork",
    "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

Path parameters

namestringRequired
Name of the source sandbox to fork.

Query parameters

projectIdstringOptional
The ID of the project the source sandbox belongs to. Required unless authenticating with an OIDC token.
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
resourcesobjectOptional
Resources to define the VM
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 forked sandbox. Must be unique per project and URL-safe (alphanumeric, hyphens, underscores). A random name is generated when omitted.
persistentbooleanOptional
Whether the sandbox persists its state across restarts via automatic snapshots. Defaults to the source sandbox setting.
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. 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
503Error