Skip to main content
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

NeedUse
Browser or GUI task for an agentDesktop automation
Human review of what the agent seesManaged viewer
Audit trail for a visual taskRecordings
Terminal access to the same machinePTY 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)

​
Desktop Surfaces

SurfaceUse It For
ScreenshotsInspect the current display or crop a region for visual agents.
InputMove, click, drag, scroll, type text, and send hotkeys.
Windows and clipboardInspect windows, launch apps, and exchange clipboard text.
Viewer sessionsOpen a signed browser viewer for supervision or handoff.
RecordingsCapture 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.