Skip to content

Serve a screen to VNC clients with gliff-server --vnc - #133

Open
avillagran wants to merge 9 commits into
omacom:mainfrom
avillagran:feat/vnc-server-pr
Open

avillagran wants to merge 9 commits into
omacom:mainfrom
avillagran:feat/vnc-server-pr

Conversation

@avillagran

@avillagran avillagran commented Nov 11, 2026 •

Copy link
Copy Markdown

Stacked PR. This builds on #102 (placing a headless output with --position). Only the four commits from daea039 on are new here. Once #102 lands, the diff shrinks to them.

The problem

An old tablet or laptop is a perfectly good extra screen, but it cannot run gliff. Almost every device can run a VNC viewer, though.

What this adds

  • gliff-server --vnc ADDR --headless --size WxH adds a screen of that size beside the others and serves it to VNC clients until it is stopped.
    • --scale, --position and --align work as they do for a gliff session.
    • --output NAME serves an existing screen instead of a new one.
    • Windows move onto the new screen like onto any monitor, and the device's touch screen, mouse and keyboard control them.
  • The screen lasts as long as the server. A client that sleeps or drops comes back to the same windows. SIGINT, SIGTERM and SIGHUP give the screen back.
  • A new crate, gliff-vnc, holds the protocol and does no I/O beyond the stream it is given, so each part is tested on its own:
    • Handshake: RFB 3.3, 3.7 and 3.8, with VNC Authentication or none. The DES response is checked against OpenSSL.
    • Pixel formats: 8, 16 and 32-bit true colour in either byte order, and 8-bit colour maps, which get a 3-3-2 map.
    • Encodings: Raw, Hextile and ZRLE, decoded back in the tests by a separate decoder over desktop-like and random pictures. Only the 16×16 tiles that changed are sent.
    • Keys: a keymap of the server's own gives every keysym a client sends a key, so any character can be typed whatever the local layout.
  • Capture: CaptureConfig::paint_cursors asks the compositor to draw the cursor into the frames, for viewers that cannot draw one. It is off by default, so gliff's own sessions are unchanged. Frames are captured only while a client is connected and only when the screen changes.
  • Keeping the mode: a Hyprland config reload drops the monitor rule that set a headless output's mode, and Omarchy reloads when a monitor comes or goes. The server checks the mode every two seconds and sets it back.
  • setup_output takes the mode to start in, so the VNC screen starts at its own size and scale.

Screenshots

Taken from a test laptop running Hyprland.

The server starting a 1024x768 screen on the right of the laptop's own and serving it on 127.0.0.1:5906. This run uses --vnc-no-password for the shot, which the server warns about.

gliff-server --vnc log

That screen in TigerVNC's viewer, with a terminal opened on it.

The headless screen in a VNC viewer

Security

  • A password is required, from --vnc-password-file or GLIFF_VNC_PASSWORD, unless --vnc-no-password is given.
  • A wrong password waits two seconds before it is refused.
  • One client is served at a time, and a new login takes over from the previous one.
  • docs/vnc.md says plainly that VNC Authentication uses only the first 8 characters of the password and does not encrypt the session. It advises keeping the port to your own devices or behind an ssh tunnel.

Testing

  • scripts/check.sh passes, with the protocol tests in gliff-vnc. Eight combinations of protocol version, encoding and pixel format decode back pixel for pixel: 786,432 of 786,432 pixels match.
  • By hand, on a Hyprland laptop serving a headless screen:
    • gvncviewer showed it live over ZRLE. A full 1024x768 ZRLE update was 135 KB and took 35 ms.
    • The pointer landed where it should.
    • Clicks and the scroll wheel worked, and so did Ctrl+D.
    • Typing Hola ñandú AÉ!? 123 ~/{x} and acción € came out as typed.
    • A wrong password waited about 2.5 s before it was refused.
    • A second client took over from the first.
    • SIGTERM gave the screen back.
    • --output eDP-1 served the built-in screen.
  • An iPad 2 on iOS 8 used the screen through noVNC in Safari, which is the tablet PR's set-up.
  • Restoring the mode: unplugging an HDMI monitor made Omarchy reload, which reset the output to 1920x1080 scale 2. The server set it back; a test output was restored in 0.14 s.

A headless output always went where Hyprland found room. --position puts
it right, left, above or below this machine's screens, and --align lines
it up with their top or left edges (start), their middles, or their
bottom or right edges (end). The position is worked out from the other
screens' layout each time the output's mode is set, so a resize keeps
it in place beside them.
The position comes from the output's logical size, which resize
computed with the requested scale. When Hyprland applies a rounded
scale instead, place the output again at that scale, so it still meets
the other screens on the chosen side and lines up as asked.
Hyprland places a screen whose position is `auto`, as Omarchy's default
configuration does, after every screen with a fixed one. A fixed
position for the headless output therefore pushed such a screen aside:
on a laptop asked for `--position right`, the laptop screen moved right
of the new output. When placing the output moves another screen, the
placement goes to Hyprland's `auto-right`, `auto-center-right` and
related positions instead. They line up at the start or the center of a
side, so `--align end` is centered there, with a warning.
CaptureConfig::paint_cursors asks the compositor to draw cursors onto
the captured frames (ext-image-copy-capture's paint_cursors option), for
a viewer that cannot draw a cursor of its own. It is off by default, so
the gliff session, which sends the cursor separately, is unchanged.
gliff-vnc holds the RFB protocol for serving a Hyprland output to VNC
clients, kept apart from any I/O beyond the stream it is given so each
part can be tested on its own:

- the handshake for RFB 3.3, 3.7 and 3.8, with VNC Authentication
  (DES challenge-response, checked against OpenSSL) or none;
- every pixel format a client may ask for: 8, 16 and 32-bit true colour
  in either byte order, and 8-bit colour maps, which get a 3-3-2 map;
- the Raw, Hextile and ZRLE encodings, decoded back in the tests by a
  separate decoder over desktop-like and random pictures;
- which 16x16 tiles changed since the client was last sent them;
- a keymap of the server's own on which each keysym a client sends has a
  key, with modifiers kept as modifiers and keys reused least recently
  typed first, so any character can be typed whatever the local layout.
`gliff-server --vnc ADDR --headless --size WxH` adds a screen of that
size beside the others (`--scale`, `--position` and `--align` as for a
gliff session) and serves it to VNC clients until stopped, so a device
with any VNC viewer, however old, becomes one more screen of this
machine. `--output` serves an existing screen instead.

The screen lives as long as the server: a client that sleeps or drops
comes back to the same windows. One client is served at a time, and one
that logs in takes over from the previous one; a wrong password waits
two seconds before it is refused. A password is required, from
--vnc-password-file or GLIFF_VNC_PASSWORD, unless --vnc-no-password
says otherwise.

Frames are captured with the cursor painted in, only while a client is
connected, and only once the screen changes; a client's first update
waits for a frame newer than its connection. Updates carry the tiles
that changed. Key events type keysyms through gliff-vnc's keymap, and
pointer events move, click and scroll on that screen.

setup_output now takes the mode to start in, so the VNC screen starts at
its size and scale, and places the output again when Hyprland rounds
the scale. SIGINT, SIGTERM and SIGHUP give the screen back.
A config reload drops the monitor rule that set a headless output's mode, and Omarchy reloads when a monitor comes or goes, which left a tablet's 1024x720 screen at 1920x1080 scale 2. The VNC server checks the mode every two seconds and sets it back.
@greptile-apps

greptile-apps Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[High impact] The latest change appears safe to merge and fixes clicks during temporary headless screen resizes.

Summary

This PR adds gliff-server --vnc and a separate gliff-vnc crate for serving screens to VNC viewers.

  • A VNC viewer can see and control a screen served by gliff-server.
  • Headless screens can start at a chosen size and sit beside other screens.
  • VNC viewers can use several protocol versions and screen formats.
  • VNC keyboard and pointer events control the desktop.

Reviews (3) · Last reviewed commit: "Keep the pointer on the screen the viewe..." · Reviewed by Greptile

Comment thread crates/gliff-server/src/vnc.rs Resolved
Comment thread crates/gliff-vnc/src/proto.rs Resolved
Comment thread crates/gliff-server/src/vnc.rs Resolved
Comment thread crates/gliff-server/src/vnc.rs Resolved
Comment thread crates/gliff-server/src/main.rs Resolved
Comment thread crates/gliff-server/src/vnc.rs Resolved
- Updates go to a writer task per client through a queue of four, each
  write with a 10-second limit; a client that stops reading is dropped
  instead of blocking logins, frames and shutdown. Client messages are
  read ahead through a bounded queue, so reading waits instead of
  growing without end.
- A client's reader and writer tasks stop when it is dropped or
  replaced.
- The client's version line is read as bytes, so a line that is not
  ASCII is refused instead of panicking, and a login slot is given back
  by a guard however the login ends.
- SetEncodings changes only the encoding: the encoder, and the ZRLE
  stream that runs for the whole connection, stay.
- A headless screen keeps the mode it was made with as the one to
  restore after a reload; frames of another size no longer replace it.
- --scale takes a finite value from 0.5 to 4.
@avillagran

Copy link
Copy Markdown
Author

All six findings are addressed in 3f1d7d3: stalled clients, malformed version lines and login slots, the headless mode across reloads, the ZRLE stream across SetEncodings, --scale validation, and reader/writer tasks stopped with their client. scripts/check.sh passes (307 tests), with new tests for the non-ASCII version line, the login slot guard and the scale range.

avillagran added a commit to avillagran/gliff that referenced this pull request Nov 11, 2026
Comment thread crates/gliff-server/src/vnc.rs Resolved
The headless screen's requested mode stays apart, but the pointer's
extent now follows the frame size, so clicks land where the viewer sees
them during the moment a reload holds the screen at another size.
avillagran added a commit to avillagran/gliff that referenced this pull request Nov 11, 2026
avillagran added a commit to avillagran/gliff that referenced this pull request Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant