How to configure WayVNC for macOS Screen Sharing

To connect the built-in macOS Screen Sharing app to a Raspberry Pi desktop running WayVNC, configure authentication compatible with the Mac client and allow incoming connections over the LAN.

This example assumes Raspberry Pi OS Desktop running a Wayland session, such as labwc, and WayVNC 0.10 or later, which added legacy DES authentication for clients such as macOS. Check the version on the Pi:

wayvnc --version

The Mac and Pi must be on the same LAN. The Pi must have a running desktop session. These steps do not install a desktop on Raspberry Pi OS Lite. If the Pi still boots into a console, configure desktop mode first as described in How to change boot into text console or GUI in Raspberry Pi.

1. Enable VNC on the Raspberry Pi

Run on the Pi:

sudo raspi-config

Select Interface Options → VNC → Yes to enable the VNC server on a Wayland system with WayVNC installed, then select Finish.

2. Configure compatibility with macOS

Edit the WayVNC configuration file used by the Raspberry Pi OS system service:

sudoedit /etc/wayvnc/config

Update or add the following settings. Replace existing values instead of adding duplicate keys, and retain existing certificate and key entries, such as certificate_file, private_key_file, and rsa_private_key_file.

address=0.0.0.0
port=5900
enable_auth=true
enable_pam=false
username=vnc
password=YOURPASS
relax_encryption=true
allow_broken_crypto=true

Replace YOURPASS with your own VNC password before saving. This example uses an eight-character password for legacy VNC; choose one different from your Linux account password.

The settings have the following effects:

• address=0.0.0.0 listens on every IPv4 interface. Using 127.0.0.1 would accept connections only within the Pi, preventing a Mac from connecting directly to its LAN IP.
• port=5900 is the TCP port the Mac connects to.
• enable_auth=true requires authentication instead of allowing password-free desktop access.
• enable_pam=false uses the configured username and password instead of Linux account authentication. Legacy DES authentication cannot use PAM.
• relax_encryption=true permits connection methods that do not require encryption after authentication.
• allow_broken_crypto=true enables legacy authentication methods that older clients use with the configured password.

The file contains a plaintext password. For Raspberry Pi OS installations running the service as user vnc, restrict access as follows:

sudo chown root:vnc /etc/wayvnc/config
sudo chmod 640 /etc/wayvnc/config

This configuration allows legacy VNC compatibility without encrypting screen contents or interaction data. Use it only on a trusted LAN, and do not forward TCP port 5900 to the internet.

3. Start the service with the new configuration

Restarting the service temporarily disconnects any existing VNC session.

sudo systemctl enable --now wayvnc.service
sudo systemctl restart wayvnc.service
systemctl is-active wayvnc.service
ss -lnt 'sport = :5900'

The service should report active, with a listener at 0.0.0.0:5900. If a firewall is enabled, allow incoming TCP port 5900 only from the Mac’s IP address or the required LAN subnet.

4. Connect from macOS

Find the Pi’s IP addresses:

hostname -I

Choose the address of the interface on the same LAN as the Mac. This example assumes 192.168.1.50.

On the Mac, open Finder, press Command + K, and enter:

vnc://192.168.1.50:5900

Alternatively, run in macOS Terminal:

open "vnc://192.168.1.50:5900"

The Screen Sharing app opens. Enter the VNC password configured in /etc/wayvnc/config. If a username field appears, use vnc as configured above. A successful connection displays the Pi’s running desktop session.

References: WayVNC 0.10 release notes, WayVNC configuration, Raspberry Pi remote access, and Apple: VNC access and control.