Skip to content

stream: make voxl the console, keep noVNC as the fallback - #16

Merged
Daviduche03 merged 1 commit into
masterfrom
stream/voxl-console
Nov 5, 2026
Merged

Daviduche03 merged 1 commit into
masterfrom
stream/voxl-console

Conversation

@Daviduche03

Copy link
Copy Markdown
Owner

What

Makes voxl the default console and keeps noVNC as the fallback.

The console was RFB. It was correct, but it moves pixels instead of video, so it capped at 6–8 FPS — the one part of warmbox that did not feel instant. voxl encodes the same X display as H.264 and the browser decodes it with WebCodecs: 60 FPS at 12–99 ms on the same hardware. It also fixes something the VNC path never did — keystrokes reach the guest (voxl injects through XTEST itself).

How the split works

  • /d/<id> probes the guest's :6901/healthz (400 ms) and serves voxl if it answers, noVNC if not.
  • ?classic=1 forces noVNC.
  • An image built before voxl, or a browser without WebCodecs, falls back automatically — no image/host version pairing.
  • Xvnc stays running as both the X server voxl reads and the fallback console.

Notable details

  • libyuv.pc: Alpine ships libyuv's headers and shared object but no pkg-config file, and voxl's build script requires one. The Dockerfile writes it.
  • Origin rewrite: voxl only answers requests whose Origin matches its own host (anti-DNS-rebinding). Everything through the daemon arrives as the dashboard's origin, so the proxy rewrites it to the address it dials. A direct request keeps its real Origin and is still refused — the guard survives instead of being disabled with --allowed-origins *.
  • Password: the same per-VM secret VNC uses, passed in the guest environment rather than on a command line (the kernel cmdline is host-readable; a guest /proc is not).
  • Readiness gates on :6901 when voxl is up, so the first /d/ load does not race it and fall back for no reason.

Test plan

Built and booted the real arm64 Alpine image, then drove it through the daemon:

PASS /d/ chose voxl
PASS ?classic=1 chose noVNC
voxl /healthz through proxy: HTTP 200
screenshot through proxy: HTTP 200
  PNG image data, 1280 x 800

The screenshot returns the actual XFCE desktop (panel, terminal, wallpaper), so capture via MIT-SHM + DAMAGE works under Xvnc. Guest log confirms keymap: 275 keysyms and XTEST pointer.

  • go build ./..., go vet, go test ./... pass
  • deploy/guest/smoke.sh now reports which console was chosen

Caveats (documented in docs/limitations.md)

  • The voxl console needs HTTPS or localhost — WebCodecs requires a secure origin.
  • X11 only; the Omarchy image keeps its noVNC path.
  • The guest image ships a GPL-2 binary (x264), so the image carries that obligation. warmbox itself is unaffected.

The console was RFB: correct, but capped at 6-8 FPS because it moves pixels
instead of video. voxl encodes the same X display as H.264 and the browser
decodes it with WebCodecs — 60 FPS at 12-99 ms on the same hardware — and,
unlike the VNC path, its keystrokes actually reach the guest.

The guest image now builds voxl from the published crate and starts it beside
Xvnc, so the fallback costs one idle process and adds no new failure mode: an
image built before voxl, or a browser without WebCodecs, still gets noVNC.
/d/ picks whichever console answers and ?classic=1 forces the fallback.

- deploy/guest: a voxlbuild stage (glibc-free: it links x264, libyuv, Opus and
  libpulse), runtime libs on desktop images only, and a pkg-config file for
  libyuv, which Alpine installs without one.
- deploy/guest/init: voxl on :6901 with the same per-VM password as VNC, in the
  environment rather than on a command line. Readiness now gates on it when it
  is up, so the first /d/ load does not race it.
- internal/api: /voxl/<id>/ proxies the page, websocket, screenshots and /wait.
  It rewrites Origin, because voxl only answers its own origin and every request
  through the proxy arrives as the dashboard's; a direct request still keeps its
  real Origin and is refused.

Verified end to end on an arm64 Alpine image: the desktop boots, /d/ selects
voxl, ?classic=1 selects noVNC, and /screenshot returns the real 1280x800 frame.
@Daviduche03
Daviduche03 merged commit 9cae09f into master Nov 5, 2026
6 checks passed
@Daviduche03
Daviduche03 deleted the stream/voxl-console branch November 5, 2026 20:45
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