Sign in

v13

latestOpenAPI 3.0.32026-07-31359869.4 MB
sandboxes

Fork a named sandbox

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.

post/v2/sandboxes/{name}/fork

Path parameters

namestring required

Name of the source sandbox to fork.

Name of the source sandbox to fork.

Query parameters

projectIdstring

The ID of the project the source sandbox belongs to. Required unless authenticating with an OIDC token.

The ID of the project the source sandbox belongs to. Required unless authenticating with an OIDC token.

teamIdstring
Example:team_1a2b3c4d5e6f7g8h9i0j1k2l

The Team identifier to perform the request on behalf of.

slugstring
Example:my-team-url-slug

The Team slug to perform the request on behalf of.

Request body

imagestring

Image to use for the sandbox.

timeoutinteger

Maximum duration in milliseconds that the sandbox can run before being automatically stopped.

envobject

Default environment variables for the sandbox. These are inherited by all commands unless overridden.

mountsobject

List of drives to mount to the sandbox at the provided path.

namestring

Name for the forked sandbox. Must be unique per project and URL-safe (alphanumeric, hyphens, underscores). A random name is generated when omitted.

persistentboolean

Whether the sandbox persists its state across restarts via automatic snapshots. Defaults to the source sandbox setting.

tagsobject

Key-value tags to associate with the sandbox. Maximum 5 tags.

Example request

{
  "networkPolicy": {
    "mode": "custom",
    "allowedDomains": [
      "api.github.com",
      "*.npmjs.org"
    ],
    "allowedCIDRs": [
      "35.192.0.0/12",
      "104.16.0.0/12"
    ],
    "deniedCIDRs": [
      "35.192.0.0/12"
    ]
  },
  "resources": {
    "vcpus": 2,
    "memory": 4096
  },
  "timeout": 300000,
  "env": {
    "NODE_ENV": "production",
    "HELLO": "world"
  },
  "name": "my-sandbox-fork",
  "tags": {
    "env": "staging",
    "team": "platform"
  }
}

Response

Example response

{
  "sandbox": {
    "name": "my-sandbox",
    "status": "running",
    "statusUpdatedAt": 1750344501629,
    "persistent": true,
    "region": "iad1",
    "vcpus": 2,
    "memory": 1024,
    "runtime": "node22",
    "image": "my-repo@sha256:2c4e8f9a1b3d5e7f091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708",
    "timeout": 300000,
    "snapshotExpiration": 604800000,
    "keepLastSnapshots": {
      "count": 5,
      "expiration": 604800000,
      "deleteEvicted": true
    },
    "totalEgressBytes": 4096,
    "totalIngressBytes": 2048,
    "totalActiveCpuDurationMs": 5000,
    "totalDurationMs": 60000,
    "cwd": "/vercel/sandbox",
    "tags": {
      "team": "hive",
      "user": "bob"
    },
    "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": [
        "api.vercel.com",
        "*.example.com"
      ],
      "allowedCIDRs": [
        "10.0.0.0/8"
      ],
      "deniedCIDRs": [
        "10.0.0.0/8"
      ],
      "injectionRules": [
        {
          "domain": "api.vercel.com",
          "headerNames": [
            "Authorization",
            "X-API-Key"
          ]
        }
      ]
    },
    "activeCpuDurationMs": 42,
    "networkTransfer": {
      "in": 12543852,
      "out": 15368
    }
  }
}