Files
cozystack/packages
Aleksei Sviridkin b18281ef0c feat(dashboard): serial console for virtual machines, and paste into the VNC console (#4356)
## What this PR does

Adds a serial console tab to the VM detail page, and makes the VNC
console accept a paste.

Moving text into a VM was the starting point, and the two consoles
answer it very differently. The VNC console carries pixels and key
events and nothing else, so a paste there has to be typed, one emulated
key press per character. The serial console carries text, so a paste is
a single write and the guest's output is real text the user can select
and copy.

Measured on a running VM, 1000 characters, checked by piping the pasted
string through `md5sum` in the guest and comparing with the digest
computed locally:

| | time | integrity |
| --- | --- | --- |
| serial console | **0.87 s** | digest matched |
| VNC, 25 ms per key event | 56.6 s | digest matched |
| VNC, no pacing | 10.3 s | **characters dropped and reordered** |

The VNC rows were taken by driving the typing loop directly rather than
through a real keypress, so they measure the typing and not the
shortcut. The pacing is the measured floor either way: with none, the
guest loses and reorders characters.

### Serial console

New tab backed by KubeVirt's `virtualmachineinstances/console`
subresource and xterm.js. A VM's tabs now lead with its two consoles —
serial first, labelled Console, with VNC beside it — because reaching a
console is why people open a VM. VNC keeps its place: the serial port
does not reach a desktop session, a bootloader, or a Windows guest, and
Windows guests are supported here, down to their own scheduling in the
VM charts.

Copy stays on the terminal's own chord, Ctrl+Shift+C or Cmd+C, so a
plain Ctrl+C still interrupts the foreground process. Paste needed one
thing handled, and only off a Mac: xterm turns Ctrl with a letter into a
control byte and cancels the keydown, so Ctrl+V never reached the
browser's paste and the guest received SYN (0x16) instead. Reproduced on
a real terminal, where the shortcut put a single `0x16` on the wire and
nothing else. The key handler now returns that chord to the browser, at
the cost of the terminal's quoted-insert. On a Mac the browser pastes on
Cmd+V, so there the terminal keeps the key.

One detail worth knowing before touching this code: virt-api negotiates
the `plain.kubevirt.io` subprotocol and reads **binary frames only**. A
text frame is accepted by the socket and then silently dropped, which is
indistinguishable from a dead console. That is why the stream is a small
module of its own with its own tests, rather than xterm's stock attach
addon, which sends text.

### Paste in the VNC console

The graphical console still matters where the serial port cannot reach —
a desktop session, a bootloader, Windows — so a paste works there too,
typed key by key.

**The shortcut is the platform's own: Cmd+V on macOS, Ctrl+V everywhere
else.** That means Ctrl+V no longer reaches the guest on Linux and
Windows, where it is visual block in vim or the guest's own clipboard.
Taking both chords bought nothing, because no browser pastes on Ctrl+V
on a Mac, and cost the guest a key it has its own use for.

Nothing is added to the interface: the toolbar's existing status line
reports `Pasting 12/270` while the text goes in, then returns to the
connection state.

Four constraints shaped the rest, each found by running it rather than
by reading:

- `navigator.clipboard.readText()` puts a permission prompt in front of
**every** paste. Instead the shortcut moves the focus to a hidden field
and lets the browser paste into it, which costs nothing and asks
nothing.
- noVNC calls `preventDefault()` on keydown. Letting the shortcut reach
it would cancel the browser's paste outright, so the shortcut is taken
on the capture phase and only its propagation is stopped. If no paste
follows, the focus returns to the console instead of being parked in an
invisible box.
- The paste starts while the user is still holding the chord, and noVNC
told the guest that modifier is down the moment it was pressed. Typing
into that state sends chords rather than characters — under Ctrl an `m`
is Return — so the host's modifiers are released before the first
character. On Windows noVNC sits on the first Ctrl for 100 ms and
delivers it on a timer, after that release has already happened, so the
release is sent once more when the pacing has covered that window.
- A character the keymap cannot produce changes what the rest means, and
the newline after it still submits: `rm -rf /srv/данные` would become
`rm -rf /srv`. Nothing is sent unless the whole paste can be typed, and
the toolbar says how many characters were in the way.

The keymap covers US only. A guest in another layout is the case the
serial console answers, where text travels as bytes and no layout is
involved.

### Screenshots

The serial console on a running VM: the tabs lead with it, the terminal
is live, and the middle line was pasted from the browser clipboard.

<img width="2252" height="1606" alt="cozystack-serial-console"
src="https://github.com/user-attachments/assets/6fac5f95-c142-405b-9b54-8ed040d65167"
/>

### Downstream repositories

- [x] No downstream repository is affected by this change
- [ ] [cozystack/website](https://github.com/cozystack/website) -
follow-up:
- [ ]
[cozystack/terraform-provider-cozystack](https://github.com/cozystack/terraform-provider-cozystack)
- follow-up:
- [ ]
[cozystack/ansible-cozystack](https://github.com/cozystack/ansible-cozystack)
- follow-up:
- [ ] [cozystack/ccp](https://github.com/cozystack/ccp) - follow-up:
- [ ] [cozystack/talm](https://github.com/cozystack/talm) - follow-up:
- [ ] [cozystack/cozyhr](https://github.com/cozystack/cozyhr) -
follow-up:
- [ ] [cozystack/cozy-proxy](https://github.com/cozystack/cozy-proxy) -
follow-up:
- [ ]
[cozystack/cozystack-telemetry-server](https://github.com/cozystack/cozystack-telemetry-server)
- follow-up:
- [ ]
[cozystack/external-apps-example](https://github.com/cozystack/external-apps-example)
- follow-up:
- [ ] [cozystack/examples](https://github.com/cozystack/examples) -
follow-up:
- [ ] [cozystack/community](https://github.com/cozystack/community) -
follow-up:

<!-- The diff touches only packages/system/dashboard/images/console.
Walked the trigger map in
docs/agents/contributing.md file by file: no entry matches a
console-only change, and the map
states outright that UI changes belong in this repository, in the same
PR. -->

### Notes for the reviewer

- New dependencies: `@xterm/xterm` and `@xterm/addon-fit`. The tab is
split at the route with `React.lazy`, the way the YAML editor already
is, so both land in a 347 KB chunk fetched when a console is opened.
Built both revisions with the same `node_modules`: the entry chunk every
dashboard page loads goes 935.91 KB → 896.39 KB, so it ends up smaller
than before this branch.
- The serial console needs a getty on `ttyS0` in the guest. Cloud images
enable it by default; a Windows guest or a graphical desktop is the VNC
console's job.
- The serial console opens with the user's own identity — nginx forwards
the session's `Authorization` untouched — and
`virtualmachineinstances/console` is already granted next to `/vnc` in
`cozy:tenant:use:base`, so no RBAC change is owed.
- Verified against a live VM on a dev cluster: connection, typing, a
1000-character paste round-tripped through `md5sum` on the serial
console, text typed before the serial socket opens (held and flushed), a
real Ctrl+V on the VNC console arriving intact, and two pastes in quick
succession (the second is refused rather than interleaved).
- The Windows modifier path is read from the pinned noVNC in
`node_modules`, not run: there is no Windows host here. The test fake
models that delivery, so the behaviour is at least held by a test.
- There is no cancel affordance for a paste in progress. It stops on its
own when the session drops or the tab is left, and the toolbar then says
how far it got; Reconnect is the manual way out. A length cap is worth
adding separately — at 25 ms per character a large clipboard types for a
long time.
- 418 tests pass; build and typecheck are clean. `eslint .` reports 54
pre-existing problems across twenty files, none of them in the files
this PR touches.

### Release note

```release-note
feat(dashboard): virtual machines gain a serial console tab, where pasting is instant and the output can be selected and copied. The VNC console now pastes the host clipboard on the platform's own shortcut — Cmd+V on macOS, Ctrl+V elsewhere — typing it into the guest on a US keyboard layout; Ctrl+V no longer reaches the guest on Linux and Windows.
```


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Added a serial console for running virtual machines, including
terminal input, output, resizing, reconnection, and connection status.
- Added clipboard paste support to the VNC console with keyboard-layout
handling, progress feedback, and unsupported-character reporting.
  - Added platform-aware paste shortcuts for macOS and Windows/Linux.

- **Improvements**
  - Console content now loads on demand with a loading indicator.
  - Added handling for stopped and unsupported virtual machine states.

- **Documentation**
  - Documented keyboard, clipboard, and console testing behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-09-22 12:39:03 +04:00
..