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

## Usage

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

## Options

**--show\_all** `boolean` (default: false)

Include Devboxes owned by other workspace members in the Devbox picker. Every `devbox desktop` subcommand accepts this option.

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

> [!NOTE]
>
> `devbox desktop view` is an alias for `devbox desktop connect`.

### Usage

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

```bash Alias theme={null}
devbox desktop view [devbox] [flags]
```

### Use another VNC client

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

### Options

**--no\_open** `boolean` (default: false)

Print the connection details instead of opening a VNC client.

***

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

### Usage

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

### Options

**--file** `string` *required*

Write the PNG to this path, or to stdout when the value is `-`.

***

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

### Usage

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

### Options

**--x** `int` *required*

Set the horizontal position in screenshot pixels.

**--y** `int` *required*

Set the vertical position in screenshot pixels.

**--button** `string` (default: left)

Click this mouse button: `left`, `middle`, or `right`.

***

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

### Usage

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

### Type text

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

### Options

**--text** `string` *required*

Type this text.

***

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

| Named keys | Values |
| - | - |
| Editing | `space`, `enter`, `tab`, `backspace`, `delete` |
| Escape | `escape`, or `esc` |
| Navigation | `home`, `end`, `pageup`, `pagedown` |
| Arrows | `up`, `down`, `left`, `right` |

| Modifier | Values |
| - | - |
| Command (⌘) | `cmd`, or `command` |
| Option (⌥) | `opt`, or `option` |
| Control (⌃) | `ctrl`, or `control` |
| Shift (⇧) | `shift` |

### Usage

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

### Options

**--key** `stringArray` *required*

Press this key, such as `enter` or `cmd+space`. Repeat the option to press several keys in order.

## Related topics

> [card] [Computer Controls](https://namespace.so/docs/devbox/computer-use.md)
>
> Capture, click, and type on a macOS Devbox from a script or an agent.

> [card] [devbox exec](https://namespace.so/docs/reference/devbox-cli/exec.md)
>
> Launch apps and run commands without the screen.


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