Desktop

The Desktop tab shows a running machine's graphical desktop in the console. It is a VNC session carried over a WebSocket and drawn in the page by noVNC: you see the screen, and your mouse, touch, and keyboard drive it.

The desktop is VNC first. Machines whose image or host has no graphical desktop yet answer 503 desktop_unavailable, and the tab says so; use the web terminal for those.

Who can open it

A desktop is full machine access, so it is allowed like the web terminal: Owner, Admin, and Operator members. Viewer and Billing members get 403 forbidden. Up to 4 viewers can watch one machine at a time.

In the console

Open a machine and choose Desktop, then Connect. The status line shows the remote screen size once the VNC session starts, and focus moves to the screen.

• Disconnect ends the session; Reconnect opens a new one. Nothing on the machine stops when you disconnect.
• View only stops sending your mouse and keyboard; you only watch.
• Scale to fit shrinks the remote screen into the panel. Turn it off to see it at 1:1 and scroll.
• Resize remote to window asks the machine's VNC server to match the panel's size, so nothing is scaled. The machine applies it if its desktop allows resizing.
• Full screen shows only the desktop; press Escape to leave.
• Send keys sends combinations your computer keeps for itself: Ctrl+Alt+Del, Ctrl+Esc, Alt+Tab, Alt+F4, the Super (Windows) key, Escape, Tab, and Print Screen. Under Workspaces it also sends the desktop's own shortcuts: Workspace 1 to Workspace 4 (Ctrl+Alt+1 to 4), Next workspace and Previous workspace (Ctrl+Alt+Right and Left), and Open launcher (Super). Use these when pressing the shortcut yourself does nothing; on a Mac, for example, Ctrl+Option+2 reaches the machine as a plain "2".

While the desktop has focus, every key goes to the machine. Shift+Escape moves focus back to the controls.

Full page in its own tab

Open in new tab on the Desktop tab, Desktop in a machine's row menu on the Machines page, and Desktop at the top of a machine's overview all open the desktop full page in a new browser tab: only the remote screen, edge to edge, with no console around it. It connects as soon as it opens and scales the screen to fit. The tab is titled with the machine's name, such as "agent-primary — Desktop".

A small handle on the left edge opens the controls: Send keys, Clipboard (send text or your clipboard to the machine, and copy what the machine copied), Full screen, View only, Reconnect, Disconnect, and Back to machine. Shift+Escape moves focus from the remote screen to the handle. While it connects you see "Connecting to the desktop…"; if that takes more than about 10 seconds the page says why it may be slow and offers Reconnect and Back to machine. A dropped connection reconnects on its own, as on the tab. The Desktop tab keeps working as before; both can be open at once.

Browser mode

Browser (next to Open in new tab, in the row menu, and at the top of the overview) opens the same full page showing only the machine's web browser, with no desktop shell around it. The page asks for it with mode=browser on the desktop WebSocket, and opens only when the server confirms browser mode. A machine whose image or host can't stream the browser on its own (503 browser_unavailable, or a host that ignores the mode) shows "Browser mode isn't available on this machine" with a link to the full desktop, whose web browser is in the app launcher.

Opening apps

Applications start from the desktop itself: click the apps-grid icon at the left of the top bar, or press the Super (Windows) key (or Send keys › Open launcher if your computer keeps that key), then type to search, for example "chrom" for the web browser, and press Enter. Arrow keys move through the list and Escape closes it. Apps open maximized under the top bar. Machine images whose desktop has no launcher yet open apps from the right-click menu instead.

From the Machines page

The row menu (⋯) of each machine offers Desktop and Browser (each in a new tab), Terminal, Files, and Copy SSH, next to Open overview, Run command, Start or Stop, Copy ID, and Delete. Desktop and Browser are disabled with "(Machine is not up)" while the machine isn't running, and for roles that can't open a desktop. Copy SSH copies the ssh command once an SSH key is installed and the machine's region has an SSH gateway; otherwise it says which is missing.

Clipboard and typing

• Text for the remote machine: Type it sends the text as keystrokes, which works in any application and from a phone keyboard. Send to remote clipboard puts it on the machine's clipboard to paste there; VNC clipboards carry Latin-1 text unless the server supports more. Paste my clipboard sends your clipboard directly, if the browser lets the page read it.
• Remote clipboard shows text copied on the machine; Copy to my clipboard copies it to yours.

On phones

The panel keeps the remote screen's shape at narrow widths. Tap to click, and use Type it for text. View only is useful for watching a long job.

Latency

Every frame and keystroke travels from your browser to the control plane, on to the machine's host, and back, so expect a delay comparable to the round trip to the machine's region plus a few frames of encoding. Typing and pointing are fine for administration, installers, and checking a GUI test; video and fast animation are not smooth. Scaling a large remote screen down costs your browser some work; Resize remote to window avoids it.

Security model

• A ticket, no VNC password. The console mints a single-use ticket with your browser session and CSRF token (POST /v1/machines/{machine_id}/desktop/tickets). It works once, within 30 seconds, for that machine and that session. The WebSocket (GET /v1/machines/{machine_id}/desktop?ticket=…) also checks your session cookie and that the page is on the console's configured address. The VNC server on the machine is reached only through this bridge, so it has no password of its own; if one ever asks for a password, the console refuses and reports it.
• The console records nothing. It relays the screen and your input to the machine without storing or logging them.
• Your role decides. Role changes apply to the next connection.

Status and errors

Protocol

After the upgrade the server sends one text message, {"type":"opened","width":1280,"height":800}. Add mode=browser to the WebSocket query (GET /v1/machines/{machine_id}/desktop?ticket=…&mode=browser) for browser mode; the server confirms it with "mode":"browser" in opened, and the default desktop needs no parameter. From then on binary messages are raw RFB (VNC protocol) bytes in both directions. Other text messages are JSON control from the server: {"type":"closed","reason":"…"} is final (idle_timeout, machine_stopped, deleted, replaced, runtime_unavailable, shutdown, limit, normal, or revoked when the organization was suspended), and {"type":"error","code":"…"} reports a problem. The remote screen is resized inside RFB (SetDesktopSize), not with a control message.

The desktop routes are not in the API reference yet; they follow the web terminal's ticket flow and errors.