Desktop Environments

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
Human review of what the agent sees	Managed viewer
Audit trail for a visual task	Recordings
Terminal access to the same machine	PTY or 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

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)

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

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}"

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

Desktop automation

Drive screenshots, mouse, keyboard, windows, clipboard, and app launch from code.

Managed viewer

Open a signed browser viewer for supervising or handing off a desktop machine.

Recordings

Record, list, download, and delete desktop session videos.

Desktop viewer example

Start a desktop machine, open a page, create a viewer URL, and capture a screenshot.

Bash Desktop Automation

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Desktop Environments

When To Use Desktop

Quick Example

Desktop Surfaces

Guides

Desktop automation

Managed viewer

Recordings

Desktop viewer example

​When To Use Desktop

​Quick Example

​Desktop Surfaces

​Guides

Desktop automation

Managed viewer

Recordings

Desktop viewer example

​Related

When To Use Desktop

Quick Example

Desktop Surfaces

Guides

Related