VNC beta

Bridge v3.0.0 includes native and browser VNC as an opt-in beta for development and testing. Both modes are disabled by default. This beta is not production-ready. The verified combinations and remaining validation limits are listed below.

Configuration

vnc:
  native:
    enabled: true
    listen: 5900
    tls_cert: /data/certs/vnc-cert.pem
    tls_key: /data/certs/vnc-key.pem
  browser:
    enabled: true
  idle_timeout: 30m

The native listener requires an existing certificate and private key. The viewer must trust that certificate and verify the gateway hostname. The settings also accept environment variables such as BRIDGE_VNC_NATIVE_ENABLED and BRIDGE_VNC_BROWSER_ENABLED.

Checkout fields

A VNC checkout has protocol: vnc, an operator username, a target_host, and a vaulted target_password. The target port defaults to 5900. VNC target authentication does not use target_username.

target_password contains 1 to 8 bytes. Bridge rejects longer values because classic VNC authentication uses only eight bytes. The Bridge login password has no eight-byte limit.

native_enabled and browser_enabled control the checkout’s access paths. The deployment settings above must also enable the selected mode. Native authentication follows the checkout’s native_auth selection, including bridge_credentials and LDAP. Bridge credentials and directory passwords are never forwarded to the target.

record_session defaults to true through the checkout API. Recorded sessions retain the desktop and accepted keyboard and pointer input in the existing replay format. Authentication exchanges are excluded. Typed passwords inside the remote desktop can appear in recordings, as with other desktop sessions.

lock_blocks_screen covers the operator’s desktop with a black frame during an administrator lock. A lock always blocks new input and releases held keys and mouse buttons. Clipboard transfer and command filtering are unavailable. Checkouts that request command filtering are refused.

Native connections

The native endpoint speaks RFB 3.8 with VeNCrypt 0.2 X509Plain. The login name is username%target_host, and the password is the checkout’s Bridge credential or directory password. Viewers without X509Plain support cannot connect. No unencrypted native authentication method is offered.

Browser connections

/connect?transaction_id=... routes an authorized checkout to /vnc/. The checkout picker also opens the browser desktop. Browser authentication exchanges the checkout bearer token or signed-in session for a short-lived, single-use WebSocket token.

The canvas client supports keyboard input, mouse buttons, vertical scrolling, full screen, and Ctrl+Alt+Delete. Clipboard transfer, file transfer, and live-view sharing are unavailable in this version. Browser frames wait for a paint acknowledgment before Bridge requests another update.

Target compatibility and limits

Targets must support RFB 3.3, 3.7, or 3.8 with classic VNC password authentication. Bridge requests a 32-bit true-color pixel format and Raw, CopyRect, and DesktopSize encodings. It refuses anonymous target authentication and other security types. Raw encoding favors compatibility and can use substantial bandwidth.

target_tls: true wraps the target connection in TLS before the RFB handshake. target_ca_cert supplies a private CA. Bridge verifies the target hostname and refuses target_tls_skip_verify. Target-side VeNCrypt negotiation is not implemented. Classic target connections without target_tls require a trusted private network or a separately protected transport.

Displays have at most 8,192 pixels per side and 16,777,216 pixels in total. Text messages have a 64 KiB limit. Connections have a 20-second setup deadline and bounded writes. Checkout deletion, expiry, or replacement ends existing sessions. Bridge checks before each input message and polls idle sessions every second.

Verified combinations

Real end-to-end checks on 2026-10-30 and the post-rebase rerun on 2026-11-02 used the normal Bridge entry point, PostgreSQL, real LDAP login, and an X11 application. The test fixtures ran on Linux ARM64. The browser ran on macOS ARM64.

The checks cover keyboard and pointer input, resizing, administrator locks, checkout revocation and expiry, recording opt-out, and browser and native recording playback. Native authentication uses both Bridge credentials and real LDAP. Target TLS checks use a real TLS tunnel with trusted and untrusted certificates and a hostname mismatch.

The native viewer checks use Linux. Other native viewers, Windows and macOS viewer builds, other browsers, sustained load, and unreliable networks still need validation. The playback checks compare the final rendered frame with the recording and exercise seeking; they do not certify every intermediate frame or timing accuracy.

Verify

Open an authorized VNC test checkout with Connect. Confirm that the remote desktop appears and accepts keyboard and pointer input. For native access, connect a verified viewer to the Bridge listener using username%target_host and the separate Bridge or LDAP password.

After ending a recorded session, open it in the existing recording player and confirm desktop playback. Revoke the test checkout and confirm that an active connection ends. Historical VNC recordings remain available in the same player.

See the VNC checkout example and Kubernetes deployment.