devbox.display to capture a macOS Devbox screen as PNG bytes and click framebuffer coordinates. Display access is currently available only for macOS Devboxes.
Display operations start a stopped Devbox automatically. The SDK obtains display credentials and caches the display connection for later screenshots and clicks. This page documents the Devbox display API, not the lower-level standalone VNC client.
display.screenshot()
Capture the full current framebuffer and encode it as PNG.
Example
API reference
Arguments and options
OperationOptions
Return value
Uint8Array
required
PNG-encoded image bytes.
number
required
Framebuffer width in pixels.
number
required
Framebuffer height in pixels.
string
required
The desktop name reported by the display server.
display.click()
Move the pointer to a framebuffer position, press a mouse button, and release it. Coordinates use the screenshot’s pixel dimensions, with (0, 0) at the top-left corner. Valid coordinates satisfy 0 <= x < width and 0 <= y < height.
Example
API reference
Arguments and options
number
required
The integer horizontal coordinate in framebuffer pixels, increasing to the right.
number
required
The integer vertical coordinate in framebuffer pixels, increasing downward.
ClickOptions
Return value
The promise resolves after the move, press, and release events have been sent. It returns no result.Errors and availability
Display methods reject withDevboxDisplayUnavailableError when the Devbox has no graphical display, including current non-macOS Devboxes. Gateway HTTP failures reject with DevboxGatewayError, whose statusCode contains the response status. Timeouts reject with DevboxTimeoutError, whose timeoutMs records the budget when available.
display.click() rejects with RangeError when either coordinate is not an integer or lies outside the current framebuffer. Cancellation rejects with the signal’s reason, or an AbortError. RPC and transport failures can also reject the operation.
See Handle errors and timeouts for shared error handling guidance.