# Moonlight clients

This directory covers installing Moonlight on the devices that connect to your
Sunshine host. The host side (Sunshine on Linux) is documented in the
[top-level README](../README.md).

## Install

### macOS

From a Mac that has this repo checked out:

```sh
./client/install-macos.sh
```

The script verifies Homebrew is present and runs `brew install --cask moonlight`.
It will not install Homebrew for you.

Manual equivalent:

```sh
brew install --cask moonlight
```

Fallback (no Homebrew): download a signed DMG from the official releases page
and drag `Moonlight.app` into `/Applications`:

- https://github.com/moonlight-stream/moonlight-qt/releases

### Android

Install "Moonlight Game Streaming" from the Play Store:

- https://play.google.com/store/apps/details?id=com.limelight

### iOS / iPadOS

Install "Moonlight Game Streaming" from the App Store:

- https://apps.apple.com/us/app/moonlight-game-streaming/id1000551566

### Apple TV

Same listing on the tvOS App Store. Search "Moonlight Game Streaming" on the
Apple TV itself, or use the App Store link above from an iOS device signed in
to the same Apple ID.

### Steam Deck / Linux

Use `moonlight-qt` from your distro's package manager (Flatpak on Steam Deck,
`pacman`/`apt` elsewhere). It is the same Qt-based client as macOS and Windows.

## First pair

The pairing flow is the same on every client.

1. Confirm the host is healthy. On the host machine:

   ```sh
   ./install.sh --doctor
   ```

   Sunshine must be running and reachable on the LAN.

2. On the client, open Moonlight. The host should appear automatically via
   mDNS as long as the client is on the same LAN. If it does not appear, use
   "Add Host Manually" and enter the host's LAN IP address.

3. Click or tap the host. Moonlight displays a 4-digit PIN.

4. On the host machine, open the Sunshine web UI:

   ```
   https://localhost:47990
   ```

   Accept the self-signed certificate. Log in (credentials are set the first
   time you visit). Go to the PIN tab, enter the 4-digit PIN from the client,
   and submit. Pairing typically completes within about 5 seconds.

5. Back in Moonlight, the host now shows as "Paired". Click it to see the
   available apps. The default app is "Desktop", which is either a full-screen
   mirror of the host's display or a headless virtual display, depending on
   how the host is configured.

## Streaming notes

- **Resolution.** Moonlight lets you pick a target stream resolution per host.
  On a headless-configured host, that resolution is what the host actually
  renders at. On a mirror-configured host, the host renders at its native
  resolution and Moonlight downscales on the client.

- **Bitrate.** Moonlight's defaults are conservative for general internet use.
  For LAN streaming, bump it to 50-100 Mbps.

- **Audio.** By default, Moonlight captures audio from the host and plays it
  on the client. If you want the host's speakers/monitor to keep playing
  audio while you stream, enable "Play audio on host" in Moonlight's stream
  settings.

## Troubleshooting

- **"Host not found" / host does not appear automatically.** Confirm both
  machines are on the same LAN/VLAN. mDNS does not traverse VLANs without an
  mDNS reflector. Fall back to "Add Host Manually" with the host's IP.

- **Pairing PIN does not work.** Two common causes: the Sunshine web UI
  session has timed out (log in again and re-enter the PIN), or the PIN is
  being entered into the wrong host (multiple Sunshine instances on the LAN).
  Cancel and re-trigger pair from the client to get a fresh PIN.

- **Black screen after pairing.** This is a host-side problem. On the host:

  ```sh
  ./install.sh --doctor
  ```

- **Mac cannot reach `brew`.** Homebrew is not installed (or not on `PATH`).
  Install it per https://brew.sh, open a fresh shell, then re-run
  `./client/install-macos.sh`.

- **Android sees the host but cannot connect.** The Android device is
  probably on a guest WiFi SSID that is isolated from the main LAN. Move it
  to the main LAN, or use "Add Host Manually" with the host IP.