---
title: "Create sandbox (v2)"
method: POST
path: "/v2/sandboxes"
tags: ["sandboxes"]
---

# Create sandbox (v2)

`POST /v2/sandboxes`

## Request

- Base URL: `https://api.e2b.app`
- URL: `https://api.e2b.app/v2/sandboxes`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer and API key in header `X-Team-ID`
  - API key in header `X-Admin-Token` and API key in header `X-Team-ID`
  - HTTP bearer and API key in header `X-Team-ID`

Create a sandbox from the template. All system communication with the sandbox is secured.

## Headers

- `Idempotency-Key` string

## Request body

- NewSandboxV2: Sandbox creation request. All system communication with the sandbox is always secured; the template's envd version must support secured access.
  - `templateID` string, required: Identifier of the required template
  - `timeout` integer: Time to live for the sandbox in seconds.
  - `autoPause` boolean: Automatically pauses the sandbox after the timeout
  - `autoPauseMemory` boolean: Controls the snapshot kind taken when the sandbox auto-pauses on timeout (only relevant when autoPause is true). When false, the auto-pause drops the in-memory state and persists only the filesystem (a filesystem-only snapshot); resuming it cold-boots (reboots) the sandbox from disk. Such a snapshot cannot be auto-resumed by traffic and must be resumed explicitly, so it cannot be combined with autoResume. Defaults to true (full memory snapshot).
  - `autoResume` SandboxAutoResumeConfig: Auto-resume configuration for paused sandboxes.
    - `enabled` boolean, required: Auto-resume enabled flag for paused sandboxes. Default false.
  - `allow_internet_access` boolean: Allow sandbox to access the internet. When set to false, it behaves the same as specifying denyOut to 0.0.0.0/0 in the network config.
  - `network` SandboxNetworkConfig
    - `allowPublicTraffic` boolean, nullable: Whether sandbox URLs accept traffic without the sandbox's traffic access token. When omitted or null on create, the project's default applies, which is true unless the project changed it.
    - `allowOut` string[]: List of allowed destinations for egress traffic. Each entry can be a CIDR block (e.g. "8.8.8.8/32"), a bare IP address (e.g. "8.8.8.8"), or a domain name (e.g. "example.com", "*.example.com"). Allowed entries always take precedence over denied entries. When allowOut contains a domain, the servers in dnsServers (8.8.8.8 by default) are also allowed.
    - `denyOut` string[]: List of denied CIDR blocks or IP addresses for egress traffic. Domain names are not supported for deny rules.
    - `dnsServers` string[]: DNS servers the sandbox can reach when allowOut contains a domain. Each entry must be an IPv4 address, and all traffic to it is allowed. Omit it to allow the default nameserver 8.8.8.8, or pass an empty list to allow none. This does not change the sandbox's /etc/resolv.conf.
    - `egressProxy` SandboxEgressProxyConfig, nullable: SOCKS5 proxy for sandbox egress. Outbound TCP is tunneled through the proxy after allow/deny filtering; the sandbox is unaware. Domain-matched flows use remote DNS (ATYP=domain).
      - `address` string, required: SOCKS5 proxy address in host:port format (e.g. "proxy.example.com:1080").
      - `username` string: Optional SOCKS5 username (RFC 1929), max 255 bytes.
      - `password` string: Optional SOCKS5 password (RFC 1929), max 255 bytes.
      - `tls` SandboxEgressProxyTLSConfig, nullable: TLS for the connection to the SOCKS5 proxy. The SOCKS5 negotiation and the tunneled traffic both run inside the TLS session, so the proxy credentials are not sent in the clear. This secures only the hop to the proxy; what the proxy does onward is its own concern. A half-close from the sandbox reaches the proxy as a TLS close_notify, not a TCP FIN, and a proxy that treats close_notify as a full close cuts the reply short.
        - `enabled` boolean, required: Connect to the proxy over TLS. When false, no other field in this object may be set.
        - `serverName` string: Name to verify the proxy certificate against, and to send as SNI. Defaults to the host part of address. Set this only when the certificate does not match the address the proxy is reached at.
        - `caCert` string: One or more PEM-encoded certificates to verify the proxy against, for a proxy fronted by a private CA. These replace the system trust store, which is what is used when this is omitted. The system trust store depends on the host the orchestrator runs on, so set this to get the same verification everywhere.
    - `maskRequestHost` string: Specify host mask which will be used for all sandbox requests
    - `httpsPorts` integer[]: Sandbox ports that serve HTTPS rather than plaintext HTTP. Affects how the proxy reaches the service inside the sandbox; the public URL is HTTPS either way. Certificates are not verified, so self-signed ones work. The envd port (49983) cannot be listed.
    - `rules` object: Per-domain transform rules applied to matching outbound HTTPS requests. Keys may be exact DNS names (for example, "api.example.com") or a leading wildcard (for example, "*.example.com"), and are normalized to lowercase on write. Wildcards match subdomains at any depth but not the apex domain; a bare "*" is invalid. Exact rules take precedence, followed by the longest matching wildcard suffix, and matching rule sets are not merged. Broad wildcards such as "*.com" are allowed and may expose transformed credentials to every matching destination the sandbox contacts. Rules do not grant network access; configure allowOut separately to permit the destination.
  - `metadata` unknown
  - `envVars` unknown
  - `mcp` Mcp, nullable: MCP configuration for the sandbox
  - `iam` SandboxIam: Sandbox workload identity configuration. A non-empty, valid tokens map enables workload identity for the sandbox.
    - `tokens` SandboxIamTokens: Named workload-token definitions, keyed by a caller-chosen token name.
  - `volumeMounts` SandboxVolumeMount[]
    - `name` string, required: Name of the volume
    - `path` string, required: Path of the volume

## Response `201`

The sandbox was created successfully

- Sandbox
  - `templateID` string, required: Identifier of the template from which is the sandbox created
  - `sandboxID` string, required: Identifier of the sandbox
  - `alias` string: Alias of the template
  - `clientID` string, required: Identifier of the client
  - `envdVersion` string, required: Version of the envd running in the sandbox
  - `envdAccessToken` string: Access token used for envd communication
  - `trafficAccessToken` string, nullable: Token required for accessing sandbox via proxy.
  - `domain` string, nullable: Base domain where the sandbox traffic is accessible

## Other responses

- `400`: Bad request
- `401`: Authentication error
- `403`: Forbidden
- `404`: Not found
- `409`: The Idempotency-Key conflicts with a different request (error_code idempotency_request_mismatch), or the matching original request has no recorded response yet and is within its expected response window (error_code idempotency_in_progress); this request was not executed again
- `422`: The matching original request has no recorded response and its expected response deadline has passed or is unknown (error_code idempotency_outcome_unknown); this request was not executed again
- `429`: Too many requests
- `500`: Server error
- `503`: Service unavailable
- `504`: Backend timeout

## Changes

- **2026-10-26** `99fccbc60e6d`: 2 info
  - the request property `network/allowPublicTraffic` became nullable
  - the `allowPublicTraffic` request property default value `true` was removed
- **2026-10-22** `04ec8eabc7f9`: 6 info
  - added the new optional `header` request parameter `Idempotency-Key`
  - added the new optional request property `network/dnsServers`
  - added the non-success response with the status `403`
  - added the non-success response with the status `404`
  - …2 more
- **2026-10-20** `861cbb1d47a7`: 1 info
  - added the new optional request property `network/egressProxy/tls`
- **2026-09-18** `0fb774ca41bf`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/e2b-dev/apis/e2b-api/changes/v2/sandboxes/post.md)

---

[API](https://skmtc.dev/e2b-dev/apis/e2b-api.md) - [All operations](https://skmtc.dev/e2b-dev/apis/e2b-api/llms.txt) - [OpenAPI document](https://skmtc.dev/e2b-dev/apis/e2b-api/revisions/99fccbc60e6d?raw)