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

# Desktop Environments

> Run GUI-capable machines for browser, desktop app, and visual-agent workflows.

Desktop environments are machine templates with a graphical display plus SDK
APIs for screenshots, mouse, keyboard, clipboard, windows, recordings, and
viewer sessions. Use them when an agent or automation workflow needs to operate
a browser or desktop app instead of only a shell.

## When To Use Desktop

| Need                                | Use                                          |
| ----------------------------------- | -------------------------------------------- |
| Browser or GUI task for an agent    | [Desktop automation](./automation)           |
| Human review of what the agent sees | [Managed viewer](./viewer)                   |
| Audit trail for a visual task       | [Recordings](./recordings)                   |
| Terminal access to the same machine | [PTY](../access/pty) or [SSH](../access/ssh) |

Desktop environments are a machine capability. They are not limited to human
access: agents can use automation APIs, and humans can supervise the same
machine through a viewer when needed.

## Quick Example

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Machine

  with Machine.create(
      template="desktop",
      timeout=300,
      resolution=(1440, 900),
  ) as machine:
      machine.desktop.open("https://example.com")
      png = machine.desktop.screenshot()
      width, height = machine.desktop.screen_size()
      print(len(png), width, height)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine desktop open mch_123 "https://example.com"
  nullspace machine desktop screenshot mch_123 -o screenshot.png
  nullspace machine desktop screen-size mch_123
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/desktop/open" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"target": "https://example.com"}'

  curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/desktop/screenshot" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -o screenshot.png

  curl "${NULLSPACE_API_URL}/v1/machines/mch_123/desktop/screen_size" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

## Desktop Surfaces

| Surface               | Use It For                                                      |
| --------------------- | --------------------------------------------------------------- |
| Screenshots           | Inspect the current display or crop a region for visual agents. |
| Input                 | Move, click, drag, scroll, type text, and send hotkeys.         |
| Windows and clipboard | Inspect windows, launch apps, and exchange clipboard text.      |
| Viewer sessions       | Open a signed browser viewer for supervision or handoff.        |
| Recordings            | Capture screen videos for audit or debugging.                   |

Desktop viewer URLs are signed bearer URLs. Treat them like temporary access
credentials and rotate sessions before sharing broadly.

## Guides

<CardGroup cols={2}>
  <Card title="Desktop automation" href="./automation">
    Drive screenshots, mouse, keyboard, windows, clipboard, and app launch from code.
  </Card>

  <Card title="Managed viewer" href="./viewer">
    Open a signed browser viewer for supervising or handing off a desktop machine.
  </Card>

  <Card title="Recordings" href="./recordings">
    Record, list, download, and delete desktop session videos.
  </Card>

  <Card title="Desktop viewer example" href="../examples/desktop-viewer">
    Start a desktop machine, open a page, create a viewer URL, and capture a screenshot.
  </Card>
</CardGroup>

## Related

* [Machines](../machines/overview)
* [Access](../access/overview)
* [Agents](../agents/overview)