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

# Create a Sandbox

> Creates a sandbox from an image and starts it.

When the image has a warm pool, you get a sandbox that is already running: the answer has `status: "running"` and `from_pool: true`. Otherwise the answer has `status: "creating"`. Poll `GET /sandboxes/{sandbox}` until it is `running` (usually a few seconds, a Windows sandbox woken cold can take longer) or `failed` (`error` says why).

The variables in `env` are in place before the sandbox shows as `running`.

To create a sandbox you need credit for at least an hour of it, the first 10 EUR top-up done, no overdue invoice, a free slot (`limits.max` in `GET /sandboxes/images`), an image within your account level's size, and an image in stock (`in_stock`). When one of these is missing, the answer is 422 with the reason in `message`.

Rate limit: 30 a minute, see [Limits](/sandboxes#limits).



## OpenAPI

````yaml POST /sandboxes
openapi: 3.0.3
info:
  title: CloudBlast API
  description: >-
    The CloudBlast V2 API provides a modern RESTful interface for managing your
    cloud infrastructure programmatically. All responses follow a consistent `{
    "data": ... }` or `{ "error": ... }` format.
  version: 2.0.0
servers:
  - url: https://console.cloudblast.io/api/v2
    description: Production
security:
  - bearerAuth: []
paths:
  /sandboxes:
    post:
      tags:
        - Sandboxes
      summary: Create a sandbox
      description: >-
        Creates a sandbox from an image and starts it.


        When the image has a warm pool, you get a sandbox that is already
        running: the answer has `status: "running"` and `from_pool: true`.
        Otherwise the answer has `status: "creating"`. Poll `GET
        /sandboxes/{sandbox}` until it is `running` (usually a few seconds, a
        Windows sandbox woken cold can take longer) or `failed` (`error` says
        why).


        The variables in `env` are in place before the sandbox shows as
        `running`.


        To create a sandbox you need credit for at least an hour of it, the
        first 10 EUR top-up done, no overdue invoice, a free slot (`limits.max`
        in `GET /sandboxes/images`), an image within your account level's size,
        and an image in stock (`in_stock`). When one of these is missing, the
        answer is 422 with the reason in `message`.


        Rate limit: 30 a minute, see [Limits](/sandboxes#limits).
      operationId: createSandbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxRequest'
      responses:
        '201':
          description: >-
            Sandbox created. Running when it came from the warm pool, otherwise
            creating.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Sandbox'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '422':
          description: >-
            A rule was broken (credit, slots, image), or a field failed
            validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxError'
              examples:
                no_credit:
                  summary: Not enough credit
                  value:
                    message: >-
                      Not enough credit: at least 0.10€ is needed, an hour of
                      this sandbox. Please top up first.
                no_slot:
                  summary: No free slot
                  value:
                    message: >-
                      Your account level allows 2 sandboxes at the same time.
                      Destroy one, or raise your level, to start another.
                image:
                  summary: Image not available
                  value:
                    message: This image is not available right now.
                env:
                  summary: Bad environment variable
                  value:
                    message: >-
                      "1TOKEN" is not a valid variable name: letters, digits and
                      _, not starting with a digit.
                validation:
                  summary: A field failed validation
                  value:
                    message: The image id field is required.
                    errors:
                      image_id:
                        - The image id field is required.
components:
  schemas:
    CreateSandboxRequest:
      type: object
      required:
        - image_id
      properties:
        image_id:
          type: integer
          description: >-
            From `GET /sandboxes/images`. The image decides the OS, the size and
            the location.
          example: 3
        name:
          type: string
          maxLength: 60
          nullable: true
          example: research-agent
        auto_stop_minutes:
          type: integer
          nullable: true
          description: >-
            Minutes without activity before the sandbox is stopped. 0 means
            never, otherwise from 5 to 43200 (30 days). Leave it out for the
            default (`lifecycle.auto_stop_minutes`, 15 unless the platform says
            otherwise).
          example: 30
        auto_destroy_minutes:
          type: integer
          nullable: true
          minimum: -1
          maximum: 43200
          description: >-
            Minutes the sandbox may stay stopped before it is destroyed. -1
            means never. 0 means as soon as it stops (ephemeral). Leave it out
            for the default (`lifecycle.auto_destroy_minutes`, never unless the
            platform says otherwise).
          example: 1440
        ephemeral:
          type: boolean
          default: false
          description: >-
            Destroy the sandbox as soon as it stops. The same as
            `auto_destroy_minutes: 0`, and it wins over `auto_destroy_minutes`.
        env:
          type: object
          nullable: true
          description: >-
            Environment variables, as `{"NAME": "value"}`. Names use letters,
            digits and `_`, do not start with a digit, and are up to 128
            characters. Up to 50 variables, 32 KB in all. Values are text. They
            are stored encrypted, and only the names are shown again.
          additionalProperties:
            type: string
          example:
            API_TOKEN: abc123
            MODE: test
    Sandbox:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: Sandbox handle. Use this as the `{sandbox}` path parameter.
          example: 9b2f4c1e-7d3a-4e8b-a5c6-1f0e2d3c4b5a
        name:
          type: string
          nullable: true
          example: research-agent
        image:
          type: string
          nullable: true
          description: Name of the image it was created from.
          example: Ubuntu 24.04 Desktop
        desktop:
          type: boolean
          description: >-
            True when it was created from a desktop image, so computer use
            works.
          example: true
        status:
          type: string
          description: >-
            `creating`: being created. `running`: ready to use. `stopping`,
            `stopped`, `starting`: on its way down, down with its disk kept, on
            its way up again. `deleting`: being destroyed. `failed`: it could
            not be created, see `error`. `deleted` only shows in the answer to
            an action on a sandbox that is already gone.
          enum:
            - creating
            - running
            - stopping
            - stopped
            - starting
            - deleting
            - deleted
            - failed
          example: running
        os:
          type: string
          enum:
            - linux
            - windows
          example: linux
        vcpu:
          type: integer
          example: 2
        memory_mb:
          type: integer
          example: 4096
        disk_gb:
          type: integer
          example: 20
        private_ip:
          type: string
          nullable: true
          description: Its address on the private sandbox network, once it has one.
          example: 10.80.0.14
        location:
          $ref: '#/components/schemas/SandboxLocation'
        error:
          type: string
          nullable: true
          description: >-
            Why the last create, start or stop did not work. `null` when all is
            well.
          example: null
        hourly_price:
          type: number
          description: Price per hour while it runs.
          example: 0.03
        stopped_hourly_price:
          type: number
          description: 'Price per hour while it is stopped: its disk only.'
          example: 0.002
        current_hourly_price:
          type: number
          description: Price per hour as it is now.
          example: 0.03
        billed_total:
          type: number
          description: Charged so far, billed per minute.
          example: 0.01225
        billed_until:
          type: string
          format: date-time
          nullable: true
          description: Up to when it has been billed.
          example: '2026-11-19T10:15:42+00:00'
        from_pool:
          type: boolean
          description: True when it was handed over already running from the warm pool.
          example: true
        env:
          type: array
          items:
            type: string
          description: >-
            The names of its environment variables. The values are never shown
            again.
          example:
            - API_TOKEN
            - MODE
        auto_stop_minutes:
          type: integer
          description: Minutes without activity before it is stopped. 0 means never.
          example: 15
        auto_destroy_minutes:
          type: integer
          description: >-
            Minutes it may stay stopped before it is destroyed. -1 means never,
            0 means as soon as it stops.
          example: -1
        ephemeral:
          type: boolean
          description: True when it is destroyed as soon as it stops.
          example: false
        created_at:
          type: string
          format: date-time
          example: '2026-11-19T09:58:02+00:00'
        stops_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When a running sandbox stops if nothing uses it before then. `null`
            when it is not running, or never stops by itself.
          example: '2026-11-19T10:30:42+00:00'
        destroys_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When a stopped sandbox is destroyed. `null` when it is not stopped,
            or is never destroyed by itself.
          example: null
    SandboxError:
      type: object
      description: >-
        How the sandbox endpoints answer an error: a `message`, not an error
        code. `errors` is only there when a request field failed validation.
      properties:
        message:
          type: string
          description: What went wrong, in plain words.
          example: Start the sandbox first.
        errors:
          type: object
          description: Messages per field, only when a field failed validation.
          additionalProperties:
            type: array
            items:
              type: string
          example:
            image_id:
              - The image id field is required.
      required:
        - message
    SandboxLocation:
      type: object
      nullable: true
      description: The region a sandbox or an image runs in. `null` when it is not known.
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Frankfurt, Germany
        short_code:
          type: string
          example: fra
        icon:
          type: string
          nullable: true
          description: URL of the location's icon.
          example: https://console.cloudblast.io/storage/locations/de.svg
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
          required:
            - code
            - message
  responses:
    Unauthenticated:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHENTICATED
              message: >-
                Missing or invalid Authorization header. Use: Authorization:
                Bearer <token>
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token from your CloudBlast account settings. Pass as `Authorization:
        Bearer <token>`.

````

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