Sign in

v13

OpenAPI 3.0.32026-07-31359869.4 MB
sandboxes

Create a named sandbox

Creates a named sandbox environment. Named sandboxes have a unique name within a project and support automatic snapshotting on shutdown.

post/v2/sandboxes

Query parameters

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.

runtime'node22' | 'node24' | 'node26' | 'python3.13'

The runtime environment for the sandbox. Determines the pre-installed language runtimes and tools available.

projectIdstring

The target project slug or ID in which the sandbox will be assigned to.

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 sandbox. Must be unique per project and URL-safe (alphanumeric, hyphens, underscores).

persistentboolean

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

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
  },
  "runtime": "node24",
  "source": {
    "url": "https://github.com/vercel/next.js.git",
    "depth": 1,
    "revision": "main"
  },
  "projectId": "prj_abc123",
  "timeout": 300000,
  "env": {
    "NODE_ENV": "production",
    "HELLO": "world"
  },
  "name": "my-sandbox",
  "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
    }
  }
}