PENUMBRA
HELP

Penumbra is a native macOS client for Sunshine hosts. It pairs with a host, keeps it awake, and streams a live preview of its screen to your menu bar. This page covers the problems people hit most often and how to resolve them.

The host doesn't appear during setup

Penumbra discovers Sunshine hosts on your local network automatically, but discovery can fail on networks that block mDNS/Bonjour or across VLANs.

• Confirm Sunshine is running on the host and that both machines are on the same network.
• Enter the host's IP address or hostname by hand on the setup screen. This always works when discovery doesn't.
• If you use a hostname and it fails, try the raw IP address instead.

Pairing fails or the PIN is rejected

When you pair, Penumbra shows a PIN that you enter in Sunshine's web UI on the host.

• Make sure you enter the PIN on Sunshine's PIN page, not another settings page.
• Some Sunshine hosts reject the PIN with a CSRF or origin error when the web UI is opened from a different origin. If that happens:
  • Submit the PIN from Sunshine's web UI on the host itself (for example, from a browser running on that machine), or
  • Set origin_web_ui_allowed to your network (lan or wan) in Sunshine's configuration and restart Sunshine, then pair again.
• If the PIN expires while you're finding the page, start pairing again for a fresh one.

No preview, or a black screen

• The menu-bar preview only updates while Penumbra is connected. Open the menu and connect first.
• If the preview stays black after connecting, disconnect and reconnect to force a fresh keyframe.
• Confirm the chosen app is still available on the host. If it was removed in Sunshine, pick a different app.

No audio

• Audio plays only while the full window is open. The menu-bar preview is intentionally silent.
• Penumbra plays stereo audio. Hosts configured to encrypt audio, or to send surround only, are not supported.

Keyboard shortcuts paste on the wrong machine

• Turn on Remap ⌘ to Ctrl on host in the menu to make Mac editing shortcuts (⌘C, ⌘V, and so on) drive the host's own copy and paste.
• To push your Mac's clipboard to the host as typed text, use Send Clipboard to Host (⌃⌘V). This works only on hosts whose Sunshine accepts UTF-8 text input.

The host still goes to sleep or locks

• Penumbra sends a periodic keep-alive input. Lower the Keep-alive input every interval in the menu if the host still idles.
• Some hosts lock on a separate OS timer that input can't defer. Adjust the host's own sleep and lock settings if the keep-alive isn't enough.

The connection drops on Wi-Fi

• Penumbra uses a fixed bitrate and requests a fresh keyframe after a lost frame, so a weak link shows stutter and full-frame hitches rather than adapting down.
• Move closer to the access point or use a wired connection on the host for a steadier stream.

Still stuck?

Note what you were doing, the host's Sunshine version, and any error text shown in Sunshine's web UI, and reach out through Anthology Group.