gliff on Omarchy

gliff on Omarchy

gliff shows another machine's live Hyprland session in a window on yours — over plain SSH, with full 4:4:4 color (crisp text) and GPU-accelerated H.264 end to end. No open ports, no accounts, no relay servers.

TL;DR

omarchy pkg add gliff

Takes ~2 minutes. Install it on both machines — yours (the viewer) and the remote one (the server).

The store listing reports a 6.5 MB download / 16.4 MB installed. MIT-licensed open source, free forever, no paid tier, no account.

Getting started (5 minutes)

1. The mental model.

gliff is two programs: gliff-server runs on the remote machine and captures its Hyprland output (GPU H.264 encode via VA-API), and gliff runs on your machine and shows it in a GTK4 window. The SSH link is the only transport — gliff launches the server over your existing SSH connection, so there's no firewall hole, no NAT headache, and nothing listening on a public port. Both ends must be running Hyprland; this is not a general VNC/RDP replacement.

2. Install on both ends and run gliff-probe first.

# on BOTH machines
omarchy pkg add gliff
gliff-probe

gliff-probe prints PASS/FAIL for the compositor, drivers, and both video paths (GPU and CPU). Run it on both ends before anything else — it tells you immediately whether you'll get the GPU tier (Vulkan + VA-API H.264) or fall back to CPU encoding (OpenH264, works with no extra setup). GPU tier needs, on Arch: vulkan-radeon + mesa (AMD), or vulkan-intel + intel-media-driver (Intel). NVIDIA encode support is new in v0.4.0; anything without a supported driver silently uses the CPU tier.

3. Connect.

Set up passwordless SSH (key auth) first — it makes every launch painless. Then:

gliff user@host              # mirror the remote's focused screen
gliff --output DP-1 user@host  # mirror a named screen
gliff --headless user@host   # a private headless screen that follows your window size

The headless mode is the quiet killer feature: instead of watching the remote's real screen (awkward if someone else is using it), you get your own private display whose resolution tracks your window.

4. The three things everyone needs to know:

• Keyboard capture grabs everything while your pointer is over the picture — including your local Hyprland/WM shortcuts. Press Shift+Esc to release capture and get local shortcuts back. This is the single most confusing behavior on first use.
• Clipboard is bidirectional by default and trusts the remote host. Text, images, and files all sync — and a connected host can read your advertised local clipboard. For untrusted machines, launch with gliff --no-clipboard. Selections marked by password managers (x-kde-passwordManagerHint) are withheld even when sharing is on.
• Quality is adaptive by design: it drops framerate before sharpness, so text stays crisp under a bad link. Screens wider than 4096 px are streamed at reduced size and scaled up — that's a documented limit, not a bug.

5. Config location.

No documented dotfile — behavior is driven by CLI flags (--output, --headless, --no-clipboard, --video, --capture, --server-bin). Treat "settings persist" claims as unverified.

Common issues & fixes

All items below come from the project's README, v0.4.0 release notes, and hardware-quirks doc — none are invented. The repo is young (created 2026-09-12), so the issue tracker is thin; the quirks doc and release notes are the real record.

gliff user@host connects but the window stays black — especially in VMs.

The remote GPU may be allocating capture buffers it never fills (seen with VM virtio-gpu/virgl). v0.4.0 makes shm capture the automatic fallback, and you can pick explicitly with --capture.

Fix: Force shared-memory capture: gliff --server-bin 'gliff-server --capture shm' user@host. (README troubleshooting, releases)

gliff can't find the remote Hyprland session — SSH connects but the server can't locate the compositor.

gliff-server locates the session via XDG_RUNTIME_DIR; SSH sessions sometimes don't carry it.

Fix: Wrap the server launch: gliff --server-bin 'env XDG_RUNTIME_DIR=/run/user/1000 gliff-server' user@host (replace 1000 with the remote user's UID). If gliff-server isn't on the remote PATH at all, give the full path via --server-bin. (README)

Picture is dark or the GPU tier fails on Intel (non-Panther-Lake) or older NVIDIA.

Hardware reality, not a config bug. The hardware-quirks doc records: Intel server support is only confirmed on Panther Lake; pre-Panther-Lake generations are untested; an Intel-specific "dark picture" issue is still under investigation in 0.4.0; NVIDIA encode support only landed in 0.4.0.

Fix: Run gliff-probe on both ends first — if the GPU path fails, the CPU tier (OpenH264) works with no extra setup. Unverified on Omarchy: NVIDIA decode, multi-GPU --render-node selection.

Hyprland cursor weirdness — cursor invisible, or removing a monitor kills the session.

Two documented upstream quirks on Hyprland 0.56.2: shared cursor images are always fully transparent, so gliff falls back to the default pointer (cosmetic); and removing a monitor under a live cursor session aborts Hyprland (SIGABRT, observed 3x) — the server mitigates this by ending the capture thread before removing the headless output.

Fix: Don't hot-unplug monitors mid-session. (hardware-quirks doc)

Clipboard contents leaking to a machine you don't fully trust.

This is the documented trust model, not a bug: "Clipboard sharing still trusts connected hosts by default" — a connected host can read the advertised local clipboard without a local paste.

Fix: Launch with --no-clipboard — mitigations in 0.4.0: password-manager selections are withheld, and requests are restricted to the current offer. Rule of thumb: gliff --no-clipboard for anything that isn't your own box. (release notes)

Pairs well with / If you hate this, try

Pairs well with

• Sunshine (the game-streaming server — use gliff for crisp text work and Sunshine when you want to stream a game to Moonlight on a phone/TV; guide)
• Tailscale/SSH key auth (passwordless SSH makes gliff user@host a one-word affair)
• the Omarchy default bar indicator — Omarchy installs gliff by default now and shows an indicator for active remote sessions

If you hate this, try

• Sunshine + Moonlight — heavier setup (open ports, HTTPS certs), but better for gaming/media and non-Hyprland clients
• wayvnc — native Wayland VNC, any VNC client connects, but softer 4:2:0-ish text and you manage port 5900 + auth yourself
• hypr-rdp/RDP — connects from Windows mstsc, Remmina, FreeRDP, with device redirection, but harder to set up and no 4:4:4 advantage

Comparison: gliff vs similar apps

Verdict: If both machines run Hyprland and you mostly read text (terminals, editors, browsers), gliff wins on simplicity and sharpness — SSH-only, nothing to open. Pick Sunshine/Moonlight for gaming, wayvnc for universal VNC clients, RDP for Windows-client compatibility.