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

# Create Sandbox Gang Endpoint

> Create a gang of sandboxes scheduled together on one node.

All or nothing: if any member is rejected, members already created are
terminated. Members boot independently; poll each one for RUNNING.



## OpenAPI

````yaml https://api.primeintellect.ai/api/v1/sandbox/openapi.json post /api/v1/sandbox/gang
openapi: 3.1.0
info:
  title: PI API
  version: 0.1.0
servers:
  - url: https://api.primeintellect.ai
security: []
paths:
  /api/v1/sandbox/gang:
    post:
      tags:
        - Sandbox
      summary: Create Sandbox Gang Endpoint
      description: |-
        Create a gang of sandboxes scheduled together on one node.

        All or nothing: if any member is rejected, members already created are
        terminated. Members boot independently; poll each one for RUNNING.
      operationId: create_sandbox_gang_endpoint_api_v1_sandbox_gang_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxGangRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxGangResponse'
        '401':
          description: Authorization failed
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    CreateSandboxGangRequest:
      properties:
        sandboxes:
          items:
            $ref: '#/components/schemas/CreateSandboxRequest'
          type: array
          maxItems: 12
          minItems: 1
          title: Sandboxes
          description: >-
            Sandboxes placed and started together on one node as one unit. All
            must share team, architecture, and GPU type. Totals are capped at 48
            CPU cores, 48 GB memory, 1000 GB disk, and 8 GPUs.
        idempotency_key:
          anyOf:
            - type: string
              maxLength: 120
              minLength: 1
            - type: 'null'
          title: Idempotency Key
          description: Client-generated key used to deduplicate retried gang creates.
      type: object
      required:
        - sandboxes
      title: CreateSandboxGangRequest
    SandboxGangResponse:
      properties:
        gang_id:
          type: string
          title: Gang Id
        sandboxes:
          items:
            $ref: '#/components/schemas/SandboxResponse'
          type: array
          title: Sandboxes
      type: object
      required:
        - gang_id
        - sandboxes
      title: SandboxGangResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateSandboxRequest:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: Sandbox name
        docker_image:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Docker Image
          description: Docker image to run. Required unless checkpoint_id is set.
        checkpoint_id:
          anyOf:
            - type: string
              maxLength: 64
              minLength: 1
            - type: 'null'
          title: Checkpoint Id
          description: >-
            Restore a checkpoint instead of booting an image. The sandbox takes
            the checkpoint's image and disk size, so docker_image and
            disk_size_gb must be omitted. The sandbox cold boots from the
            checkpoint's stored (DURABLE) disk; a checkpoint taken by pause can
            also restore memory, see restore_memory. Repeat to fork again. A
            checkpoint holds only the root disk, so no volume is mounted unless
            volumes is set. Only within the owning team or account.
        restore_memory:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Restore Memory
          description: >-
            With checkpoint_id: true restores the checkpoint's memory, so the
            new sandbox continues from the paused state with the paused shape
            (409 if it has none). Omitted or false cold boots from its disk. A
            memory fork is an exact copy of the paused guest: the kernel RNG is
            reseeded, but random generators seeded in userspace (OpenSSL,
            language runtimes) and keys, tokens, or IDs already in memory are
            the same in every fork. Rekey or regenerate them in the workload.
        arch:
          type: string
          enum:
            - amd64
            - arm64
          title: Arch
          default: amd64
        start_command:
          anyOf:
            - $ref: '#/components/schemas/StartCommand'
            - type: string
            - type: 'null'
          title: Start Command
          description: Process to start without invoking a shell
        cpu_cores:
          type: integer
          maximum: 48
          minimum: 1
          title: Cpu Cores
          description: Whole vCPUs required
          default: 1
        memory_gb:
          type: number
          maximum: 128
          minimum: 0.1
          title: Memory Gb
          description: Memory in GB
          default: 1
        disk_size_gb:
          anyOf:
            - type: number
              maximum: 1000
              minimum: 0.1
            - type: 'null'
          title: Disk Size Gb
          description: Disk size in GB. Defaults to 32.
        gpu_count:
          type: integer
          maximum: 8
          minimum: 0
          title: Gpu Count
          description: Number of GPUs
          default: 0
        gpu_type:
          anyOf:
            - $ref: '#/components/schemas/GPUType'
            - type: 'null'
          description: GPU type (e.g. H100, A100). Required when gpu_count > 0
        vm:
          type: boolean
          title: Vm
          description: >-
            Sandbox runtime selector. VM is the only supported runtime: omit to
            use a VM. An explicit false is rejected with HTTP 410; the container
            runtime is retired. VM is required when requesting GPUs.
          default: true
        network_allowlist:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Network Allowlist
          description: >-
            VM only. Allow egress only to these domains/IPv4 CIDRs
            (hostname-aware; empty list denies all). Mutually exclusive with
            network_denylist. Entries may end in :port or :low-high (domains:
            :80 or :443 only) to match only those destination ports.
        network_denylist:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Network Denylist
          description: >-
            VM only. Deny egress to these domains/IPv4 CIDRs and allow
            everything else (empty list allows all). Mutually exclusive with
            network_allowlist. Entries may end in :port or :low-high (domains:
            :80 or :443 only) to match only those destination ports.
        network_rules:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/VmHeaderRule'
              type: object
            - type: 'null'
          title: Network Rules
          description: >-
            VM only. Per-host HTTPS request header substitution rules: each key
            is a rule host (exact DNS name or a single-level wildcard such as
            *.example.com), each value maps header names to templates that may
            reference platform secrets owned by the sandbox's owner with
            ${prime.secrets.<name>}. A rule never grants egress; the host must
            also be allowed by the allow/deny lists, and rules apply to HTTPS
            requests only. Substitution happens on the sandbox's node; the
            secret value never enters the sandbox.
        timeout_minutes:
          type: integer
          title: Timeout Minutes
          description: >-
            Max execution time in minutes. Defaults to 60. Use any negative
            value for no lifetime deadline.
          default: 60
        idle_timeout_minutes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Idle Timeout Minutes
          description: >-
            Terminate the sandbox if no exec, upload, download, or read-file
            operation is active for this many minutes. Unset disables it.
        environment_vars:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Environment Vars
          description: Environment variables
        secrets:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Secrets
          description: >-
            Sensitive environment variables. VM values are encrypted server-side
            with tenant- and sandbox-bound authenticated encryption before
            dispatch.
        labels:
          items:
            type: string
          type: array
          title: Labels
          description: Tags/labels for the sandbox
        volumes:
          items:
            $ref: '#/components/schemas/VolumeMountSpec'
          type: array
          maxItems: 8
          title: Volumes
          description: >-
            VM only. Up to 8 volumes to mount, resolved by name in the caller's
            scope (team_id selects the team scope). Mount paths are absolute,
            normalized, unique, and never nested. Each volume is mounted at its
            current published head, also when the sandbox restores or forks a
            checkpoint (a disk restore only; memory restore rejects volumes).
            Unpublished writes are not carried.
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
          description: Team ID for team sandboxes
        advanced_configs:
          anyOf:
            - $ref: '#/components/schemas/AdvancedConfigs'
            - type: 'null'
          description: Advanced configuration options
        registry_credentials_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Registry Credentials Id
          description: >-
            Retired: private-registry credentials are not supported. Any
            supplied value returns HTTP 410.
        guaranteed:
          type: boolean
          title: Guaranteed
          description: >-
            Admin/manager only. When true, schedule the sandbox with full
            CPU/memory requests and disk requests equal to the configured disk
            size, bypassing cluster resource multipliers. Not applicable to VM
            sandboxes.
          default: false
        idempotency_key:
          anyOf:
            - type: string
              maxLength: 128
              minLength: 1
            - type: 'null'
          title: Idempotency Key
          description: Client-generated key used to deduplicate retried create requests.
      type: object
      required:
        - name
      title: CreateSandboxRequest
    SandboxResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        dockerImage:
          type: string
          title: Dockerimage
        startCommand:
          anyOf:
            - $ref: '#/components/schemas/StartCommand'
            - type: string
            - type: 'null'
          title: Startcommand
        cpuCores:
          type: number
          title: Cpucores
        memoryGB:
          type: number
          title: Memorygb
        diskSizeGB:
          type: number
          title: Disksizegb
        diskMountPath:
          type: string
          title: Diskmountpath
        gpuCount:
          type: integer
          title: Gpucount
        gpuType:
          anyOf:
            - $ref: '#/components/schemas/GPUType'
            - type: 'null'
        vm:
          type: boolean
          title: Vm
          default: false
        network_allowlist:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Network Allowlist
        network_denylist:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Network Denylist
        status:
          $ref: '#/components/schemas/SandboxStatus'
        timeoutMinutes:
          type: integer
          title: Timeoutminutes
        idleTimeoutMinutes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Idletimeoutminutes
        terminationReason:
          anyOf:
            - type: string
            - type: 'null'
          title: Terminationreason
        environmentVars:
          anyOf:
            - type: object
            - type: 'null'
          title: Environmentvars
        advancedConfigs:
          anyOf:
            - type: object
            - type: 'null'
          title: Advancedconfigs
        labels:
          items:
            type: string
          type: array
          title: Labels
        createdAt:
          type: string
          format: date-time
          title: Createdat
        updatedAt:
          type: string
          format: date-time
          title: Updatedat
        startedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Startedat
        terminatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Terminatedat
        exitCode:
          anyOf:
            - type: integer
            - type: 'null'
          title: Exitcode
        errorType:
          anyOf:
            - type: string
            - type: 'null'
          title: Errortype
        errorMessage:
          anyOf:
            - type: string
            - type: 'null'
          title: Errormessage
        userId:
          anyOf:
            - type: string
            - type: 'null'
          title: Userid
        teamId:
          anyOf:
            - type: string
            - type: 'null'
          title: Teamid
        kubernetesJobId:
          anyOf:
            - type: string
            - type: 'null'
          title: Kubernetesjobid
        registryCredentialsId:
          anyOf:
            - type: string
            - type: 'null'
          title: Registrycredentialsid
        pendingImageBuildId:
          anyOf:
            - type: string
            - type: 'null'
          title: Pendingimagebuildid
          description: >-
            Set while the sandbox is PENDING because its VM image artifact is
            being built automatically (first VM use of this image). The sandbox
            starts on its own once the build completes.
        gatewayAuth:
          anyOf:
            - $ref: '#/components/schemas/SandboxAuthResponse'
            - type: 'null'
          description: >-
            Gateway credentials, returned on create when the API token has
            sandbox:read. Same payload as POST /sandbox/{id}/auth.
      type: object
      required:
        - id
        - name
        - dockerImage
        - startCommand
        - cpuCores
        - memoryGB
        - diskSizeGB
        - diskMountPath
        - gpuCount
        - status
        - timeoutMinutes
        - environmentVars
        - advancedConfigs
        - createdAt
        - updatedAt
        - startedAt
        - terminatedAt
        - userId
        - teamId
        - kubernetesJobId
      title: SandboxResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    StartCommand:
      properties:
        executable:
          type: string
          minLength: 1
          title: Executable
        args:
          items:
            type: string
          type: array
          title: Args
      additionalProperties: false
      type: object
      required:
        - executable
      title: StartCommand
      description: A process to start without invoking a shell.
    GPUType:
      type: string
      enum:
        - CPU_NODE
        - A10_24GB
        - A100_80GB
        - A100_40GB
        - A30_24GB
        - A40_48GB
        - B200_180GB
        - B300_262GB
        - GB200
        - GB300
        - RTX3070_8GB
        - RTX3070_8GB
        - RTX3080_10GB
        - RTX3080Ti_12GB
        - RTX3090_24GB
        - RTX3090Ti_24GB
        - RTX4070Ti_12GB
        - RTX4080_16GB
        - RTX4080Ti_16GB
        - RTX4090_24GB
        - RTX5090_32GB
        - H100_80GB
        - H200_96GB
        - GH200_96GB
        - H200_141GB
        - GH200_480GB
        - GH200_624GB
        - L4_24GB
        - L40_48GB
        - L40S_48GB
        - RTX4000_8GB
        - RTX5000_16GB
        - RTX6000_24GB
        - RTX8000_48GB
        - RTX2000Ada_16GB
        - RTX4000Ada_20GB
        - RTX5000Ada_32GB
        - RTX6000Ada_48GB
        - A2000_6GB
        - A4000_16GB
        - A4500_20GB
        - A5000_24GB
        - A6000_48GB
        - V100_16GB
        - V100_32GB
        - P100_16GB
        - T4_16GB
        - P4_8GB
        - P40_24GB
        - RTX_PRO_6000B_96GB
        - MI355X_288GB
      title: GPUType
    VmHeaderRule:
      properties:
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
      type: object
      required:
        - headers
      title: VmHeaderRule
      description: |-
        Headers to set on HTTPS requests to one rule host.

        Each value is a template that may contain "${prime.secrets.<name>}"
        references; a set header replaces any same-name header the sandbox sent.
    VolumeMountSpec:
      properties:
        name:
          type: string
          pattern: ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$
          title: Name
          description: Volume name, unique in its scope
        mount_path:
          type: string
          maxLength: 256
          minLength: 2
          title: Mount Path
          description: >-
            Absolute, normalized guest path to mount the volume at. Not the
            filesystem root or a system path (/proc, /sys, /dev, /etc, /usr,
            ...); unique per sandbox; never nested under another mount path.
        read_only:
          type: boolean
          title: Read Only
          description: Mount the volume read-only
          default: false
      type: object
      required:
        - name
        - mount_path
      title: VolumeMountSpec
      description: One requested volume mount; the name resolves in the caller's scope.
    AdvancedConfigs:
      properties: {}
      additionalProperties: true
      type: object
      title: AdvancedConfigs
    SandboxStatus:
      type: string
      enum:
        - PENDING
        - PROVISIONING
        - RUNNING
        - PAUSED
        - ERROR
        - TERMINATED
        - TIMEOUT
      title: SandboxStatus
    SandboxAuthResponse:
      properties:
        token:
          type: string
          title: Token
          description: JWT token for direct sandbox access
        gateway_url:
          type: string
          title: Gateway Url
          description: Gateway URL for direct sandbox operations
        user_ns:
          type: string
          title: User Ns
          description: User namespace for sandbox access
        job_id:
          type: string
          title: Job Id
          description: Job ID for sandbox access
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: Token expiration time
      type: object
      required:
        - token
        - gateway_url
        - user_ns
        - job_id
        - expires_at
      title: SandboxAuthResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````