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

# Create Sandbox

> Create an ephemeral or named sandbox.

Launch an ephemeral or named sandbox.

* Omit `name` to create an ephemeral sandbox.
* Set `name` to create a named sandbox that supports suspend and resume.
* Set `snapshot_id` to restore from a snapshot, or `image` to boot from a registered Sandbox Image.
* For fresh creates, if `resources.disk_mb` is omitted, the sandbox uses the default 10 GB root disk (`10240` MiB).
* With `image`, `resources.disk_mb` can be used to grow the root disk at create time (growth-only).
* With `snapshot_id` from a filesystem snapshot, `resources.disk_mb` can be used to grow the root disk at create time (growth-only).


## OpenAPI

````yaml post /sandboxes
openapi: 3.1.0
info:
  title: Tensorlake API
  description: >-
    Tensorlake Cloud APIs for Sandboxes, Document Ingestion, and Serverless
    Workflows
  license:
    name: ''
  version: 0.1.0
servers:
  - url: https://api.tensorlake.ai/
security:
  - bearerAuth: []
tags:
  - name: Tensorlake Cloud API
    description: >-
      Tensorlake Cloud APIs for Sandboxes, Document Ingestion, and Serverless
      Workflows
paths:
  /sandboxes:
    post:
      tags:
        - sandboxes
      summary: Create a sandbox
      description: Create an ephemeral or named sandbox.
      operationId: create_sandbox
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxRequest'
        required: true
      responses:
        '200':
          description: Sandbox created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSandboxResponse'
        '400':
          description: Invalid sandbox creation request
          content:
            text/plain: {}
        '401':
          description: Unauthorized. Invalid or missing credentials
        '403':
          description: Forbidden. You do not have permission to access this resource
        '404':
          description: Referenced snapshot was not found
          content:
            text/plain: {}
        '409':
          description: A sandbox with the requested name already exists in this namespace
          content:
            text/plain: {}
        '422':
          description: Invalid properties in request body
          content:
            text/plain: {}
        '500':
          description: Internal server error
          content:
            text/plain: {}
components:
  schemas:
    CreateSandboxRequest:
      type: object
      properties:
        image:
          type: string
          description: >-
            Optional sandbox image name to boot from. When omitted, Tensorlake
            uses the default managed environment. This can also be a registered
            Sandbox Image name.
        resources:
          $ref: '#/components/schemas/SandboxResourceOverrides'
        secret_names:
          type: array
          description: Secret names to inject into the sandbox.
          items:
            type: string
        timeout_secs:
          type: integer
          format: int64
          minimum: 0
          description: >
            Sandbox timeout in seconds. `0` requests the maximum allowed by your
            plan.

            Plan maximums: Free unverified 3600 (1h), Free verified 7200 (2h),

            On-Demand 86400 (24h). See
            [tensorlake.ai/pricing](https://www.tensorlake.ai/pricing) for
            higher limits on committed plans.
        entrypoint:
          type: array
          description: Optional command to run when the sandbox starts.
          items:
            type: string
        network:
          $ref: '#/components/schemas/SandboxNetworkAccessControl'
        snapshot_id:
          type: string
          description: Snapshot to restore from.
        allow_unauthenticated_access:
          type: boolean
          description: >-
            Allow sandbox ingress to route requests without validating auth
            credentials. The legacy request alias
            `allow_unauthenticated_proxy_access` is also accepted.
        exposed_ports:
          type: array
          description: >-
            Additional sandbox ports that public ingress may route to. When
            omitted, only the management port `9501` is routable.
          items:
            type: integer
            format: int32
            minimum: 1
            maximum: 65535
        template_id:
          type: string
          description: Template identifier to associate with the launched sandbox.
        name:
          type: string
          description: >-
            Optional user-provided sandbox name. When set, the sandbox is named
            and supports suspend/resume. When omitted, the sandbox is ephemeral.
    CreateSandboxResponse:
      type: object
      required:
        - sandbox_id
        - status
      properties:
        sandbox_id:
          type: string
        status:
          $ref: '#/components/schemas/SandboxStatus'
        pending_reason:
          $ref: '#/components/schemas/SandboxPendingReason'
    SandboxResourceOverrides:
      type: object
      properties:
        cpus:
          type: number
          format: double
          description: CPU allocation override in cores.
        memory_mb:
          type: integer
          format: int64
          description: Memory allocation override in MiB.
        disk_mb:
          type: integer
          format: int64
          minimum: 10240
          maximum: 102400
          description: >
            Ephemeral root filesystem size in MiB. Defaults to 10240 (10 GiB).

            Must be between 10240 and 102400 inclusive. For filesystem
            snapshots,

            this can be used with snapshot_id to grow root disk size
            (growth-only).
        gpus:
          type: array
          items:
            $ref: '#/components/schemas/GPUResources'
          description: Optional GPU allocation override.
    SandboxNetworkAccessControl:
      type: object
      properties:
        allow_internet_access:
          type: boolean
          default: true
          description: If false, all outbound internet access is blocked by default.
        allow_out:
          type: array
          description: Allowlisted destination IPs or CIDRs for outbound traffic.
          items:
            type: string
        deny_out:
          type: array
          description: Denylisted destination IPs or CIDRs for outbound traffic.
          items:
            type: string
    SandboxStatus:
      type: string
      enum:
        - pending
        - running
        - snapshotting
        - suspending
        - suspended
        - terminated
    SandboxPendingReason:
      type: string
      enum:
        - scheduling
        - waiting_for_container
        - no_executors_available
        - no_resources_available
        - pool_at_capacity
    GPUResources:
      type: object
      required:
        - count
        - model
      properties:
        count:
          type: integer
          format: int32
          minimum: 1
        model:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````