Skip to Content
DocsApplicationsRemote AccessnoVNC
noVNC

noVNC

Browser-based VNC access that runs well in modern desktop and mobile browsers

Overview

noVNC is both a VNC client JavaScript library and an application built on top of that library. It runs well in any modern browser, including mobile browsers on iOS and Android.

It is a browser-based VNC client, not a native desktop viewer—access happens through your web browser rather than a standalone app.

Key features

noVNC focuses on simple, browser-based VNC access with QuickBox-managed services and paths.

Browser-first VNC

VNC client JavaScript library that runs in modern browsers, including mobile

Per-user services

Systemd units vnc@username.service and novnc@username.service are created per user

Reverse-proxied paths

nginx locations /username/vnc and /username/websockify map to /srv/novnc and 127.0.0.1:port

Base ports

Base ports are 6080 (web) and 5901 (VNC daemon) with auto-generated flags enabled

When to use it

Choose noVNC when you want browser-based VNC access that QuickBox exposes through user-scoped paths.

You want

  • Need VNC access that works in modern desktop and mobile browsers
  • Want user-scoped web paths like /username/vnc and /username/websockify
  • Prefer per-user systemd services for VNC and websockify

QuickBox provides

  • QuickBox provisions vnc@username.service and novnc@username.service per user
  • nginx serves /username/vnc from /srv/novnc and proxies /username/websockify
  • Dashboard Service Control surfaces live port and service state for noVNC

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find noVNC in the Remote Access category (or search), and click Install. The dashboard streams the install log live and the live noVNC port and status appear in your Application Control panel when it finishes. Reinstall, Update, and Remove are on the same panel.

noVNC pulls a full Xfce desktop, an X server stack, and firefox-esr, so its install takes longer than most apps. What you see is gated by your account: admins manage any user’s apps, regular users manage their own. See App Management for the full flow.

Install from the CLI (automation)

The CLI runs the same script and suits automation:

qb install novnc -u username
qb reinstall novnc -u username
qb update novnc -u username
qb remove novnc -u username

CLI Options

-u, --usernameRequired

Target QuickBox username for install, reinstall, update, and remove actions

Full flag reference: CLI Reference.

Access and authentication

URL / route

Item
Base web port
Details
6080 (auto-generated flag enabled)
Item
Base VNC daemon port
Details
5901 (auto-generated flag enabled)
Item
Port confirmation
Details
Dashboard Service Control shows the current noVNC port

Login / credentials / tokens

  • QuickBox decrypts the QuickBox user password and applies it with vncpasswd during install.
  • HTTP Basic auth for /username/vnc uses /etc/htpasswd.d/htpasswd.username.

Security notes

VNC daemon port access

QuickBox adds iptables rules to accept only localhost traffic on the VNC daemon port and drop other traffic. Access is intended through the nginx paths instead of direct VNC port access.

Configuration and files

Key paths
/
srv/# noVNC client files and utilities
└── novnc/
│ ├── utils/novnc_proxy# WebSocket bridge used by novnc@username.service
│ └── utils/self.pem# Bundled certificate for novnc_proxy
etc/# Service + nginx definitions
├── systemd/system/
│ ├── vnc@username.service# TightVNC display bound to the VNC daemon port
│ └── novnc@username.service# novnc_proxy listening on the assigned web port
├── nginx/conf.d/username.vnc.conf# Websockify proxy for /username/websockify
├── nginx/software/username.novnc.conf# Alias for /username/vnc served from /srv/novnc
└── htpasswd.d/htpasswd.username# HTTP Basic auth for /username/vnc
home/# User session assets
└── username/.vnc/xstartup# Xfce session launcher with autocutsel and startxfce4

Common tasks

FAQ

QuickBox sets a base web port of 6080 and a base VNC daemon port of 5901, with auto-generated flags enabled. The Dashboard Service Control view shows the current assigned noVNC port.
QuickBox outputs the per-user path /username/vnc/vnc.html?resize=remote&host=host&path=username/websockify and maps the nginx locations /username/vnc and /username/websockify to the noVNC client and websockify bridge.
QuickBox sets the VNC password using vncpasswd based on the stored QuickBox user password, and nginx protects /username/vnc using HTTP Basic auth from /etc/htpasswd.d/htpasswd.username.
noVNC installs a full Xfce desktop, an X server stack, and firefox-esr. If the server has apt-listbugs installed, it pauses the apt transaction to show bug reports for those packages and waits for confirmation; when nothing answers, apt exits with a non-zero status (often error code 10) and the install reports a dependency failure. Remove the prompt tool with apt-get -y purge apt-listbugs, then run apt-get update and apt-get -y --fix-broken install, and re-run qb install novnc -u username.
QuickBox locks the VNC daemon port to localhost only with iptables — direct connections from outside the server are dropped. Access noVNC through the browser path /username/vnc, which is reverse-proxied through nginx and the websockify bridge.

Best practices

Do

  • Use the Dashboard Service Control view to confirm the active port and service state for noVNC.
  • Keep /home/username/.vnc/xstartup executable so Xfce launches with autocutsel and startxfce4.
  • Use the /username/vnc path protected by HTTP Basic auth for browser access.

Don't

  • Do not expect direct access to the VNC daemon port; iptables drops non-local traffic to that port.
  • Do not delete /etc/htpasswd.d/htpasswd.username if you rely on HTTP Basic auth for /username/vnc.

Troubleshooting

noVNC install fails or hangs on a dependency prompt

noVNC pulls in one of the heaviest dependency sets of any QuickBox app: it installs a full Xfce desktop, an X server stack, TightVNC, and firefox-esr. On some servers apt stops on an interactive prompt while pulling these packages, which makes qb install novnc appear to hang or fail.

Symptom: install stops at 'Do you want to continue? [Y/n]' or apt-listbugs reports 'error code 10'

This happens when the apt-listbugs package is present on the server. While noVNC installs firefox-esr and the Xfce/X11 packages, apt-listbugs intercepts the transaction, prints any known bug reports for those packages, and waits for you to confirm. If nothing answers the prompt, the apt run exits non-zero (commonly error code 10) and the noVNC install reports a dependency failure.

Fix:
  1. Remove the interactive bug-prompt tool so apt can complete non-interactively: 
    apt-get -y purge apt-listbugs
  2. Refresh the package lists and finish the pending package work: 
    apt-get update
apt-get -y --fix-broken install
  3. Re-run the install: 
    qb install novnc -u username

If you prefer to keep apt-listbugs, you can instead pre-install the dependency set in a session where you can answer the prompt, then run qb install novnc.

Symptom: install fails with 'Unable to locate package firefox-esr' or a held/broken package

The Xfce + X server + firefox-esr dependency set requires up-to-date package lists. A stale or partially-updated apt cache can leave the install unable to resolve firefox-esr, tightvncserver, or the xserver-xorg packages.

Fix: refresh apt and clear any broken state, then reinstall:

apt-get update
apt-get -y --fix-broken install
qb reinstall novnc -u username

After install — common access failures

Symptom: browser loads but the desktop is blank

Checks: Confirm vnc@username.service is running and /home/username/.vnc/xstartup exists and is executable. The xstartup script launches the Xfce session — if it is missing or not executable, the VNC server connects but no desktop renders.

systemctl status vnc@username.service
ls -l /home/username/.vnc/xstartup
Symptom: connection refused or 502 on the websockify path

Checks: Confirm novnc@username.service (the websockify proxy) is active and that /etc/nginx/conf.d/username.vnc.conf points to the assigned web port. The websockify proxy bridges the browser WebSocket to the VNC server — if it is stopped, the page loads but the connection is refused.

systemctl status novnc@username.service
systemctl restart novnc@username.service
Symptom: 'connection timed out' connecting directly to the VNC port

This is expected. QuickBox adds iptables rules that accept VNC daemon-port traffic only from localhost and drop everything else. Connect through the browser path /username/vnc (which goes through the websockify proxy and nginx), not by pointing a desktop VNC viewer at the daemon port.

Symptom: browser keeps prompting for a username and password

The /username/vnc route is protected by nginx HTTP Basic auth using /etc/htpasswd.d/htpasswd.username. A second password prompt comes from the VNC server itself, set during install with vncpasswd from your QuickBox account password. If Basic auth keeps failing, confirm the htpasswd file exists for your user. If the VNC password is rejected, run qb reinstall novnc -u username to reset it.

Resources

Resources

noVNC official website

Official noVNC project website with documentation and downloads

noVNC GitHub repository
VNC protocol overview

Wikipedia article covering the Remote Framebuffer (RFB) protocol used by VNC

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support
Feature Previews
Community Configs
Active Discussions
Join Discord Server
Last updated on
Remote AccessWeb Console