> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create sandbox (v2)

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

Anona: `size` (`small`, `medium`, `large` or `xl`) sets the sandbox's vCPU, memory and disk; an E2B SDK can send it as metadata `anona.size` instead. Without it the sandbox runs at its template's own size, or on Free at the smallest size the template allows (Small for `base`). A size below the template's minimum is `400` `sandbox_size_not_available`, and one above your plan's largest size is `403` `plan_limit_exceeded`; the first sandbox at a size the template was not built at may get `503` `sandbox_size_preparing` with `Retry-After` while that size is prepared (see Sandbox sizes). Over a plan limit on what runs at once (sandboxes, vCPU, or sandboxes at the largest size) is `429` `plan_limit_exceeded` with `limit_name`, `limit`, `current` and `plan`. `timeout` also accepts `-1` for no deadline. `lifecycle.onTimeout: pause` (sent by the SDK as `autoPause`) pauses instead of deleting. A sandbox without a deadline reports `endAt` `9999-12-31T23:59:59Z`. `network.egressProxy`, `volumeMounts`, `iam` and `autoPauseMemory: false` are refused with 400, and the `Idempotency-Key` header is not supported.



## OpenAPI

````yaml /api-reference/e2b-openapi.yaml post /v2/sandboxes
openapi: 3.0.0
info:
  title: Anona Compute API (E2B-compatible routes)
  version: 0.1.0
  description: >-
    The E2B-compatible API operations the Anona Compute gateway serves, for use
    with the E2B SDK.
servers:
  - url: https://api.compute.anonalabs.com
security: []
tags:
  - name: sandboxes
paths:
  /v2/sandboxes:
    post:
      tags:
        - sandboxes
      summary: Create sandbox (v2)
      description: >-
        Create a sandbox from the template. All system communication with the
        sandbox is secured.


        Anona: `size` (`small`, `medium`, `large` or `xl`) sets the sandbox's
        vCPU, memory and disk; an E2B SDK can send it as metadata `anona.size`
        instead. Without it the sandbox runs at its template's own size, or on
        Free at the smallest size the template allows (Small for `base`). A size
        below the template's minimum is `400` `sandbox_size_not_available`, and
        one above your plan's largest size is `403` `plan_limit_exceeded`; the
        first sandbox at a size the template was not built at may get `503`
        `sandbox_size_preparing` with `Retry-After` while that size is prepared
        (see Sandbox sizes). Over a plan limit on what runs at once (sandboxes,
        vCPU, or sandboxes at the largest size) is `429` `plan_limit_exceeded`
        with `limit_name`, `limit`, `current` and `plan`. `timeout` also accepts
        `-1` for no deadline. `lifecycle.onTimeout: pause` (sent by the SDK as
        `autoPause`) pauses instead of deleting. A sandbox without a deadline
        reports `endAt` `9999-12-31T23:59:59Z`. `network.egressProxy`,
        `volumeMounts`, `iam` and `autoPauseMemory: false` are refused with 400,
        and the `Idempotency-Key` header is not supported.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewSandboxV2'
      responses:
        '201':
          description: The sandbox was created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '400':
          description: Bad request
          headers:
            Should-Retry:
              $ref: '#/components/headers/ShouldRetry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/401'
        '402':
          description: >-
            The credit is spent (error_code `credit_exhausted`); top up or
            change plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          headers:
            Should-Retry:
              $ref: '#/components/headers/ShouldRetry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          headers:
            Should-Retry:
              $ref: '#/components/headers/ShouldRetry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            The sandbox is in the wrong state, or the template exists but cannot
            start a sandbox (error_code `template_not_ready`; retrying does not
            help until it is rebuilt)
          headers:
            Should-Retry:
              $ref: '#/components/headers/ShouldRetry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
          headers:
            Should-Retry:
              $ref: '#/components/headers/ShouldRetry'
            Retry-After:
              description: >-
                When present, the number of seconds to wait before retrying the
                request.
              required: false
              schema:
                type: integer
                minimum: 0
              example: 30
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          headers:
            Should-Retry:
              $ref: '#/components/headers/ShouldRetry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service unavailable
          headers:
            Should-Retry:
              $ref: '#/components/headers/ShouldRetry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: Backend timeout
          headers:
            Should-Retry:
              $ref: '#/components/headers/ShouldRetry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    NewSandboxV2:
      description: >-
        Sandbox creation request. All system communication with the sandbox is
        always secured; the template's envd version must support secured access.
      required:
        - templateID
      properties:
        templateID:
          type: string
          description: Identifier of the required template
        timeout:
          type: integer
          format: int32
          minimum: 1
          default: 300
          description: Time to live for the sandbox in seconds.
        autoPause:
          type: boolean
          default: false
          description: Automatically pauses the sandbox after the timeout
        autoPauseMemory:
          type: boolean
          default: true
          description: >-
            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:
          $ref: '#/components/schemas/SandboxAutoResumeConfig'
        allow_internet_access:
          type: boolean
          description: >-
            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:
          $ref: '#/components/schemas/SandboxNetworkConfig'
        metadata:
          $ref: '#/components/schemas/SandboxMetadata'
        envVars:
          $ref: '#/components/schemas/EnvVars'
        mcp:
          $ref: '#/components/schemas/Mcp'
        iam:
          $ref: '#/components/schemas/SandboxIam'
        volumeMounts:
          type: array
          items:
            $ref: '#/components/schemas/SandboxVolumeMount'
        size:
          type: string
          enum:
            - small
            - medium
            - large
            - xl
          description: >-
            Anona extension: the sandbox size (vCPU, memory and disk). Absent:
            the template's own size.
    Sandbox:
      required:
        - templateID
        - sandboxID
        - clientID
        - envdVersion
      properties:
        templateID:
          type: string
          description: Identifier of the template from which is the sandbox created
        sandboxID:
          type: string
          description: Identifier of the sandbox
        alias:
          type: string
          description: Alias of the template
        clientID:
          type: string
          deprecated: true
          description: Identifier of the client
        envdVersion:
          $ref: '#/components/schemas/EnvdVersion'
        envdAccessToken:
          type: string
          description: Access token used for envd communication
        trafficAccessToken:
          type: string
          nullable: true
          description: Token required for accessing sandbox via proxy.
        domain:
          type: string
          nullable: true
          description: Base domain where the sandbox traffic is accessible
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        error_code:
          type: string
          description: >-
            Machine-readable error code. Not a closed set; the gateway sends
            plan_limit_exceeded (a plan limit; the body also has limit_name,
            limit, current and plan), rate_limited (a rate limit, with
            Retry-After), sandbox_quota_exceeded (a platform cap that is not a
            plan limit: fork checkpoints, builds in progress), credit_exhausted
            (the credit is spent), sandbox_snapshot_storage_full (pause and fork
            cannot store a snapshot; retrying does not help),
            template_not_found, template_not_ready (the template exists but
            cannot start a sandbox), sandbox_capacity_unavailable,
            sandbox_engine_starting and sandbox_engine_unavailable (retry after
            Retry-After), sandbox_create_failed (retry), sandbox_create_refused,
            invalid_request and internal_server_error.
        message:
          type: string
          description: Error
    SandboxAutoResumeConfig:
      type: object
      description: Auto-resume configuration for paused sandboxes.
      required:
        - enabled
      properties:
        enabled:
          $ref: '#/components/schemas/SandboxAutoResumeEnabled'
    SandboxNetworkConfig:
      type: object
      properties:
        allowPublicTraffic:
          type: boolean
          nullable: true
          description: >-
            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:
          type: array
          description: >-
            Destinations to allow: IPv4 addresses, CIDR blocks (e.g.
            "203.0.113.0/24") and exact host names (e.g. "api.example.com").
            Allowed entries take precedence over denied entries. Anona: a host
            name needs public egress off (`allow_internet_access: false`, or
            `0.0.0.0/0` in `denyOut`). Wildcard names such as `*.example.com`
            are refused with 400 (wildcard host names are not supported yet;
            name exact hosts), and so are names that do not resolve yet and
            destinations in private or reserved ranges, including names that
            resolve into them. The sandbox's DNS resolvers, 1.1.1.1 and 1.0.0.1,
            are always allowed.
          items:
            type: string
        denyOut:
          type: array
          description: >-
            List of denied CIDR blocks or IP addresses for egress traffic.
            Domain names are not supported for deny rules.
          items:
            type: string
        dnsServers:
          type: array
          maxItems: 10
          description: >-
            Anona: sandboxes resolve names through 1.1.1.1 and 1.0.0.1, which
            are always allowed, and this field does not change that or the
            sandbox's /etc/resolv.conf. Any other IPv4 address listed here is
            added to the allowed destinations when `allowOut` has a host name
            and public egress is off; otherwise it is accepted and has no
            effect. The free plan accepts only 1.1.1.1 and 1.0.0.1, and an
            address in a reserved range is refused with 400.
          items:
            type: string
        egressProxy:
          type: object
          nullable: true
          description: >-
            Not supported on Anona. Any value other than `null` is refused with
            400 (`SOCKS5 egress proxies are not supported`), on create and on
            update.
        maskRequestHost:
          type: string
          description: Specify host mask which will be used for all sandbox requests
        httpsPorts:
          type: array
          description: >-
            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.
          maxItems: 128
          uniqueItems: true
          items:
            type: integer
            format: uint32
            minimum: 1
            maximum: 65535
        rules:
          type: object
          description: >-
            Per-host header rules for the sandbox's outbound HTTPS requests.
            Anona: each key is one exact host name, normalized to lowercase. A
            wildcard key such as `*.example.com` is refused with 400 (`a
            wildcard is not allowed here; name the exact host`), and so is an IP
            address. Rules apply to HTTPS only. A rule does not allow the host
            on its own: with public egress off, list the host in `allowOut` too,
            or the rule is dropped with a warning. The host must be on the
            secret's allowed hosts (403 otherwise), and a rule that needs a new
            credential binding needs a caller who may create one (403
            otherwise); see Networking.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/SandboxNetworkRule'
    SandboxMetadata:
      additionalProperties:
        type: string
        description: Metadata of the sandbox
    EnvVars:
      additionalProperties:
        type: string
        description: Environment variables for the sandbox
    Mcp:
      type: object
      description: MCP configuration for the sandbox
      additionalProperties: {}
      nullable: true
    SandboxIam:
      type: object
      description: >-
        Sandbox workload identity configuration. A non-empty, valid tokens map
        enables workload identity for the sandbox.
      properties:
        tokens:
          $ref: '#/components/schemas/SandboxIamTokens'
    SandboxVolumeMount:
      type: object
      properties:
        name:
          type: string
          description: Name of the volume
        path:
          type: string
          description: Path of the volume
      required:
        - name
        - path
    EnvdVersion:
      type: string
      description: Version of the envd running in the sandbox
    SandboxAutoResumeEnabled:
      type: boolean
      description: Auto-resume enabled flag for paused sandboxes. Default false.
      default: false
    SandboxNetworkRule:
      type: object
      description: Transform rule applied to egress requests matching a domain pattern.
      properties:
        transform:
          $ref: '#/components/schemas/SandboxNetworkTransform'
    SandboxIamTokens:
      type: object
      description: Named workload-token definitions, keyed by a caller-chosen token name.
      additionalProperties:
        $ref: '#/components/schemas/SandboxIamToken'
    SandboxNetworkTransform:
      type: object
      description: Transformations applied to matching egress requests before forwarding.
      properties:
        headers:
          type: object
          description: >-
            HTTP headers to set on matching requests; an existing header with
            the same name is replaced. Anona: every value must be one credential
            vault placeholder, `${vault.<name>}`, optionally after `Bearer ` or
            `Basic `. The egress proxy fills it in on the way out, and the
            sandbox never sees the value. A literal value is refused with 400
            (`value must be ${vault.<name>}, optionally prefixed by "Bearer " or
            "Basic "; literal values are not accepted`), as is a value with more
            than one placeholder and an empty `headers` object
            (`transform.headers: empty`). `Host`, `Content-Length`,
            `Transfer-Encoding`, `Connection`, `Upgrade`, `TE`, `Trailer`,
            `Keep-Alive` and `Proxy-*` headers cannot be set.
          additionalProperties:
            type: string
    SandboxIamToken:
      type: object
      required:
        - audience
        - tokenType
      properties:
        audience:
          type: string
          description: Audience of the workload token, stored exactly as provided.
        tokenType:
          type: string
          description: Workload token type.
  headers:
    ShouldRetry:
      description: >
        Whether the condition behind this error may clear, so that retrying the
        request could

        succeed. true marks a transient failure such as missing capacity, a rate
        limit, or a

        creation still in progress: retry after Retry-After when present,
        otherwise with

        exponential backoff. false marks a failure a retry cannot fix, such as a
        malformed request

        or a configuration fault, or an outcome that is unknown, where a retry
        could create a

        second sandbox. Successful responses and errors without an explicit
        classification omit

        the header.
      required: false
      schema:
        type: boolean
  responses:
    '401':
      description: Authentication error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.