---
title: "Create a named sandbox"
method: POST
path: "/v3/sandboxes"
tags: ["sandboxes"]
---

# Create a named sandbox

`POST /v3/sandboxes`

Creates a named sandbox environment. Named sandboxes have a unique name within a project and support automatic snapshotting on shutdown. Unlike v2, this version has no `runtime` parameter: when no `image` is provided (and the sandbox is not restored from a snapshot), the sandbox is created from the default universal image.

## Query parameters

- `teamId` string
- `slug` string

## Request body

- object
  - `networkPolicy` union
    - object — 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.
      - `mode` 'allow-all' | 'deny-all' | 'custom' | 'default-allow' | 'default-deny', required — 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.
      - `allowedDomains` string[] — 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).
      - `allowedCIDRs` string[] — List of IP address ranges (in CIDR notation) the sandbox is allowed to connect to. Traffic to these addresses bypasses domain-based restrictions.
      - `deniedCIDRs` string[] — List of IP address ranges (in CIDR notation) the sandbox is blocked from connecting to. These rules take precedence over all allowed rules.
      - `injectionRules` object[] — HTTP header injection rules for outgoing requests matching specific domains. Traffic to matching domains will be intercepted instead of proxied through encrypted connections.
        - `domain` string, required — The domain (or pattern) of requests to add headers for. Supports wildcards like *.example.com.
        - `headers` object, required — HTTP headers to inject into requests for this domain. Existing headers with the same name will be overridden.
        - `match` object — Optional L7 match. When provided, the injection rule only applies to requests that satisfy every specified dimension. When multiple injection rules target the same domain they are evaluated in order and the first match wins; a rule without `match` matches any request and shadows later rules for the same domain.
          - `path` object — Match on the request path. Comparison is case-sensitive.
            - `exact` string — Match the value exactly. Case-sensitive for paths, header values, and methods; case-insensitive for domains and header keys.
            - `startsWith` string — Match values that start with the given prefix.
          - `method` string[] — HTTP methods to match. Any single match succeeds (OR semantics).
          - `queryString` object[] — Query-string entry matchers. Multiple entries are ANDed. Query parameter names and values are both compared case-sensitively (RFC 3986). When a request has multiple values for the same key, any matching value satisfies the matcher.
            - `key` object — Matcher for the entry key (header name or query key).
              - …
            - `value` object — Matcher for the entry value.
              - …
          - `headers` object[] — Header matchers. Multiple entries are ANDed. Header names are compared case-insensitively (RFC 9110); header values are compared case-sensitively. When a request has multiple values for the same header, any matching value satisfies the matcher.
            - `key` object — Matcher for the entry key (header name or query key).
              - …
            - `value` object — Matcher for the entry value.
              - …
    - object
      - `allow` union
        - string[]
        - object — A rule applied to requests matching a domain in the network policy. Only one of `transform` or `forwardURL` can be specified per rule.
      - `subnets` object
        - `allow` string[]
        - `deny` string[]
  - `resources` object — Resources to define the VM
    - `vcpus` integer — The number of virtual CPUs to allocate to the sandbox. Must be 1, or an even number.
    - `memory` integer — The amount of memory in megabytes to allocate to the sandbox. Must equal vcpus * 2048.
  - `source` union — The source from which to initialize the sandbox filesystem. Can be a Git repository, a tarball URL, or an existing snapshot.
    - object — Clone a Git repository into the sandbox.
      - `type` unknown, required
      - `url` string, uri, required — The URL of the Git repository to clone.
      - `username` string — Username for Git authentication. Required together with password for private repositories.
      - `password` string — Password or personal access token for Git authentication. Required together with username for private repositories.
      - `depth` integer — Create a shallow clone with history truncated to the specified number of commits. Useful for faster cloning of large repositories.
      - `revision` string — The specific commit SHA, branch name, or tag to checkout after cloning.
    - object — Download and extract a gzipped tarball into the sandbox.
      - `type` unknown, required
      - `url` string, uri, required — URL of a gzipped tarball (.tar.gz) to download and extract.
    - object — Restore the sandbox filesystem from an existing snapshot.
      - `type` unknown, required
      - `snapshotId` string, required — The unique identifier of the snapshot to restore.
  - `projectId` string — The target project slug or ID in which the sandbox will be assigned to.
  - `image` string — Image to use for the sandbox.
  - `timeout` integer — Maximum duration in milliseconds that the sandbox can run before being automatically stopped.
  - `env` object — Default environment variables for the sandbox. These are inherited by all commands unless overridden.
  - `mounts` object — List of drives to mount to the sandbox at the provided path.
  - `name` string — Name for the sandbox. Must be unique per project and URL-safe (alphanumeric, hyphens, underscores).
  - `persistent` boolean — Whether the sandbox persists its state across restarts via automatic snapshots. Defaults to true.
  - `snapshotExpiration` union — Default snapshot expiration time in milliseconds. Set to 0 to disable expiration. When set, this value is used as the default expiration for all snapshots created for this sandbox.
    - unknown
    - integer
  - `keepLastSnapshots` object — Protect the N most recent snapshots with different expiration/deletion behavior.
    - `count` integer, required — Number of most recent snapshots to keep.
    - `expiration` union — Expiration time in milliseconds for kept snapshots. Falls back to snapshotExpiration.
      - unknown
      - integer
    - `deleteEvicted` boolean — Whether to immediately delete evicted snapshots. Defaults to true.
  - `tags` object — Key-value tags to associate with the sandbox. Maximum 5 tags.

## Response `200`

- object
  - `sandbox` NamedSandbox, required — This object contains information related to a Vercel NamedSandbox.
    - `name` string, required — The unique identifier of the sandbox.
    - `currentSnapshotId` string — Current snapshot ID that the named sandbox is pointing to.
    - `currentSessionId` string, required — Current session ID the sandbox is pointing to.
    - `status` 'running' | 'stopped' | 'stopping', required — The status of the current sandbox.
    - `statusUpdatedAt` number, required — The time when the sandbox status was last updated, in milliseconds since the epoch.
    - `persistent` false | true, required — Whether the sandbox persists its state across restarts via automatic snapshots.
    - `region` string — The region the sandbox is configured to run in: the region set on the sandbox, otherwise the project-level default, then the platform default. Where a running session actually landed is reported by `session.region`.
    - `vcpus` number — Number of virtual CPUs allocated.
    - `memory` number — Memory allocated in MB.
    - `runtime` string — Runtime identifier.
    - `image` string — Digest-pinned reference of the container image the sandbox was created from, when it was created from an image ("{repository}@{manifestDigest}").
    - `timeout` number — Timeout in milliseconds.
    - `snapshotExpiration` number — Default snapshot expiration time in milliseconds. 0 means no expiration.
    - `keepLastSnapshots` object — Keep-last snapshot configuration.
      - `count` number, required — Number of most recent snapshots to keep.
      - `expiration` number — Expiration time in milliseconds for kept snapshots.
      - `deleteEvicted` false | true, required — Whether to immediately delete evicted snapshots.
    - `networkPolicy` object — Network policy configuration.
      - `mode` 'allow-all' | 'custom' | 'default-allow' | 'default-deny' | 'deny-all', required
      - `allowedDomains` string[]
      - `allowedCIDRs` string[]
      - `deniedCIDRs` string[]
    - `totalEgressBytes` number — Cumulative egress bytes across all sandbox runs.
    - `totalIngressBytes` number — Cumulative ingress bytes across all sandbox runs.
    - `totalActiveCpuDurationMs` number — Cumulative active CPU duration in milliseconds across all sandbox runs.
    - `totalDurationMs` number — Cumulative wall-clock duration in milliseconds across all sandbox runs.
    - `cwd` string — The working directory of the sandbox.
    - `tags` object — Key-value tags attached to the named sandbox.
    - `mounts` object — Key-value pairs of mount path and drive.
    - `createdAt` number, required — The time when the named sandbox was created, in milliseconds since the epoch.
    - `updatedAt` number, required — The time when the named sandbox was last updated, in milliseconds since the epoch.
    - `expiresAt` number — The time at which the currently running sandbox will time out, in milliseconds since the epoch. Only present while a session is running.
  - `session` Session, required — This object contains information related to a Vercel Sandbox Session. v2 endpoints return "session" instead of "sandbox" as the response wrapper key.
    - `sourceSandboxName` string, required — The name of the source sandbox.
    - `projectId` string, required — The unique identifier of the project associated with this session.
    - `id` string, required — The unique identifier of the sandbox.
    - `memory` number, required — Memory allocated to this sandbox in MB.
    - `vcpus` number, required — Number of vCPUs allocated to this sandbox.
    - `region` string, required — The region where the sandbox is hosted.
    - `runtime` string, required — The runtime of the sandbox.
    - `timeout` number, required — The maximum amount of time the sandbox will run for in milliseconds.
    - `status` 'aborted' | 'failed' | 'pending' | 'running' | 'snapshotting' | 'stopped' | 'stopping', required — The status of the sandbox.
    - `requestedAt` number, required — The time when the sandbox was requested, in milliseconds since the epoch.
    - `startedAt` number — The time when the sandbox was started, in milliseconds since the epoch.
    - `cwd` string, required — The working directory of the sandbox.
    - `requestedStopAt` number — The time when the sandbox was requested to stop, in milliseconds since the epoch.
    - `stoppedAt` number — The time when the sandbox was stopped, in milliseconds since the epoch.
    - `abortedAt` number — The time when the sandbox was aborted, in milliseconds since the epoch.
    - `duration` number — The duration of the sandbox in milliseconds.
    - `sourceSnapshotId` string — The unique identifier of the snapshot associated with this sandbox, if any.
    - `snapshottedAt` number — The time when a snapshot was requested, in milliseconds since the epoch.
    - `createdAt` number, required — The time when the sandbox was created, in milliseconds since the epoch.
    - `updatedAt` number, required — The last time the sandbox was updated, in milliseconds since the epoch.
    - `networkPolicy` SandboxNetworkPolicy — The network policy applied to this sandbox, if any.
      - `mode` 'allow-all' | 'custom' | 'deny-all', required — 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.
      - `allowedDomains` string[] — List of domain names the sandbox is allowed to connect to. Supports wildcard patterns (e.g., "*.vercel.com" matches all subdomains).
      - `allowedCIDRs` string[] — List of IP address ranges (in CIDR notation) the sandbox is allowed to connect to.
      - `deniedCIDRs` string[] — List of IP address ranges (in CIDR notation) the sandbox is blocked from connecting to. These rules take precedence over all allowed rules.
      - `injectionRules` SandboxInjectionRule[] — HTTP header injection rules for outgoing requests matching specific domains.
        - `domain` string, required — The domain (or pattern) that this injection rule applies to. Supports wildcards like *.vercel.com.
        - `headerNames` string[] — The names of HTTP headers that have value that will be injected for requests to this domain.
    - `activeCpuDurationMs` number — 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` object — 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.
      - `ingress` number, required
      - `egress` number, required
  - `routes` SandboxPublicRoute[], required
    - `url` string, required — A public URL to access the corresponding port in the Sandbox.
    - `port` number, required — The user port number that the route is mapped to.
    - `subdomain` string, required — The subdomain assigned to this route.
    - `system` true — Whether the route is reserved by the system (e.g. for internal use).

## Other responses

- `400` — One of the provided values in the request body is invalid.
- `401` — The request is not authorized.
- `402` — The account is missing a payment so payment method must be updated
- `403` — You do not have permission to access this resource.
- `404`
- `409`
- `410`
- `422`
- `429` — The concurrency limit has been exceeded.
- `500`

---

[API](https://skmtc.net/vercel/apis/api.md) · [All operations](https://skmtc.net/vercel/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vercel/api/versions/61d1ba3f6dac/schema)