WayVNC: a Screen Sharing fallback

1. Start with a working private connection

This is the optional backup to the Moonlight guide. It uses WayVNC on Linux and the built-in Screen Sharing app on your Mac. Moonlight was much more responsive in our setup; keep this as an alternative.

First complete the main guide’s prerequisites, Tailscale setup and SSH connection. Sunshine and Moonlight are not required for this fallback. Linux must already be logged into its graphical desktop.

In your Linux terminal, run:

sudo pacman -S --needed wayvnc
systemctl --user is-active graphical-session.target
systemctl --user show-environment | grep WAYLAND_DISPLAY

Expect an active session and a Wayland display. If either is missing, log into Omarchy locally before continuing.

2. Set up WayVNC on Linux

WayVNC needs a password that the Mac Screen Sharing app understands. We keep it listening only on the Linux computer itself; the SSH tunnel will provide network encryption.

In the Linux terminal: enter Bash so the password prompt below behaves consistently:

bash

Then paste this whole block. It backs up an existing WayVNC configuration, asks you to choose a new eight-character password, and creates the settings. Use a unique password and save it in your password manager.

mkdir -p ~/.config/wayvnc ~/.config/systemd/user
if [ -f ~/.config/wayvnc/config ]; then
  cp -p ~/.config/wayvnc/config ~/.config/wayvnc/config.backup-$(date +%Y%m%d-%H%M%S)
fi
read -r -s -p 'Choose an 8-character VNC password (letters and numbers): ' VNC_PASSWORD
printf '\n'
if [[ "$VNC_PASSWORD" =~ ^[A-Za-z0-9]{8}$ ]]; then
  umask 077
  printf 'address=127.0.0.1\nport=5900\nenable_auth=true\nrelax_encryption=true\nallow_broken_crypto=true\nusername=%s\npassword=%s\n' "$USER" "$VNC_PASSWORD" > ~/.config/wayvnc/config
  echo 'WayVNC configuration saved.'
else
  echo 'Not saved: use exactly eight letters/numbers. Repeat this block.'
fi
unset VNC_PASSWORD

Wait for “WayVNC configuration saved” before continuing. The legacy password method used here only uses eight characters. It is suitable here because the service stays on 127.0.0.1 and SSH encrypts the connection. Do not change the address to 0.0.0.0 or expose this VNC port to the internet.

Next, create the automatic-start service. If you already created your own wayvnc.service, back it up before replacing it.

if [ -f ~/.config/systemd/user/wayvnc.service ]; then
  cp -p ~/.config/systemd/user/wayvnc.service ~/.config/systemd/user/wayvnc.service.backup-$(date +%Y%m%d-%H%M%S)
fi
cat > ~/.config/systemd/user/wayvnc.service <<'EOF'
[Unit]
Description=WayVNC desktop access via SSH
After=graphical-session.target
PartOf=graphical-session.target

[Service]
ExecStart=/usr/bin/wayvnc -r
Restart=on-failure
RestartSec=5

[Install]
WantedBy=graphical-session.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now wayvnc
systemctl --user restart wayvnc
systemctl --user is-active wayvnc

Expected: active. If it says failed, use the troubleshooting section before continuing.

3. Connect from Mac Screen Sharing

Open a second Terminal window on the Mac. Leave your Linux terminal available. Paste this block into the new Mac window and enter your Linux details again:

printf "Linux username: "
read -r LINUX_USER
printf "Linux Tailscale IPv4 address: "
read -r LINUX_IP
ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
  -L "127.0.0.1:15900:127.0.0.1:5900" \
  "$LINUX_USER@$LINUX_IP"

Expected: after authentication, the terminal sits quietly without returning a prompt. That means the tunnel is running. Leave this window open. Pressing Control–C or closing it stops this connection.

This tunnel carries Screen Sharing. Here, 127.0.0.1 means “this computer”: the Mac connects locally, and SSH carries that traffic to Linux.

Try Screen Sharing

1. Open a third Mac Terminal window and run the command below.
2. When Screen Sharing asks for a password, enter the eight-character VNC password from step 2. This is not your Linux login password.
3. If you then see the Linux lock screen, enter your normal Linux login password there.

open 'vnc://127.0.0.1:15900'

You should now see your existing Linux desktop. Closing the Screen Sharing window disconnects the viewer; it does not log you out of Linux. The SSH tunnel window can stay open for next time.

4. Make a reusable Mac launcher

You can repeat step 3 each time. Or make a small Mac launcher so you only enter the connection details once. In a Mac Terminal window, paste this block. It creates files in ~/Documents/Omarchy Remote. The configuration contains only your Linux username and address, not passwords.

mkdir -p "$HOME/Documents/Omarchy Remote"
printf "Linux username: "
read -r LINUX_USER
printf "Linux Tailscale IPv4 address: "
read -r LINUX_IP
printf '%s\n%s\n' "$LINUX_USER" "$LINUX_IP" > "$HOME/Documents/Omarchy Remote/connection.txt"
cat > "$HOME/Documents/Omarchy Remote/Open Linux Desktop.command" <<'EOF'
#!/bin/zsh
set -e
cd -- "$(dirname -- "$0")"
{ read -r remote_user; read -r remote_ip; } < connection.txt
socket="${TMPDIR:-/tmp/}omarchy-desktop-${UID}.sock"
if ! ssh -S "$socket" -O check "$remote_user@$remote_ip" >/dev/null 2>&1; then
  ssh -M -S "$socket" -fNT -o ExitOnForwardFailure=yes \
    -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
    -L "127.0.0.1:15900:127.0.0.1:5900" \
    "$remote_user@$remote_ip"
fi
open 'vnc://127.0.0.1:15900'
EOF
chmod 700 "$HOME/Documents/Omarchy Remote/Open Linux Desktop.command"
chmod 600 "$HOME/Documents/Omarchy Remote/connection.txt"

Before trying the launcher, stop the manual tunnel from step 3 with Control–C, so it does not occupy the same ports. In Finder, open Documents → Omarchy Remote and double-click Open Linux Desktop.command. Keep the script beside its connection.txt file if you move the folder. The launcher reuses its own running tunnel and reconnects when it has stopped. Authentication may still prompt.

To stop a launcher-created tunnel, use this in Mac Terminal:

cd "$HOME/Documents/Omarchy Remote"
{ read -r remote_user; read -r remote_ip; } < connection.txt
ssh -S "${TMPDIR:-/tmp/}omarchy-desktop-${UID}.sock" -O exit "$remote_user@$remote_ip"

Screen Sharing may offer to remember its VNC password in your Mac’s Keychain; that is your choice. Do not put real passwords in a website, shared script or screenshot.

5. If keyboard input stays on the Mac

Click inside the remote desktop and try typing in a Linux text editor. Make sure Screen Sharing is controlling the computer, rather than observing it. If every keystroke makes the Mac beep, check View → Keyboard Controls Remote Device and test typing again. Changing this menu setting restored input in our session.

Moonlight’s “Capture system keyboard shortcuts” setting does not affect Screen Sharing. Command-to-Super behavior through Screen Sharing was not conclusively verified; do not assume its modifiers match Moonlight. Use the tested Moonlight keyboard setup when Super shortcuts are essential. No Linux-wide keyboard remapping is required by this fallback guide.

6. Troubleshooting and recovery

WayVNC fails, or Screen Sharing cannot connect

Run these in the Linux terminal:

systemctl --user status wayvnc --no-pager
journalctl --user -u wayvnc -n 50 --no-pager
ss -lnt | grep 5900

Expected listener: 127.0.0.1:5900. A missing Wayland display usually means there is no running graphical session or its environment has not reached the user service manager. Log into Omarchy locally and repeat the session checks in step 1. After correcting configuration, run systemctl --user restart wayvnc.

The Screen Sharing password is your eight-character VNC password. A subsequent Linux lock screen takes your Linux password.

If the tunnel reports “Address already in use,” stop your manual tunnel with Control–C, or use the launcher’s stop command above. Keep only one tunnel on port 15900.

For startup and power-outage limits, see the main recovery checklist. Check this fallback service separately with systemctl --user is-enabled wayvnc and systemctl --user is-active wayvnc.

7. Stop the fallback

On Linux:

systemctl --user disable --now wayvnc

This leaves Sunshine and Moonlight available. To restore the fallback, run systemctl --user enable --now wayvnc. Close Screen Sharing and stop its SSH tunnel.

WayVNC documentation · Back to the Moonlight guide