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

# Create Desktop

> Provision a new VM environment

Creates and initializes a new desktop environment. Runs as a background task and returns immediately with a task ID for status polling. Supports multiple VMs simultaneously (max 16).

Returns `429 Too Many Requests` if the maximum number of concurrent environments is reached.

## Request Body

<ParamField body="provider_name" type="string" default="docker">
  VM provider
</ParamField>

<ParamField body="os_type" type="string" default="Ubuntu">
  Operating system (`Ubuntu`, `Windows`, `macOS`)
</ParamField>

<ParamField body="remote_server_ip" type="string">
  Remote server IP (for remote VMs)
</ParamField>

<ParamField body="remote_server_port" type="integer">
  Remote server port
</ParamField>

<ParamField body="require_a11y_tree" type="boolean" default="false">
  Enable accessibility tree
</ParamField>

<ParamField body="require_terminal" type="boolean" default="false">
  Enable terminal access
</ParamField>

<ParamField body="timeout" type="integer" default="3600">
  Session timeout in seconds
</ParamField>

## Response

<ResponseField name="status" type="string">
  Request status (`accepted`)
</ResponseField>

<ResponseField name="message" type="string">
  Status message
</ResponseField>

<ResponseField name="vm_id" type="string">
  Unique identifier for the VM
</ResponseField>

<ResponseField name="task_id" type="string">
  Background task ID for status polling
</ResponseField>

<ResponseField name="status_url" type="string">
  URL to check task status
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "http://CONTROL_PLANE_IP:PORT/create_desktop" \
    -H "Content-Type: application/json" \
    -d '{
      "provider_name": "docker",
      "os_type": "Ubuntu",
      "require_a11y_tree": true,
      "require_terminal": false,
      "timeout": 3600
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response (202) theme={null}
  {
    "status": "accepted",
    "message": "Desktop environment creation started",
    "vm_id": "vm-abc123",
    "task_id": "uuid-string",
    "status_url": "/task_status/uuid-string"
  }
  ```

  ```json Max Environments Reached (429) theme={null}
  {
    "error": "Maximum number of environments reached",
    "details": "Cannot create new environment. Maximum of 16 concurrent environments allowed.",
    "current_count": 16,
    "max_allowed": 16
  }
  ```
</ResponseExample>