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

# devbox desktop

> View and control the desktop of a macOS Devbox.

Use `devbox desktop` to open the desktop of a macOS Devbox in a local VNC client, capture screenshots, click, type text, and press keys. The screenshot, click, type, and press commands let a script or an agent drive apps that have no command-line interface.

The desktop is available on macOS Devboxes only. Every subcommand takes the Devbox as an optional positional argument. On a terminal, omitting it opens a picker.

<h2 id="desktop-usage">
  Usage
</h2>

```bash theme={null}
devbox desktop [command]
```

<h2 id="desktop-options">
  Options
</h2>

<ResponseField name="--show_all" type="boolean" default="false">
  Include Devboxes owned by other workspace members in the Devbox picker. Every `devbox desktop` subcommand accepts this option.
</ResponseField>

## `devbox desktop connect`

Open the desktop in a local VNC client. The connection is forwarded through a local port until the VNC client disconnects or you press `Ctrl+C`. If no VNC client opens, connect one to the printed address with the printed credentials.

<Info>
  `devbox desktop view` is an alias for `devbox desktop connect`.
</Info>

<h3 id="connect-usage">
  Usage
</h3>

<CodeGroup>
  ```bash Canonical theme={null}
  devbox desktop connect [devbox] [flags]
  ```

  ```bash Alias theme={null}
  devbox desktop view [devbox] [flags]
  ```
</CodeGroup>

### Use another VNC client

```bash theme={null}
devbox desktop connect my-devbox --no_open
```

<h3 id="connect-options">
  Options
</h3>

<ResponseField name="--no_open" type="boolean" default="false">
  Print the connection details instead of opening a VNC client.
</ResponseField>

***

## `devbox desktop screenshot`

Save a PNG screenshot of the desktop. The CLI prints the screenshot size, in the same pixels that `devbox desktop click` uses.

<h3 id="screenshot-usage">
  Usage
</h3>

```bash theme={null}
devbox desktop screenshot [devbox] --file <path> [flags]
```

### Save a screenshot

```bash theme={null}
devbox desktop screenshot my-devbox --file shot.png
```

### Write the PNG to stdout

```bash theme={null}
devbox desktop screenshot my-devbox --file - > shot.png
```

<h3 id="screenshot-options">
  Options
</h3>

<ResponseField name="--file" type="string" required>
  Write the PNG to this path, or to stdout when the value is `-`.
</ResponseField>

***

## `devbox desktop click`

Click a point on the desktop. Coordinates are screenshot pixels, measured from the upper-left corner, so a point read from a screenshot can be passed as is.

<h3 id="click-usage">
  Usage
</h3>

```bash theme={null}
devbox desktop click [devbox] --x <x> --y <y> [flags]
```

### Right-click a point

```bash theme={null}
devbox desktop click my-devbox --x 100 --y 200 --button right
```

<h3 id="click-options">
  Options
</h3>

<ResponseField name="--x" type="int" required>
  Set the horizontal position in screenshot pixels.
</ResponseField>

<ResponseField name="--y" type="int" required>
  Set the vertical position in screenshot pixels.
</ResponseField>

<ResponseField name="--button" type="string" default="left">
  Click this mouse button: `left`, `middle`, or `right`.
</ResponseField>

***

## `devbox desktop type`

Type text into the focused application. A newline in the text presses Enter. To press shortcuts or named keys, use [`devbox desktop press`](#devbox-desktop-press).

<h3 id="type-usage">
  Usage
</h3>

```bash theme={null}
devbox desktop type [devbox] --text <text> [flags]
```

### Type text

```bash theme={null}
devbox desktop type my-devbox --text "hello world"
```

<h3 id="type-options">
  Options
</h3>

<ResponseField name="--text" type="string" required>
  Type this text.
</ResponseField>

***

## `devbox desktop press`

Press keys on the desktop, in the order given. A key is one character or a named key, optionally preceded by modifiers joined with `+`, such as `cmd+space` or `shift+tab`.

<div className="desktop-keys-table">
  | Named keys | Values |
  | - | - |
  | Editing | `space`, `enter`, `tab`, `backspace`, `delete` |
  | Escape | `escape`, or `esc` |
  | Navigation | `home`, `end`, `pageup`, `pagedown` |
  | Arrows | `up`, `down`, `left`, `right` |
</div>

<div className="desktop-keys-table">
  | Modifier | Values |
  | - | - |
  | Command (⌘) | `cmd`, or `command` |
  | Option (⌥) | `opt`, or `option` |
  | Control (⌃) | `ctrl`, or `control` |
  | Shift (⇧) | `shift` |
</div>

<h3 id="press-usage">
  Usage
</h3>

```bash theme={null}
devbox desktop press [devbox] --key <key> [--key <key>...] [flags]
```

### Open Spotlight

```bash theme={null}
devbox desktop press my-devbox --key cmd+space
```

### Press several keys in order

```bash theme={null}
devbox desktop press my-devbox --key down --key down --key enter
```

<h3 id="press-options">
  Options
</h3>

<ResponseField name="--key" type="stringArray" required>
  Press this key, such as `enter` or `cmd+space`. Repeat the option to press several keys in order.
</ResponseField>

## Related topics

<CardGroup cols={2}>
  <Card title="Computer Controls" icon="monitor" href="/docs/devbox/computer-use">
    Capture, click, and type on a macOS Devbox from a script or an agent.
  </Card>

  <Card title="devbox exec" icon="terminal" href="/docs/reference/devbox-cli/exec">
    Launch apps and run commands without the screen.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.