Nicholas Dodds

Screen Sharing fallback

Screen Sharing fallback

An optional second way to reach your Omarchy desktop from a Mac: WayVNC on Linux, viewed in macOS Screen Sharing through an SSH tunnel.

Tested October 5, 2026 with WayVNC 0.10.1. Command-to-Super wasn't confirmed, so use Moonlight when Super shortcuts matter; see Testing and references.

What you'll build

WayVNC shares the Linux desktop on 127.0.0.1 only, and macOS Screen Sharing reaches it through an SSH tunnel. It backs up the Moonlight guide, which was much more responsive in testing.

Before you start

You need:

1. Install WayVNC

On Linux, install WayVNC and check that the graphical session it will share is running:

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

The session is active and a Wayland display is shown. If not, log into Omarchy at the computer first.

2. Set up WayVNC

WayVNC listens only on the Linux computer itself, with a password the Mac's Screen Sharing understands; the SSH tunnel encrypts the connection.

  1. Start Bash, so the password prompt behaves the same for everyone:

    bash

  2. Run this whole block. It backs up any existing WayVNC configuration, asks you to choose an eight-character password, and writes 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

    Continue once it prints “WayVNC configuration saved.”

    Keep WayVNC on 127.0.0.1

    This older password method only uses eight characters. It's acceptable only because WayVNC stays on 127.0.0.1 behind SSH. Never change the address to 0.0.0.0 or expose the VNC port to the internet.

  3. Create the service that starts WayVNC with your desktop. An existing wayvnc.service is backed up first.

    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

The last line says active. If it says failed, see Troubleshooting.

3. Connect from Screen Sharing

  1. Open a second Terminal window on the Mac, keeping the Linux one. Run this and enter your Linux details:

    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"

    After you sign in, the window sits quietly with no prompt: that's the tunnel running. Leave it open; Control+C or closing it stops the tunnel.

Try Screen Sharing

  1. In a third Mac Terminal window, run:

    open 'vnc://127.0.0.1:15900'
  2. When Screen Sharing asks for a password, enter the eight-character VNC password from step 2, not your Linux password.
  3. If the Linux lock screen appears, enter your Linux password there.

Your Linux desktop appears. Closing Screen Sharing disconnects the viewer without logging you out of Linux. The tunnel can stay open for next time.

4. Optional: make a launcher

Instead of repeating step 3 each time, make a Mac launcher that remembers the connection details. It creates files in ~/Documents/Omarchy Remote holding only your Linux username and address, no 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"
  1. Stop the manual tunnel from step 3 with Control+C, so it doesn't hold the same port.
  2. In Finder, open Documents > Omarchy Remote and double-click Open Linux Desktop.command. If you move the folder, keep the script beside connection.txt.

The launcher reuses its own tunnel if it's running and starts a new one if not; you may still be asked to sign in. To stop a tunnel it started:

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 save the VNC password in your Keychain; that's up to you. Never put real passwords in a website, shared script or screenshot.

Troubleshooting

WayVNC fails, or Screen Sharing can't connect

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

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, not just observing it. If every key makes the Mac beep, check View > Keyboard Controls Remote Device; that restored input in testing.

Moonlight's keyboard capture setting doesn't apply to Screen Sharing, and its modifiers may not match Moonlight's. Use Moonlight when Super shortcuts matter. No Linux-wide remapping is needed.

Stop or undo

Stop WayVNC and keep it from starting with your session:

systemctl --user disable --now wayvnc

Sunshine and Moonlight stay available. To bring the fallback back, run systemctl --user enable --now wayvnc. Close Screen Sharing and stop its tunnel.

Testing and references

Tested October 5, 2026 with WayVNC 0.10.1; Screen Sharing reached the Linux lock screen. Command-to-Super through Screen Sharing wasn't conclusively verified.