# Desktop

> Every box can show a full Linux desktop, or a single Chrome window, in your browser. It streams over VNC inside the private tunnel; nothing is opened to the internet.

URL: https://prized.dev/docs/desktop

## Open [#open]

On the box page, open the **Desktop** tab. Pick **Desktop** for a 1920x1080 XFCE desktop or **Browser** for one Chrome window, then click open. From the terminal:

```bash
prized desktop
prized browser --url https://example.com
```

A desktop is up in a few seconds; a box created before September 2, 2026 installs the packages on its first open (about two minutes, once).

| Command                | What it does                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prized desktop [BOX]` | Start the desktop, forward its VNC port to `127.0.0.1`, and open the dashboard tab. Runs until Ctrl-C; wakes a suspended box.                           |
| `prized browser [BOX]` | The same with one Chrome window. `--profile NAME` picks the [profile](#browser-profiles), `--url URL` the start page.                                   |
| `--no-open`            | Print the `vnc://127.0.0.1:PORT` address and the password for a native VNC client instead of opening the dashboard.                                     |
| `--stop`               | Stop the desktop (or browser) on the box and exit. Never wakes a paused box.                                                                            |
| `--json`               | Print `{"ok":true,"box":"…","mode":"desktop","localPort":…,"password":"…","dashboardUrl":"…"}` once the forward listens, open nothing, keep forwarding. |

## What you get [#what-you-get]

* **Desktop:** XFCE with a terminal, a file manager and Chrome, on a fixed 1920x1080 screen scaled to your window. `xdotool` and `wmctrl` are installed for scripts.
* **Browser:** one maximized Chrome window and nothing else. Sign in to a site once and tools on the box can reuse the profile.
* **Keyboard and mouse** work as in a native window. The tab's header has full screen and two clipboard buttons, paste to the box and copy from it.
* **The desktop keeps running when you close the tab.** Open it again and you land on the same windows. **Stop desktop** in the tab, or `prized desktop --stop`, ends it.

## Browser profiles [#browser-profiles]

A profile is Chrome's user data directory at `~/.prized/browser/<name>` on the box (`default` when you name none): sign-ins, cookies and extensions persist across restarts and ride a [snapshot](https://prized.dev/docs/boxes#snapshots). Names use letters, digits, `-` and `_`, up to 64 characters.

* Starting the browser with a different profile replaces the running window.
* Starting it again with the same profile and a URL opens that page as a new tab.

## Pause and resume [#pause-and-resume]

The desktop is processes, not disk: Nano through Small boxes hibernate and bring it back as it was; Medium and larger stop clean, so the tab starts a fresh desktop on resume. Files, packages and profiles survive either way ([Pause and resume](https://prized.dev/docs/boxes#pause-and-resume)).

> A running desktop may count as activity for [auto-pause](https://prized.dev/docs/boxes#auto-pause) even with nobody connected. If you rely on auto-pause, stop the desktop when you are done.

## Security [#security]

* **Loopback only.** The VNC server listens on the box's loopback; nothing new is reachable from the internet.
* **A random password per start**, kept only on the box in a file only your user can read. The dashboard uses it for you; `--no-open` and `--json` print it, the default output shows only the forwarded `vnc://` address.
* **The VNC port** (5910 for the desktop, 5911 for the browser) appears in `prized ports` like any listener, but needs no mirroring: the desktop command forwards it itself.

## Limits [#limits]

* VNC, not video: a responsive desktop for editors, terminals and browsing, not full-motion video. No audio.
* Fixed 1920x1080, scaled to your window. No GPU on any box size.
* No GUI automation agent. For scripts, `DISPLAY=:10 xdotool …` targets the desktop, `DISPLAY=:11` the browser window.
* One desktop and one browser window per box.

## Troubleshooting [#troubleshooting]

| Symptom                                      | What to do                                                                                                         |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `desktop install failed`                     | On the box, `cat ~/.prized/desktop/install.log` names the cause (network, or a held apt lock); open the tab again. |
| A black screen after connecting              | The session is still starting; if it stays black, **Stop desktop** and open again.                                 |
| `the box refused the VNC password`           | A stale password after a restart; open the tab again.                                                              |
| No Chrome window in browser mode             | `cat ~/.prized/desktop/browser-session.log` on the box; a profile in use by another Chrome blocks a second one.    |
| Shortcuts go to your own browser             | Use full screen; Cmd/Ctrl+W, Cmd/Ctrl+T and the like always stay with your browser.                                |
| `prized desktop` says the box is unreachable | Same tunnel as `prized ssh`: run `prized doctor`.                                                                  |