Remote Desktop

Overview

Sunshine serves a remote desktop on desktop, laptop and potato; Moonlight connects to it from any of the others. Hosts are reachable both over the WireGuard VPN and on the local network, and each one carries a certificate signed by a private CA so the web UI validates without a browser warning.

Host VPN address Streaming name
desktop 10.100.0.2 stream-desktop.yhkze.net
laptop 10.100.0.3 stream-laptop.yhkze.net
potato 10.100.0.4 stream-potato.yhkze.net

The names resolve through networking.hosts, declared in modules/features/sunshine.nix, so they work without a public DNS record.

Reference modules/features/sunshine.nix.

Certificate Model

Sunshine presents a single certificate for two unrelated purposes: TLS for the web UI, and the host identity Moonlight pins when pairing. Upstream declined to separate them, which constrains what the certificate may be.

Both rules exclude the ACME wildcard that Traefik and the mail server use: that certificate is EC-256 and renews roughly every 60 days, which would force every Moonlight client to re-pair on each renewal. A private CA issuing long-lived leaves satisfies both rules instead.

graph LR
    CA["Internal CA<br/>(private key offline)"]
    L1["stream-desktop leaf<br/>RSA-2048, 10 y"]
    L2["stream-laptop leaf<br/>RSA-2048, 10 y"]
    L3["stream-potato leaf<br/>RSA-2048, 10 y"]
    T["Workstation trust stores<br/>security.pki.certificateFiles"]
    M["Moonlight<br/>pins leaf at pairing"]

    CA -->|signs| L1
    CA -->|signs| L2
    CA -->|signs| L3
    CA -->|public cert committed as<br/>resources/yhkze-ca.pem| T
    L2 -->|served on :47990| T
    L2 --> M

The CA’s public certificate lives in resources/yhkze-ca.pem and is trusted by every workstation, since each host is also a client. The CA’s private key never enters the repository or any host — it is kept offline in KeePassXC and only used to sign a new leaf.

Each leaf is stored per host in hosts/<host>/secrets/secrets.yaml under sunshine/cert.pem and sunshine/key.pem.

Issuing Certificates

Create the CA once. Keep yhkze-ca.key offline and commit only the public certificate.

openssl genrsa -out yhkze-ca.key 4096
openssl req -x509 -new -nodes -key yhkze-ca.key -sha256 -days 3650 \
  -subj "/CN=yhkze.net internal CA" -out yhkze-ca.pem

Issue one leaf per host. The example covers laptop; substitute the name and VPN address from the table above for the others. The key length is not optional.

openssl genrsa -out sunshine-laptop.key 2048
openssl req -new -key sunshine-laptop.key \
  -subj "/CN=stream-laptop.yhkze.net" -out sunshine-laptop.csr
openssl x509 -req -in sunshine-laptop.csr -CA yhkze-ca.pem -CAkey yhkze-ca.key \
  -CAcreateserial -days 3650 -sha256 -out sunshine-laptop.pem \
  -extfile <(printf 'subjectAltName=DNS:stream-laptop.yhkze.net,IP:10.100.0.3\nbasicConstraints=critical,CA:FALSE\nkeyUsage=critical,digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n')

The subjectAltName carries both the name and the VPN address, so either form of access validates. A certificate without it is rejected by browsers regardless of trust, because they ignore the common name.

Store the pair in the host’s vault with sops hosts/laptop/secrets/secrets.yaml, as YAML literal blocks.

sunshine:
    cert.pem: |
        -----BEGIN CERTIFICATE-----
        ...
    key.pem: |
        -----BEGIN PRIVATE KEY-----
        ...

Deploy with the rebuild script, then restart the service. Sunshine runs as a user service, so sops cannot restart it through restartUnits.

systemctl --user restart sunshine

Pairing a Client

Sunshine issues a PIN challenge that is confirmed from its web UI.

  1. In Moonlight, add the host by its streaming name or VPN address and start pairing. Moonlight shows a PIN

  2. Open https://stream-<host>.yhkze.net:47990/pin and submit the PIN

    Sunshine only accepts the pairing form from origins listed in csrf_allowed_origins, which the module sets to the host’s streaming name and VPN address. Reaching the UI by any other address, such as a DHCP local-network address, is refused by CSRF protection — submit from https://localhost:47990/pin on the host itself in that case, which is always permitted

  3. Confirm the host appears in Moonlight and launch an app

Replacing a host’s certificate invalidates existing pairings. Clients that were paired beforehand must pair again; if one keeps reporting a certificate mismatch, remove its entry under .root.named_devices in ~/.config/sunshine/sunshine_state.json and restart the service.

Settings and Applications

Sunshine owns its own sunshine.conf and apps.json under ~/.config/sunshine, so encoder, bitrate, resolution and applications are all editable from its web UI and persist across reboots.

Sunshine copies a default apps.json out of its package on first run and inherits that file’s read-only mode from the Nix store, which leaves the Applications tab unable to save. An activation step in modules/features/sunshine.nix restores write permission without touching existing content.

Three values are pinned by modules/features/sunshine.nix regardless of what that UI writes, because they are security properties rather than preferences: cert and pkey carry host identity, and csrf_allowed_origins decides who may submit a pairing PIN. They are passed as name=value arguments on Sunshine’s command line, which it merges over its configuration file, so a declared value always wins while every other key stays mutable.

services.sunshine.settings is deliberately left unset. Declaring it renders sunshine.conf into a read-only store path, and as that option’s own description warns, no configuration is then possible from the web UI.

Editing a pinned value in the web UI appears to succeed and is silently ineffective — change it in the module instead.

Renewal

The CA and the leaves expire in 2036. Renewing a leaf means repeating the issuance steps for that host and pairing every client to it again, so the expiry is deliberately long. Renewing the CA additionally requires re-signing every leaf and updating resources/yhkze-ca.pem.