Quick Browser-Based Remote Desktop (x11vnc + noVNC)

Lightweight alternative to Sunshine/Moonlight when you need to view the desktop in a laptop browser — no client install, no pairing, zero config beyond apt packages. Useful for quick admin tasks, one-off desktop viewing, or when Moonlight isn't available on the client.

When to use

View the desktop from a laptop browser (Chrome, Firefox, Safari)
No client software allowed/available on the remote machine
Quick one-off access — don't need persistent pairing or low-latency game streaming
User says "I need to see my desktop in my browser"

Setup (one-time)

sudo apt-get install -y x11vnc websockify novnc

Launch (run each time)

# 1. Kill any stale processes from previous runs
pkill x11vnc 2>/dev/null
pkill websockify 2>/dev/null
sleep 1

# 2. Share the existing display via VNC (no password, shared)
#    -noxdamage fixes black screen with noVNC
#    -scale 1920x1080 downsamples 4K for browser performance
x11vnc -display :0 -forever -shared -nopw -noxdamage -scale 1920x1080 &

# 3. Use the official noVNC launcher (handles websockify bridge internally)
/usr/share/novnc/utils/novnc_proxy --listen 6800 --vnc localhost:5900 --web /usr/share/novnc &

IMPORTANT: Using the official novnc_proxy launcher is preferred over raw websockify. It starts its own internal websockify, serves noVNC files, and handles the WebSocket handshake correctly. It serves vnc.html (the full noVNC client) at the root, not just vnc_lite.html.

Verify

# x11vnc listening (port 5900)
ss -tlnp | grep 5900

# novnc_proxy listening (port 6800, 0.0.0.0 = accessible from LAN)
ss -tlnp | grep 6800

# noVNC serving
curl -s -o /dev/null -w "%{http_code}" http://localhost:6800/vnc.html
# Expect: 200

Client URL

Open in laptop browser:

http://<server-ip>:6800/vnc.html

The novnc_proxy launcher auto-fills the WebSocket connection parameters — no query params needed. Example: http://192.168.50.98:6800/vnc.html

Teardown

pkill x11vnc
pkill websockify
pkill -f novnc_proxy

Pitfalls

UFW blocks port 6800 by default. If the client browser says "site can't be reached," open the port: sudo ufw allow 6800/tcp.
Black screen in noVNC. If noVNC connects but shows only black (no desktop), first check whether it's a VNC encoding issue or the GPU framebuffer itself is black. Take an X11 screenshot to distinguish: DISPLAY=:0 xwd -root -out /tmp/screen.xwd && convert /tmp/screen.xwd /tmp/screen.png. If the screenshot is all-black (tiny file, ~1.3KB for any resolution), the GPU isn't rendering anything — check DRM connector state: for c in /sys/class/drm/card*-HDMI-*/; do echo "$(basename $c): $(cat $c/enabled) dpms=$(cat $c/dpms)"; done. If enabled=disabled and dpms=Off, the display is in a kernel-level DPMS lockup and only a reboot will fix it (see references/debug-black-screen.md for full workflow). If the screenshot shows the desktop but noVNC shows black, it's a VNC encoding issue — add -noxdamage to x11vnc. XDamage can fail to track on 4K displays and with compositing enabled.
4K display kills browser performance. Streaming a native 4K (3840x2160) framebuffer over noVNC is extremely heavy for the browser. Always downsample with -scale 1920x1080 (or -scale 1280x720 for slower connections). The x11vnc -scale flag handles this server-side.
Use novnc_proxy, not raw websockify. The Debian novnc package includes /usr/share/novnc/utils/novnc_proxy — a wrapper script that manages websockify internally, serves the full vnc.html client, and handles auto-connect better than the raw websockify --web=... command.
websockify binds 0.0.0.0 by default — accessible from LAN. No auth on this setup; only use on trusted networks.
x11vnc -nopw means NO password. Anyone on the LAN can connect to port 5900 directly. Acceptable for quick local use; don't leave running.
Contrasts with Sunshine/Moonlight: This is pure software encode (no NVENC), higher latency, higher CPU usage. Fine for desktop viewing; terrible for gaming.

4.1 KiB Raw Blame History