Use the desktop console

The desktop console shows a Box's virtual display (1920×1080) and sends your keyboard and mouse to it, like a monitor plugged into the machine. The Dashboard streams it over VNC through an authenticated relay to the Box's host, so it needs no tunnel, SSH key or working network inside the Box. It also works while the Box boots and when SSH does not, which makes it the place to look when a Box will not become ready. With the private network connected, a native VNC client can open the same display.

Before you beginCopy Anchor Link

• A Dashboard sign-in at https://app.cubicle.sh. Only the Dashboard opens the browser console; the CLI, the SDK and API keys cannot.
• An explicit grant on the Box. The owner and admin roles alone are not enough. See Grant access to a Box.
• A running Box.
• For the best keyboard support, a Chromium-based browser such as Chrome or Edge. See Keyboard.

DesktopsCopy Anchor Link

Both base images start a desktop on the Box's display and sign in to it automatically.

• omarchy is the image's built-in default password, the same on every Omarchy Box.
• Both desktop accounts have passwordless sudo.
• The desktop account is not your SSH guest account (jv_…). Files you create over SSH or exec belong to your guest account.
• These accounts come from the base image. A Box created from a snapshot keeps the accounts of the Box the snapshot was taken from.

Open the consoleCopy Anchor Link

If the browser refuses full screen, the console stays open in the tab with the message Full screen was unavailable. You can keep using the console here. The Full screen button tries again.

Console controlsCopy Anchor Link

The display scales to fit the window.

KeyboardCopy Anchor Link

In full screen, Chromium-based browsers capture the keyboard, so browser shortcuts go to the Box instead of the browser. Other browsers do not support capture and show Keyboard capture is unavailable. Browser shortcuts may still act locally. If you decline the browser's prompt, the console shows Keyboard capture was denied. Browser shortcuts may still act locally. The Super+Space button still works.

ClipboardCopy Anchor Link

The clipboard carries text only. Files and images are not transferred.

• Box to your computer: copy text in the Box, open Clipboard, then select and copy the text that appears in the Text field.
• Your computer to the Box: open Clipboard, paste or type into Text, click Send to Box, then paste in the Box.

Shared displayCopy Anchor Link

There is one display per Box. Everyone viewing it, in the browser or a native VNC client, sees the same screen and controls the same keyboard and mouse.

A console connection also closes when the Box stops, hibernates or is started again, and when your grant, membership or login ends. Adding or removing one of your SSH keys updates your guest account on each Box, which also closes your open consoles. The console then shows Disconnected. Open Console from the Dashboard to reconnect. Click Console again to reconnect.

Check console readinessCopy Anchor Link

Every Box reports console.ready and a reason, separately from ssh.ready. The console is ready as soon as the Box's virtual machine runs and its display exists, before SSH is ready.

const info = await cubicle.boxes.get("acme/job-1")
console.log(info.console)
// => { ready: true, reason: null }

cubicle boxes get acme/job-1 and GET /v1/boxes/{box} return the same console field.

When you open the console, the Dashboard also checks your own access and can refuse with user_disabled, membership_inactive or grant_inactive.

Connect with a native VNC clientCopy Anchor Link

With the private network connected, a VNC client on your computer can open the same display.

The VNC connection has no password. Gateway's permission for your device and your grant on the Box are the only check, and the Box must be routed (running, with a grant) and its console ready. Port 5900 on a Box always leads to this display, so a service of your own on port 5900 in the Box is not reachable over the private network.

TroubleshootingCopy Anchor Link

Console requires an explicit grant on this BoxCopy Anchor Link

The Console button is disabled because you hold no grant on the Box. An owner or admin adds one in the Box's details, on the Access tab, or with cubicle grants add acme/job-1 USER_ID; see Grant access to a Box.

Console unavailable: <reason>Copy Anchor Link

The Console button is disabled because console.ready is false. Look up the reason in Check console readiness. For not_requested and restart_required, start the Box with the play button or cubicle boxes start acme/job-1.

Console is not ready: <reason>Copy Anchor Link

The Box or your access changed between loading the page and opening the console. The reason is one of the console.reason values or user_disabled, membership_inactive or grant_inactive.

Close an existing VNC viewer before opening anotherCopy Anchor Link

You have 8 browser consoles open. Close one, in any tab, wait a few seconds and try again.

Disconnected. Open Console from the Dashboard to reconnect.Copy Anchor Link

The connection closed: the Box stopped, hibernated or was started again, your access changed, or 8 hours passed. Close the console and click Console again.

RelatedCopy Anchor Link

• SSH into a Box: a shell as your own guest account.
• Reach a Box over the private network: the tunnel that native VNC uses.
• Box lifecycle: readiness, generations and restarts.
• Organizations and access: who can open a console.
• Troubleshooting: errors shared with other pages, such as sign-in and permissions.