--- title: "Fork a named sandbox" method: POST path: "/v2/sandboxes/{name}/fork" tags: ["sandboxes"] --- # Fork a named sandbox `POST /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. ## Path parameters - `name` string, required — Name of the source sandbox to fork. ## Query parameters - `projectId` string — The ID of the project the source sandbox belongs to. Required unless authenticating with an OIDC token. - `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. - `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 forked sandbox. Must be unique per project and URL-safe (alphanumeric, hyphens, underscores). A random name is generated when omitted. - `persistent` boolean — Whether the sandbox persists its state across restarts via automatic snapshots. Defaults to the source sandbox setting. - `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. One of the provided values in the request query 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)