# Desktop

> Open a Linux desktop with Chrome and a terminal from a sandbox in your browser, share it with a link, and automate its Chrome on localhost:9222.

```sh
cloudex desktop
```

`cloudex desktop` starts a desktop in the sandbox and opens it in your browser. The desktop has Google Chrome, a terminal (xterm), the openbox window manager and a tint2 panel. It runs on TigerVNC, and your browser shows it through noVNC.

The first start installs the desktop, about 950 MB, which takes a minute or two. On a [node](https://cloudex.build/docs/nodes.md), it comes over the node's own line. A save keeps it, so later starts take seconds. A [restore from backup](https://cloudex.build/docs/sandboxes.md#backups) doesn't keep it, because it's installed outside `/home`; the next start installs it again.

## On your computer, or by link

By default, the CLI forwards a local port, opens your browser on it, and keeps the connection until you press Ctrl-C. The desktop keeps running in the sandbox after that, and `cloudex desktop` connects to it again.

```sh
cloudex desktop --link
```

`--link` prints an HTTPS link on your [preview domain](https://cloudex.build/docs/deploy.md#preview-domain) instead. It works in any browser while the sandbox runs, for anyone who has the link. The link is the only protection; the desktop has no password. To make a shared link stop working, run `cloudex host <sandbox> 6080 --revoke`; see [Revoke a link](https://cloudex.build/docs/connect.md#revoke-a-link).

## Options

| Flag | Default | Effect |
|---|---|---|
| `--size` | `1280x720` for a new desktop | Screen size as WIDTHxHEIGHT. A running desktop is resized to it; without `--size`, it keeps its size. |
| `--quality` | `3` | Picture quality from 0 to 9. Lower uses less bandwidth on moving images; text stays sharp. |
| `--link` | off | Print an HTTPS link on your preview domain instead of using a local port |
| `--port` | `6080`, or a free one | The local port to use |
| `--no-open` | off | Don't open a browser |
| `--stop` | off | Stop the desktop and the programs on it |

```sh
cloudex desktop web --size 1920x1080
cloudex desktop --quality 0
cloudex desktop --stop
```

A still page uses little bandwidth. Full-screen motion can use tens of Mbit/s; on a slow connection, `--quality 0` cuts that by more than half.

## Windows from the sandbox

While the desktop runs, programs started from a shell in the sandbox show their windows on it, as long as the shell was opened after the desktop started. That includes a browser an agent opens to test a page.

The desktop's Chrome listens for automation, the Chrome DevTools Protocol, on `localhost:9222` inside the sandbox. Tools in the sandbox, such as Playwright or Puppeteer, can connect to `http://localhost:9222`. To reach it from your computer, forward the port:

```sh
cloudex ssh -- -L 9222:localhost:9222
```

Chrome keeps its profile in `~/.config/cloudex-chrome`, so sign-ins and history stay with the sandbox.

## Idle stop and updates

A browser showing the desktop counts as activity, so the sandbox stays up while you watch it. When you close the browser, [idle stop](https://cloudex.build/docs/sandboxes.md#idle-stop) counts from then.

Running `cloudex deploy` can drop desktop connections; the viewer reconnects by itself.
