If the one-command install didn't work, you're in the right place. This article covers every failure we've seen when installing Matrix Desktop on a headless Mac over SSH — and the exact fix for each one.

If you haven't tried the install yet, start with the headless Mac setup guide first. Come back here if something goes wrong.

"Operation not permitted" When Copying

The app is already installed and running. macOS (SIP) protects the running app bundle so cp -R fails.

Fix: Kill the running app and remove the old copy before installing:

Terminal (SSH session)
killall "Matrix Desktop" 2>/dev/null; rm -rf "/Applications/Matrix Desktop.app"

Then re-run the install command from the setup guide.

Tip: This also applies when updating. Always kill and remove before copying a new version.

"Resource busy" When Mounting DMG

A previous DMG mount is still attached from a failed install attempt.

Fix: Detach the stale mount:

Terminal (SSH session)
hdiutil detach "/Volumes/Matrix Desktop" 2>/dev/null || hdiutil detach /dev/disk4 -force
Tip: Run ls /Volumes/ to check if "Matrix Desktop" is already mounted. If the volume name doesn't match, use hdiutil info to find the right device path.

Commands Break When Pasted Over SSH

Multi-line commands with backslash (\) continuations can split into separate commands in some terminal emulators (Warp, iTerm pasting into SSH sessions, Tailscale SSH). You'll see errors like zsh: no URL specified, command not found: -R, or only the first line executes.

Fix: Use a single-line version of the install command with no line breaks:

Terminal (SSH session)
curl -L https://matrix.watch/Matrix-Desktop.dmg -o /tmp/md.dmg && hdiutil attach /tmp/md.dmg -nobrowse && cp -R "/Volumes/Matrix Desktop/Matrix Desktop.app" /Applications/ && hdiutil detach "/Volumes/Matrix Desktop" && open "/Applications/Matrix Desktop.app"
Tip: When in doubt, always use the single-line version. Backslash continuations are fragile over SSH — quoted paths with && chains on one line are the safest approach.

Display Is Asleep

system_profiler SPDisplaysDataType shows Display Asleep: Yes. The open command may fail or the app may launch but not render because macOS has suspended the display pipeline.

Fix: Wake the display before launching:

Terminal (SSH session)
caffeinate -u -t 5

Headless Macs put their virtual display to sleep after a few minutes of inactivity. The -u flag simulates a user wake event. Run this before open in your install command.

No GUI Session / WindowServer Not Running

The open command fails silently or errors because there's no active GUI session. This happens when:

Fix: Enable either auto-login or Screen Sharing:

Tip: A dummy HDMI plug also helps macOS maintain a proper WindowServer session even when no one is connected via Screen Sharing.

Gatekeeper Blocks the App

You see "damaged and can't be opened" or "developer cannot be verified" when launching over SSH. Matrix Desktop is notarized, but the quarantine extended attribute can cause issues when the DMG was downloaded via curl.

Fix: Clear the quarantine flag after copying and before launching:

Terminal (SSH session)
xattr -cr "/Applications/Matrix Desktop.app"

"login item UNKNOWN" From osascript

When you run the osascript command to add a login item, it returns login item UNKNOWN. This looks like an error but it's not — the login item was created successfully. macOS returns this for apps that aren't currently running or for the first registration.

Verify it worked by checking System Settings > General > Login Items, or just reboot and confirm the app starts automatically.

Rain Not Visible After Launch

The process is running (ps aux | grep -i matrix shows it) but you don't see rain on the desktop through Screen Sharing.

Possible causes:

Check if it's running:

Terminal (SSH session)
ps aux | grep -i "[M]atrix"

Low Resolution / Blocky Rain

The app auto-upgrades resolution on headless displays, but if you want Retina quality: use a dummy HDMI plug ($8 on Amazon) or BetterDisplay ($21.50) for full control over virtual display resolution.

The Bulletproof Install Command

A single command that handles all of the above — kills existing app, removes old copy, detaches stale mounts, downloads, mounts, copies, detaches, clears quarantine, wakes display, launches, and adds a login item:

Terminal (SSH session)
killall "Matrix Desktop" 2>/dev/null; rm -rf "/Applications/Matrix Desktop.app"; hdiutil detach "/Volumes/Matrix Desktop" 2>/dev/null; curl -L https://matrix.watch/Matrix-Desktop.dmg -o /tmp/md.dmg && hdiutil attach /tmp/md.dmg -nobrowse && cp -R "/Volumes/Matrix Desktop/Matrix Desktop.app" /Applications/ && hdiutil detach "/Volumes/Matrix Desktop" && xattr -cr "/Applications/Matrix Desktop.app" && caffeinate -u -t 5 && open "/Applications/Matrix Desktop.app" && osascript -e 'tell application "System Events" to make login item at end with properties {path:"/Applications/Matrix Desktop.app", hidden:false}'
Tip: This is safe to run even on a fresh install — the killall, rm, and detach commands silently succeed if there's nothing to kill, remove, or detach.

Claude Code Troubleshooting Prompt

A prompt you can paste into Claude Code that diagnoses and fixes everything automatically:

Claude Code prompt
Troubleshoot Matrix Desktop on this Mac. Check if it's running with ps aux. Check if /Applications/Matrix Desktop.app exists. Check if a DMG is mounted at /Volumes/Matrix Desktop. Check display status with system_profiler SPDisplaysDataType. If the app is running but rain isn't visible, restart it. If it's not installed, download from https://matrix.watch/Matrix-Desktop.dmg to /tmp/md.dmg — but first kill any running instance and remove the old app. Detach any existing Matrix Desktop volume. Mount the DMG, copy the app, detach, clear quarantine with xattr -cr, wake the display with caffeinate -u -t 5, then launch it. Add it as a login item with osascript. Verify everything works. Show me the final status.