Skip to Content
Vm ManagementBrowser VM console

Browser VM console

The OpenFactory console includes a noVNC-based browser display for running virtual machines. It can show boot output and graphical desktops and forward keyboard and pointer input without exposing a raw VNC port to the browser.

Open a console

Open a running VM from the topology or VM list, then choose Console. The UI authorizes the WebSocket for the current user and VM before proxying it to the host-local VNC endpoint.

There is no documented stable deep-link contract for a console dialog. Use the VM controls in the application rather than constructing a URL.

Available controls

The current desktop console provides:

  • keyboard and mouse input;
  • an on-screen keyboard;
  • Ctrl+Alt+Del;
  • fit-to-viewport scaling;
  • reconnect;
  • fullscreen; and
  • close.

The mobile view provides touch pointer controls, left/right click, a joystick, and the device’s software keyboard. Mobile VNC is view-only at the noVNC layer; the separate mobile controls send input.

Clipboard synchronization, selectable quality modes, guest-driven resolution changes, audio controls, arbitrary special-key menus, and a serial-console UI are not part of the current VNC component. Do not rely on those behaviors.

Connection states

The dialog distinguishes connecting, connected, reconnecting/booting, and disconnected/error states. A successful WebSocket handshake can occur before the guest has drawn its first non-black frame, so the console shows a booting overlay and retries with a bounded backoff.

If the VM has no VNC display, is stopped, is missing, or another exclusive session prevents connection, the backend closes the WebSocket with a specific reason and the dialog presents a retry or error state.

Security boundary

  • The production browser connection uses an authenticated WebSocket over TLS.
  • The backend verifies VM access before opening the VNC proxy.
  • The proxy connects only to the VNC port resolved on the virtualization host.
  • Closing the browser dialog ends that browser session; it does not stop the VM.

Console access is equivalent to physical access to the guest display and keyboard. Avoid exposing secrets on screen, lock the guest when finished, and close consoles you are not using.

Troubleshooting

Connected but black

The guest may still be booting. Wait for the boot overlay before forcing a reconnect. If no frame appears after the retry window, confirm that the VM is running and has a VNC graphics device.

Input does not reach the guest

Click the viewport to focus it. On mobile, use the console’s explicit pointer and keyboard controls. If the guest is locked, send Ctrl+Alt+Del where the guest OS supports it.

Repeated disconnects

Close another console session for the same VM, verify the VM is still running, and retry. Persistent failures should be reported with the VM ID, timestamp, connection state, and displayed error; never include session tokens.

Slow display

Reduce the guest’s display resolution and check host/network load. The current component always uses fit-to-viewport scaling and does not expose a quality selector.

Network Topology