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

# Desktop

> A live, clickable view of any machine's display in your browser - watch an agent browse, take over its keyboard, drop files onto it.

Every machine has a display. **Desktop** opens it in a separate browser window: a real desktop you can watch and control - launch a browser, a terminal, a file manager or any GUI app installed on the machine; type and click into whatever's running; drag files from your computer onto it.

The headline use is watching an agent work. Coding agents on the machine browse the web with the pre-installed [`agent-browser`](/guides/launch-a-browser), and it opens on this desktop, so you see every page they visit as it happens and can step in - enter a password, solve a captcha, fix a form - without stopping them.

## Open it

* **Console** - on the Machines page, open a machine's **Open** menu and choose **Desktop**. It opens in its own window, one per machine.
* **CLI** - `boxd machine desktop mybox` prints the link and opens it in your browser.
* **Link** - `https://app.boxd.sh/desktop/<machine-name>`. An agent on the machine can hand you this link; it's what they're told to do when they start a browser session.
* **SDK** - every machine carries it: `machine.access.desktopUrl` in [TypeScript](/reference/typescript-sdk), `machine.access.desktop_url` in [Python](/reference/python-sdk). Handy when a script creates a machine and wants to hand someone a way to watch it.
* **From inside the machine** - there is no in-machine command for it, but every session carries the machine's name and host, so the link is one line away:

```bash theme={"theme":"github-dark"}
echo "https://app.${BOXD_VM_HOST#*.}/desktop/${BOXD_VM_NAME}"
```

You need to be signed in to the console in that browser, as the machine's owner. A paused or hibernated machine is woken on open - you'll see *Starting desktop… (a sleeping machine may take a few seconds to wake)* for a moment - with its windows exactly where they were. A **stopped** machine isn't started for you; start it from the Machines page first.

<Note>
  Desktop needs the default machine image at a recent version. A machine on a custom image, or created before the desktop shipped, shows the entry greyed out: *Desktop is not available for this machine. Create a new machine to use it.* Forks and snapshot restores keep their source's image, so create a fresh machine from the default image to get it.
</Note>

## Launch apps

Click **Launch** at the top, or press **⌘B** (Ctrl+B). Type to filter; arrow keys move between tiles; **Enter** launches; **Esc** closes.

Three apps are always there:

| App          | What it is                                                                                      |
| ------------ | ----------------------------------------------------------------------------------------------- |
| **Browser**  | The machine's own browser - the same one agents use, with a persistent profile, so logins stick |
| **Terminal** | A shell on the machine                                                                          |
| **Files**    | A file manager - also the drop target for uploads                                               |

Anything else with a desktop entry on the machine - an editor, a design tool, a desktop app you installed - appears with its own icon and name. Terminal-type entries and other Chrome or Chromium installs are left out, since the built-ins cover them. Apps run as the machine's user, with the same access a terminal has.

## Work in it

* **Windows** - drag the title bar to move, drag the right edge, the bottom edge or the bottom-right grip to resize, click to bring to front, **✕** to close. Apps that draw their own title bar keep it.
* **Keyboard** - everything you type goes to the focused window, modifiers included. Only ⌘B/Ctrl+B is reserved. Switching to another window on your computer releases any held modifier on the machine, so nothing gets stuck.
* **Right-click** goes to the machine, not your browser.
* **Clipboard** - text copied on the machine pastes on your computer; text copied on your computer is available on the machine when you focus the desktop window again. Your browser may ask once for permission to read the clipboard.
* **Screen size** - the machine's display follows the size of the window, up to 5K, so there's no letterboxing. Resize the window and the desktop resizes with it.

## Upload by drag and drop

Drag files - or whole folders - from your computer onto the desktop:

* Dropped **on the Files window**, they land in the folder it currently has open.
* Dropped **anywhere else**, they land in the home directory.

Folder structure is preserved. Files upload one after another; if one fails, the drop stops there and what was already uploaded stays. A status pill at the bottom shows progress - *Uploading report.pdf (2/7)…* - and where things ended up. Limits: 500 files per drop, 1 GiB per file; empty files are skipped. There is no download in the other direction - use `boxd machine cp` or the file manager's own tools for that.

## One viewer at a time

A desktop has one viewer. Opening it while it's open elsewhere - another tab, another computer - takes over, and the other view shows **Disconnected** with a **Reconnect** button. Everyone who can open it has full control; there is no read-only mode.

## What persists

* **Closing the window** changes nothing on the machine. Windows and apps keep running, and are there when you open the desktop again.
* **Pause/resume and hibernate/wake** preserve the desktop and its windows.
* **Stop or reboot** ends every desktop window. The desktop comes back on demand - the next time you open the view, or an agent starts a browser - and files on disk are untouched.
* **The browser's profile persists** - cookies and logins survive closing the browser, relaunching it, and crashes. The **Browser** tile, agents, and links opened from a terminal all share one profile.

The desktop uses roughly 200 MB of memory while it's up and nothing when it isn't. It doesn't start at boot. An **open** Desktop view keeps the machine awake for as long as it's open; a dormant desktop doesn't.

## Not included

No audio, microphone or webcam; no printing; no minimize/maximize or taskbar; mouse and keyboard only (no touch). Clipboard sync is text only.

## Drive it from code

`browser.launch()` in an [automation](/guides/automations/browser) opens a Playwright-controlled browser on this same desktop, so a script's browsing is just as watchable as an agent's. GUI apps of any kind can be started onto the desktop from a shell with `boxd-desktop-launch '<command>'`.