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

# Interact with the display

> Capture screenshots and send pointer input to Devboxes with graphical displays.

Use `devbox.display` to capture a macOS Devbox screen as PNG bytes and click framebuffer coordinates. Display access is currently available only for macOS Devboxes.

<Info>
  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.
</Info>

## `display.screenshot()`

Capture the full current framebuffer and encode it as PNG.

### Example

```typescript {4,6} theme={null}
import { writeFile } from "node:fs/promises";

const devbox = await client.devboxes.get("sdk-example");
const screenshot = await devbox.display.screenshot({ timeoutMs: 30_000 });

await writeFile("screenshot.png", screenshot.png);
```

### API reference

```typescript theme={null}
screenshot(options?: OperationOptions): Promise<Screenshot>
```

#### Arguments and options

<ResponseField name="options" type="OperationOptions">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="signal" type="AbortSignal">Cancels activation, connection, or capture when aborted.</ResponseField>
    <ResponseField name="timeoutMs" type="number">Total activation, connection, and capture budget in milliseconds. There is no default timeout. The value must be finite and non-negative.</ResponseField>
  </Expandable>
</ResponseField>

#### Return value

```typescript theme={null}
interface Screenshot {
  png: Uint8Array;
  width: number;
  height: number;
  desktopName: string;
}
```

<ResponseField name="png" type="Uint8Array" required>PNG-encoded image bytes.</ResponseField>
<ResponseField name="width" type="number" required>Framebuffer width in pixels.</ResponseField>
<ResponseField name="height" type="number" required>Framebuffer height in pixels.</ResponseField>
<ResponseField name="desktopName" type="string" required>The desktop name reported by the display server.</ResponseField>

***

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

```typescript {2} theme={null}
const devbox = await client.devboxes.get("sdk-example");
await devbox.display.click(100, 200, { button: "right" });
```

### API reference

```typescript theme={null}
click(x: number, y: number, options?: ClickOptions): Promise<void>
```

#### Arguments and options

<ResponseField name="x" type="number" required>The integer horizontal coordinate in framebuffer pixels, increasing to the right.</ResponseField>
<ResponseField name="y" type="number" required>The integer vertical coordinate in framebuffer pixels, increasing downward.</ResponseField>

<ResponseField name="options" type="ClickOptions">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="button" type="&#x22;left&#x22; | &#x22;middle&#x22; | &#x22;right&#x22;" default="&#x22;left&#x22;">The mouse button to press and release.</ResponseField>
    <ResponseField name="signal" type="AbortSignal">Cancels activation, connection, or input when aborted.</ResponseField>
    <ResponseField name="timeoutMs" type="number">Total activation, connection, and input budget in milliseconds. There is no default timeout. The value must be finite and non-negative.</ResponseField>
  </Expandable>
</ResponseField>

#### 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 with `DevboxDisplayUnavailableError` 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](/docs/reference/typescript-sdk/errors) for shared error handling guidance.