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

# Post apiv1sandboxes



## OpenAPI

````yaml https://api.simplesandbox.dev/doc post /api/v1/sandboxes
openapi: 3.0.0
info:
  version: 1.0.0
  title: Sandbox API
servers: []
security: []
paths:
  /api/v1/sandboxes:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxCreate'
      responses:
        '201':
          description: Sandbox created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSandboxResponse'
        '400':
          description: Bad request or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Concurrency limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SandboxCreate:
      type: object
      properties:
        image:
          type: string
          example: node:22
          description: Docker image to run inside the shared Fly app
        timeoutMs:
          type: integer
          minimum: 0
          example: 600000
          description: >-
            Optional timeout in milliseconds for the sandbox. Defaults to 10
            minutes (600000ms). Maximum 1 hour (3600000ms) from creation for
            FREE users.
        env:
          type: object
          additionalProperties:
            type: string
          example:
            NODE_ENV: production
            API_KEY: secret
          description: >-
            Environment variables to set in the sandbox. These will be available
            to all commands executed in the sandbox.
        volumes:
          type: object
          additionalProperties:
            anyOf:
              - type: string
                pattern: ^[a-z0-9_]{1,30}$
              - type: object
                properties:
                  name:
                    type: string
                    pattern: ^[a-z0-9_]{1,30}$
                  sizeGb:
                    type: integer
                    minimum: 1
                    maximum: 100
                    default: 1
                required:
                  - name
          example:
            /workspace: my_packages
            /cache:
              name: build_cache
              sizeGb: 5
          description: >-
            Mount volumes by name. Creates if missing, reuses if exists. Key is
            mount path, value is volume name or config. Volume names must
            contain only lowercase alphanumeric characters and underscores (max
            30 chars).
      required:
        - image
    CreateSandboxResponse:
      type: object
      properties:
        sandbox:
          $ref: '#/components/schemas/Sandbox'
      required:
        - sandbox
    Error:
      type: object
      properties:
        code:
          type: number
          example: 422
        message:
          type: string
          example: 'Validation failed: Name has already been taken'
        details:
          nullable: true
      required:
        - code
        - message
    Sandbox:
      type: object
      properties:
        id:
          type: string
          example: e7847229c547d8
        name:
          type: string
          example: sandbox-node-1
        state:
          type: string
          example: started
        region:
          type: string
          example: iad
        image:
          type: string
          example: node:22
        createdAt:
          type: string
          format: date
          example: '2023-12-01T00:00:00Z'
        stopAt:
          type: string
          format: date
          example: '2023-12-01T01:00:00Z'
        publicAccessUrlTemplate:
          type: string
          example: >-
            {{PORT}}-m_01h9z60rm0ex1rc4x-sandbox-shared-app-fly.apps.simplesandbox.dev
          description: >-
            Host template for public access. Replace `{{PORT}}` with the numeric
            port (e.g. `8080`) and prepend the scheme if needed, e.g.
            `https://8080-m_01h9z60rm0ex1rc4x-sandbox-shared-app-fly.apps.simplesandbox.dev`.
      required:
        - id
        - name
        - state
        - region
        - image
        - createdAt
        - stopAt
        - publicAccessUrlTemplate

````