Omarchy desktop from a Mac

What you'll build

• Moonlight on your Mac shows and controls the desktop already running on your Omarchy computer: the same desktop someone at its monitor sees, not a separate login.
• Sunshine on Linux sends the picture and sound.
• Tailscale connects the two computers privately, so no router port forwarding is needed.

In testing, Moonlight felt much more responsive than macOS Screen Sharing over WayVNC (latency wasn't measured), so it's the recommended everyday setup. The physical Windows key on the Linux computer keeps working. An optional WayVNC fallback is available once you've finished here; you don't need it to use Moonlight.

Before you start

• An Omarchy computer with a monitor attached, online, awake and logged into its desktop.
• A Mac that's online.
• Your Linux username and password, with permission to use sudo.
• Both computers signed into the same personal Tailscale account. A managed account may need an administrator to allow the connections.

This is for Omarchy (Hyprland). Ubuntu GNOME and KDE need different desktop-sharing steps. It shares a desktop that's already running; it doesn't create a headless one.

Each command is labelled with where it runs. Copy the whole block and press Return; don't copy prompts such as ~ ❯. Password prompts usually show nothing as you type.

Already set up? Go to Command as Super or everyday use. The setup steps replace the named configuration files, backing them up where it matters.

1. Connect with Tailscale

Install Tailscale on both computers and sign both into the same account, then turn on terminal access on Linux.

On the Linux computer

1. If Tailscale isn't installed, install and start it. If installing reports stale mirrors or dependency errors, update Omarchy through its normal update tool first; don't run a database-only pacman -Sy.

   sudo pacman -S --needed tailscale
   sudo systemctl enable --now tailscaled
   sudo tailscale up

   Open the sign-in link it prints and sign into your Tailscale account. If it's already connected, skip the sign-in.

2. Check it, and note your username and Tailscale address:

   systemctl is-enabled tailscaled
   systemctl is-active tailscaled
   whoami
   tailscale ip -4

The first two lines say enabled and active, and the address usually starts with 100.. Write down your username and that address; they're specific to your machine.

On the Mac

1. Install Tailscale following its official Mac instructions.
2. Open Tailscale, approve its network-extension setup, and sign into the same account.
3. Check that its menu says it's connected. Optional: turn on start at login.

Enable terminal access on Linux

If SSH to this machine already works, skip this. Otherwise, run it at the Linux computer itself, because it can interrupt an SSH connection over Tailscale:

sudo tailscale set --ssh

This turns on Tailscale SSH over your private network. Your account must allow SSH to this Linux user; if access is denied, see Tailscale SSH access rules rather than opening a managed network up broadly.

2. Open a Linux terminal from the Mac

Open Terminal (Applications > Utilities) and run this. It asks for the two details you wrote down:

printf "Linux username: "
read -r LINUX_USER
printf "Linux Tailscale IPv4 address: "
read -r LINUX_IP
ssh "$LINUX_USER@$LINUX_IP"

Complete any Tailscale browser check if asked. If SSH asks about a new host key, check it against the host's details before accepting.

You reach a Linux prompt. Run hostname if you're unsure which computer you're on.

Keep this window open for the Linux steps. Step 5 needs a second Mac Terminal window. Typing exit returns a window to the Mac.

3. Install Sunshine

1. Install it (the SSH window is fine). Enter your Linux password, and type y if asked to proceed.

   sudo pacman -S --needed sunshine

2. Confirm it installed and that a desktop session is running:

   pacman -Q sunshine
   systemctl --user is-active graphical-session.target
   systemctl --user show-environment | grep WAYLAND_DISPLAY

The session check says active, and the last command shows a Wayland display such as WAYLAND_DISPLAY=wayland-1. If not, log into the Omarchy desktop at the computer; an SSH login alone doesn't start a desktop.

Never add sudo to the systemctl --user commands in this guide.

4. Set up Sunshine

1. Run bash first, so the next block runs in Bash.

2. Create a configuration that listens only on your Tailscale address, with automatic router port opening off:

   mkdir -p ~/.config/sunshine
   chmod 700 ~/.config/sunshine
   if [ -f ~/.config/sunshine/sunshine.conf ]; then
     cp -p ~/.config/sunshine/sunshine.conf ~/.config/sunshine/sunshine.conf.backup-$(date +%Y%m%d-%H%M%S)
   fi
   LINUX_IP=$(tailscale ip -4)
   if [[ "$LINUX_IP" =~ ^100\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
     printf 'sunshine_name = Omarchy Desktop\nbind_address = %s\nupnp = disabled\n' "$LINUX_IP" > ~/.config/sunshine/sunshine.conf
     chmod 600 ~/.config/sunshine/sunshine.conf
     echo 'Sunshine configuration saved.'
   else
     echo 'Not saved: connect Tailscale first, then repeat this block.'
   fi

   Continue once it prints “Sunshine configuration saved.”

3. Start the service:

   systemctl --user enable --now app-dev.lizardbyte.app.Sunshine
   systemctl --user restart app-dev.lizardbyte.app.Sunshine
   systemctl --user is-active app-dev.lizardbyte.app.Sunshine

The last line says active. Sunshine waits a few seconds for the desktop. Once enabled, the short name sunshine also works; this guide uses the full name because the short one may not exist before then.

Sunshine picks a video encoder automatically. On the tested Intel UHD 630, hardware H.264 and HEVC worked with the installed Intel media driver, and encoder = vaapi was set explicitly. On other hardware, leave the automatic choice; don't copy Intel settings to an NVIDIA computer.

5. Open Sunshine's settings

Open a second Terminal window on the Mac, keeping the Linux one. Run this 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:47990:$LINUX_IP:47990" \
  "$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 the window stops it.

The tunnel lets your Mac's browser reach Sunshine's settings: 127.0.0.1 means “this computer”, and SSH carries the traffic to Linux.

6. Install Moonlight and pair

Install Moonlight on your Mac, create a Sunshine admin login, then add the Linux computer in Moonlight and pair it.

Install the Mac app

Download the macOS version from Moonlight's website, open the disk image and drag Moonlight into Applications. Or, if you use Homebrew:

brew install --cask moonlight

Then open Moonlight.

Create your Sunshine admin login

1. With the tunnel from step 5 running, open https://localhost:47990/ on your Mac.

2. Your browser may warn about the certificate, because Sunshine uses its own.

   Check the address first

   Continue past the warning only after checking the address is exactly https://localhost:47990/ and this is the Sunshine server you just started. Never apply this to an unfamiliar website.

3. Create a Sunshine username and a strong, unique password, and save them in your password manager. This login is separate from your Linux login.
4. Sign in, and keep the tab open for pairing.

Add your Linux computer in Moonlight

1. In Moonlight's Computers view, click the monitor-with-a-plus button at the top right.
2. Enter the Linux Tailscale address you noted. Not 127.0.0.1, a web address or a VNC port.
3. Click OK. “Omarchy Desktop” appears.
4. Click it. Moonlight shows a four-digit PIN.
5. In Sunshine's tab, open PIN, enter the PIN and a name for your Mac if asked, then submit.
6. The PIN dialog closes when pairing works. Click the computer again to see its apps.
7. Click the first tile, Desktop. Skip “Low Res Desktop”, which is set up for a different display arrangement.

Your Linux desktop appears; unlock it with your Linux password if needed. To disconnect, press Control+Option+Shift+Q (Option is the Alt in Moonlight's tip). That ends the stream, not your Linux session.

After pairing, Moonlight connects directly over Tailscale, so you can stop the tunnel with Control+C. Start it again whenever you need Sunshine's settings page.

7. Make Command work as Super

This is what fixed the missing Super key in testing; no Linux-wide remapping was needed.

1. Disconnect with Control+Option+Shift+Q.
2. Click the gear at the top right of Moonlight.
3. Under Input Settings, check Capture system keyboard shortcuts and set the menu beside it to always, so it also works in a window, not just fullscreen.
4. Click the back arrow and resume Desktop.
5. Click inside the stream and press Command+Space.

The Omarchy menu opens (with the default Omarchy shortcuts).

This only changes keyboard capture in the Mac app; the Linux keyboard and Omarchy's shortcuts are untouched, and the physical Windows key still works. While the stream has focus, Mac shortcuts go to Linux, so remember the disconnect shortcut. The Screen Sharing fallback handles keys differently.

Day-to-day use

Connect and disconnect

1. Make sure Linux is awake and logged into its desktop, and Tailscale is connected on both computers.
2. Open Moonlight > Omarchy Desktop > Desktop.
3. Use Command for Super shortcuts, and disconnect with Control+Option+Shift+Q.

No Terminal window or tunnel needs to stay open.

After a restart or power cut

Several things must happen between power returning and seeing your desktop. Tailscale starting is only one of them:

Check your Linux machine:

systemctl is-enabled tailscaled
systemctl is-active tailscaled
systemctl --user is-enabled app-dev.lizardbyte.app.Sunshine
systemctl --user is-active app-dev.lizardbyte.app.Sunshine

If Tailscale is disabled, turn on start at boot:

sudo systemctl enable --now tailscaled

Also check the device's key expiry in Tailscale's admin console. An expired sign-in needs reauthenticating even when the service runs. Choose an expiry policy that suits your device; this guide doesn't turn expiry off.

Before you rely on this away from home, do a planned restart while you can reach the computer: note whether it stops at disk unlock or desktop login, then reconnect from the Mac. A UPS helps with short outages. Fully unattended recovery needs separate decisions about firmware, disk unlocking and login; this guide doesn't turn on automatic login or remove encryption, and enabling user “linger” alone doesn't start a Hyprland desktop.

On the tested machine, tailscaled was already enabled and active, and the disk uses LUKS encryption. It wasn't rebooted, and unattended unlocking wasn't checked. A locked desktop that's already running is different from one waiting for its first login.

If streaming isn't available

The WayVNC guide adds a second way in through macOS Screen Sharing, for when streaming isn't available. It was noticeably laggier in testing, so keep Moonlight for everyday use. Both need Tailscale, a running Linux desktop and an awake computer, so the fallback doesn't help after a power cut or at a login screen.

Troubleshooting

SSH times out or says permission denied

Check that Tailscale is connected on both computers, Linux is awake, and you used the Linux username with its Tailscale address. “Access denied” can mean Tailscale policy or sign-in needs attention. SSH must work before the tunnel will.

“Address already in use” when opening the tunnel

An earlier tunnel still holds port 47990. Stop it with Control+C before starting another.

Sunshine won't start, or Moonlight can't find it

systemctl --user status app-dev.lizardbyte.app.Sunshine --no-pager
journalctl --user -u app-dev.lizardbyte.app.Sunshine -n 80 --no-pager
ss -lnt | grep -E '47984|47989|47990|48010'
tailscale ip -4

• The listening address should match the current Tailscale address. If Tailscale started late after a reboot, restart Sunshine once it's connected.
• If the device was removed and re-added to Tailscale, update bind_address and the address in Moonlight.
• Add the computer in Moonlight by address; automatic discovery may not find a Tailscale host.
• If SSH works but Moonlight can't connect, check the Linux firewall and Tailscale access rules. Sunshine uses TCP 47984, 47989 and 48010 and UDP 47998–48000; its settings page uses TCP 47990. The tested network needed no firewall change.

Picture works, but mouse or keyboard doesn't

Click inside Moonlight first. For Super shortcuts, redo step 7 and reconnect. If no input works at all, check device permissions:

getfacl /dev/uinput

The tested Sunshine package added a device rule that gave the logged-in user access. If yours has none, log out of the desktop and back in. Or reload the rules and retry:

sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=misc --sysname-match=uinput
systemctl --user restart app-dev.lizardbyte.app.Sunshine

Video is black, slow or choppy

Keep the monitor connected and awake. Start at 1080p, 60 FPS and about 15–20 Mbps in Moonlight, and lower the bitrate or frame rate on a slow connection; a wired connection on Linux helps. Check Sunshine's log for the encoder it chose. Probe errors for unsupported codecs (such as AV1 on the UHD 630) don't mean streaming failed; the tested log went on to find working H.264 and HEVC encoders.

No sound on the Mac

Check the Mac's volume, the Linux app's volume and Moonlight's audio settings. Sunshine creates a streaming audio output, and its log should show audio (Opus) starting. Mute host PC speakers while streaming controls whether sound also plays at the Linux computer. Audio starting was checked; audio quality wasn't measured.

Stop or undo

To stop desktop sharing and keep it from starting with future sessions:

systemctl --user disable --now app-dev.lizardbyte.app.Sunshine

Your settings, packages and Tailscale connection stay. Close Moonlight and stop any tunnel. To turn sharing back on:

systemctl --user enable --now app-dev.lizardbyte.app.Sunshine

To undo the Command-key change, disconnect, open Moonlight's settings and uncheck Capture system keyboard shortcuts. The Linux keyboard is never changed.

Testing and references

Tested October 5, 2026 on Omarchy with Hyprland 0.56.2, WayVNC 0.10.1, Sunshine 2026.516.143833 and Moonlight 6.2.0, on an Intel UHD 630 with a 1920 × 1080 monitor. Moonlight showed the desktop and started audio, and Command+Space opened the Omarchy menu once keyboard capture was on. Screen Sharing showed the Linux lock screen.

Not tested: recovery from a cold boot, other GPUs, headless use, and remapping modifiers in Screen Sharing. The screenshots show saved settings after setup, not a fresh install. Private addresses and credentials are left out.

• WayVNC: running, authentication and SSH tunnelling
• Sunshine documentation
• Moonlight setup guide
• Tailscale on Linux and on macOS
• Tailscale SSH and access rules