> ## 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.

# Desktop Environment API

> API reference for Desktop VM management and interaction

The Desktop Environment API is organized into two layers:

* **Control Plane**: VM lifecycle management (create, initialize, evaluate, close)
* **Data Plane**: Direct VM interaction (screenshot, execute, accessibility)

<Info>
  Contact Scale to receive access to Desktop Environments. VMs are provisioned and managed through the Scale Gymnasium platform.
</Info>

## Control Plane (VM Lifecycle)

Endpoints for managing VM lifecycle and task execution.

<CardGroup cols={2}>
  <Card title="Health" icon="heart-pulse" href="/api-reference/desktop/control-plane/health">
    Check API server status
  </Card>

  <Card title="Create Desktop" icon="plus" href="/api-reference/desktop/control-plane/create-desktop">
    Provision a new VM environment
  </Card>

  <Card title="Initialize Task" icon="play" href="/api-reference/desktop/control-plane/initialize-task">
    Set up a task in the VM
  </Card>

  <Card title="Run Evaluator" icon="check" href="/api-reference/desktop/control-plane/run-evaluator">
    Evaluate task completion
  </Card>

  <Card title="Reset" icon="rotate" href="/api-reference/desktop/control-plane/reset">
    Reset environment to initial state
  </Card>

  <Card title="Close" icon="xmark" href="/api-reference/desktop/control-plane/close">
    Terminate VM and clean up
  </Card>

  <Card title="List Environments" icon="list" href="/api-reference/desktop/control-plane/list-environments">
    View all active VMs
  </Card>

  <Card title="Get VNC URL" icon="display" href="/api-reference/desktop/control-plane/get-vnc-url">
    Get VNC connection URL
  </Card>

  <Card title="Task Status" icon="clock" href="/api-reference/desktop/control-plane/task-status">
    Check background task status
  </Card>

  <Card title="Run Agent Loop" icon="robot" href="/api-reference/desktop/control-plane/run-agent-loop">
    Execute agent on a task
  </Card>
</CardGroup>

## Data Plane (VM Interaction)

Endpoints for direct interaction with the running VM.

<CardGroup cols={2}>
  <Card title="Screenshot" icon="camera" href="/api-reference/desktop/screenshot">
    Capture current visual state
  </Card>

  <Card title="Execute" icon="terminal" href="/api-reference/desktop/execute">
    Run shell commands
  </Card>

  <Card title="Platform" icon="computer" href="/api-reference/desktop/platform">
    Get OS information
  </Card>

  <Card title="Accessibility" icon="universal-access" href="/api-reference/desktop/accessibility">
    Get UI accessibility tree
  </Card>

  <Card title="File" icon="file-arrow-down" href="/api-reference/desktop/file">
    Download files from VM
  </Card>
</CardGroup>

## Network Access

| Component                    | Port | Access Method           |
| ---------------------------- | ---- | ----------------------- |
| **Control Plane API**        | 3000 | VM lifecycle management |
| **Data Plane API (OSWorld)** | 5000 | AI agent interaction    |
| **noVNC Web**                | 8006 | Browser-based access    |
| **VNC Server**               | 5900 | Direct VNC client       |

## Next Steps

<CardGroup cols={2}>
  <Card title="Desktop Guide" icon="desktop" href="/environments/desktop/overview">
    Explore desktop environments
  </Card>

  <Card title="Docker Quick Start" icon="docker" href="/getting-started/quickstart-docker">
    Self-host desktop environments
  </Card>
</CardGroup>