Skip to main content
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, 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, machine.access.desktop_url in Python. 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:
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.
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.

​
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: 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 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>'.