You can install Matrix Desktop on a headless Mac Mini or Mac Studio entirely over SSH in under 60 seconds. This guide covers the full setup: remote install, auto-start on boot, restart commands, and performance tips for screen sharing and VNC.

Why Run a Live Wallpaper on a Headless Mac?

A headless Mac used for vibe coding with Claude Code, Open Claw, or Hermes Agent still has a desktop, and you see it every time you connect via Screen Sharing, VNC, or a remote desktop client. Without a wallpaper, you get a flat default background. With Matrix Desktop, your remote session shows live digital rain cascading behind your terminal windows.

Three reasons this matters for headless setups:

Step 1: Install via SSH

SSH into your headless Mac and run this single command. It downloads the DMG, mounts it, copies the app to Applications, unmounts the DMG, and launches the app.

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: If the display is asleep (common on headless Macs), wake it first: caffeinate -u -t 5. The open command also requires an active GUI session — make sure Screen Sharing or a dummy HDMI plug is connected.

That is the entire installation. No Homebrew, no App Store sign-in, no manual dragging. The app runs immediately after the command finishes.

Reinstalling or Updating

If Matrix Desktop is already installed and running, cp -R will fail because macOS locks the running app bundle. Kill it and remove the old copy first:

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

Then run the install command above again.

Or Let Claude Do It

Paste this prompt into Claude Code and it handles everything — install, auto-start, display wake, and troubleshooting:

Claude Code prompt
Install Matrix Desktop on this Mac. Download from https://matrix.watch/Matrix-Desktop.dmg to /tmp/md.dmg. If the app is already running, kill it first with killall and remove the old copy from /Applications before copying the new one. Mount the DMG, copy Matrix Desktop.app to /Applications, unmount. If the display is asleep, wake it with caffeinate -u -t 5 before launching. Launch the app with open. Then register it as a login item so it auto-starts on boot using osascript. Verify the app is running with ps aux. If anything fails, refer to https://matrix.watch/articles/headless-troubleshooting.html for known fixes and troubleshoot accordingly.

Step 2: Auto-Start on Boot

Matrix Desktop should launch automatically when the Mac reboots so you never connect to a bare desktop. Run this command to add it as a login item:

Terminal (SSH session)
osascript -e 'tell application "System Events" to make login item at end with properties {path:"/Applications/Matrix Desktop.app", hidden:false}'

This registers the app with macOS Login Items. After any restart or power cycle, Matrix Desktop starts automatically when the user session logs in. No cron jobs, no launch agents, no plist files to maintain.

Tip: If your headless Mac is set to auto-login (System Settings > Users > Login Options > Automatic login), the wallpaper will be running before you even connect. For Macs without auto-login, you will need to authenticate first via Screen Sharing to trigger the user session.

Step 3: Restart the App Remotely

If you change settings or need to restart Matrix Desktop for any reason, use this command over SSH:

Terminal (SSH session)
killall "Matrix Desktop" 2>/dev/null; open /Applications/Matrix\ Desktop.app

The killall command silently terminates the running instance (the 2>/dev/null suppresses errors if it is not running), and open immediately relaunches it. The entire cycle takes under a second.

VNC and Screen Sharing Performance Tips

A live animated wallpaper sends more pixels over the wire than a static image. These settings keep the experience smooth when viewing your headless Mac remotely.

Use Apple Screen Sharing over VNC

Apple's built-in Screen Sharing (System Settings > General > Sharing > Screen Sharing) uses a hardware-accelerated encoder that handles animation far better than third-party VNC servers. If you are on a Mac client, always connect via vnc://your-mac-ip in Finder to use the native protocol.

Lower the Rain Density

Matrix Desktop lets you adjust character density in real time. For remote sessions, reducing density to 60-70% of the default cuts the number of animated elements without losing the visual effect. Fewer moving characters means fewer screen updates transmitted over the network.

Reduce Animation Speed

Slowing the rain speed by 20-30% significantly reduces the frame delta between screen captures. The wallpaper still looks alive, but VNC has less work to do encoding each frame. This makes the biggest difference on slower network connections.

Display Resolution

Without a physical display, macOS defaults to a low resolution (often 1024x768), which makes everything look blocky. Matrix Desktop handles this automatically — on launch, it detects if the main display is below 1280px wide and upgrades it to the best available mode (typically 1920x1080) using native macOS display APIs. No configuration needed.

For most headless setups, this is all you need. The app takes care of it on every launch.

For higher resolutions: If you want Retina-quality rendering (2560x1440 or higher), you have two options:

Option A: Dummy HDMI plug (~$8) — A 4K HDMI dummy plug tricks macOS into thinking a real display is connected, unlocking full resolution modes. Search "4K HDMI dummy plug" on Amazon. Plug it in and macOS renders at native 4K. Simplest permanent fix.

Option B: BetterDisplay — BetterDisplay ($21.50) is a third-party app that creates and manages virtual displays with full control over resolution, refresh rate, and HiDPI scaling. It can create Retina-scaled virtual displays up to 5K, configure custom refresh rates, and persist settings across reboots. If you're running a serious headless setup and want precise control over your virtual display, BetterDisplay is the most capable tool available.

Recommended Presets for Headless Setups

Matrix Desktop ships with 12 presets. Two work especially well on headless machines viewed through screen sharing:

Operator

Dense columns of tightly packed characters with a bright green-on-black palette. This preset creates the classic code-rain look that pairs naturally with terminal windows and IDE panels. If your headless Mac is a dedicated vibe coding machine, Operator is the preset that matches the aesthetic. The high density looks striking on screen share, and the consistent animation pattern compresses well over VNC.

Classic

The original Matrix rain with balanced spacing, moderate speed, and clean character rendering. Classic is the safer choice if you want the wallpaper to be present but not dominant. It uses fewer GPU resources than denser presets, which can matter if your headless Mac is also running ML workloads or heavy compilation alongside the coding agents.

Tip: You can switch presets through the menu bar icon even over a remote session. Right-click the Matrix Desktop icon in the menu bar, select Presets, and choose one. The change takes effect immediately with no restart needed.

Summary

The complete headless setup is three commands:

  1. Install: Download, mount, copy, launch via a single curl pipeline.
  2. Auto-start: Register as a login item with osascript.
  3. Restart: Kill and relaunch with killall and open.

After that, every time you connect to your headless Mac Mini or Mac Studio, the Matrix rain is already running. Your vibe coding setup looks exactly the way it should.