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 is running, and drag files from your laptop onto it. The main 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. You see every page they visit as it happens and can step in to enter a password, solve a captcha or 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 myapp prints the link and opens it in your browser.
  • Link. https://app.boxd.sh/desktop/<machine>. An agent on the machine gives you this link when it starts a browser session.
  • SDK. Every machine carries it: machine.access.desktopUrl in TypeScript, machine.access.desktop_url in Python. Use it when a script creates a machine and needs 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 you can build the link:
You need to be signed in to the console in that browser as the machine’s owner, or as any member of the organization when the machine is shared. A machine on standby or hibernated is woken on open, with its windows exactly where they were. You see Starting desktop… for a moment, because the desktop view takes a few seconds to come up after the machine wakes. 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 machines created from a snapshot keep their source machine’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, use the arrow keys to move between tiles, press Enter to launch and Esc to close. Three apps are always there: Anything else with a desktop entry on the machine, such as an editor, a design tool or 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 a window to the front, and click ✕ to close it. 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 laptop releases any held modifier on the machine, so nothing gets stuck.
  • Right-click. It goes to the machine, not your browser.
  • Clipboard. Text copied on the machine pastes on your laptop. Text copied on your laptop 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 is no letterboxing. Resize the window and the desktop resizes with it.

​
Upload by drag and drop

Drag files or whole folders from your laptop 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, such as Uploading report.pdf (2/7)…, and where the files ended up. 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 is open elsewhere, in another tab or on another laptop, 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. Nothing changes on the machine. Windows and apps keep running and are there when you open the desktop again.
  • Standby and hibernation. Both preserve the desktop and its windows.
  • Stop or reboot. Either 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. 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.
While it is up, the desktop takes about 200 MB of the machine’s memory. It takes none when it isn’t running, and it doesn’t start at boot. An open Desktop view keeps the machine awake for as long as it is open. A dormant desktop doesn’t.

​
Limits

  • Drag and drop. Up to 500 files per drop and 1 GiB per file.
  • Input. Mouse and keyboard only, with no touch.
  • Clipboard. Text only.
  • Not included. Audio, microphone and webcam, printing, minimize and maximize, and a taskbar.

​
Drive it from code

browser.launch() in an automation opens a Playwright-controlled browser on this same desktop, with a clean profile on every launch, 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 on the machine with boxd-desktop-launch '<command>'.