Moonshine lets you stream games from your PC to any device running Moonlight. Your keyboard, mouse, and controller inputs are sent back to the host so you can play games remotely as if you were sitting in front of it.
- Isolated streaming sessions: Each stream runs in its own compositor, completely separate from your desktop environment. Your host PC can still be used for other things while you stream.
- No monitor required: Works on headless servers — no HDMI dummy plug needed.
- Hardware video encoding: H.264, H.265, and AV1 encoding using the GPU.
- HDR support: True 10-bit HDR streaming for supported games.
- Full input support: Mouse, keyboard, touchscreen, pen/stylus, and gamepad (including motion, touchpad, and haptics).
- Audio streaming: Stereo and surround sound (5.1/7.1) with low-latency Opus encoding.
- Linux only. Available as
.deb,.rpm, Nix, AUR, and an install script for SteamOS. Tested on Arch Linux, but reported to work on other distributions too. - systemd. Required for launching and managing application processes. Almost all modern Linux distributions include it by default.
- A GPU with Vulkan video encoding. NVIDIA RTX, AMD RDNA2+, or Intel Arc.
- Moonlight v6.0.0 or higher. Compatibility with older versions or unofficial ports is not guaranteed.
The recommended method is to install through the AUR using:
yay -S moonshine-bin
After installing, follow the distro-agnostic Enable the service steps below.
Download the latest .deb from the releases page and install it:
sudo apt install ./moonshine_*.debAfter installing, follow the Enable the service steps below.
Download the latest .rpm from the releases page and install it:
sudo dnf install ./moonshine-*.rpmThe package's post-install scripts set up udev rules, kernel modules, and the moonshine group automatically.
After installing, follow the Enable the service steps below.
On NixOS, use the services.moonshine module. It installs the package and handles everything in Enable the service, so skip those steps.
Moonshine and its module are in nixpkgs:
services.moonshine = {
enable = true;
user = "alice"; # must be declared in users.users
# Required: the default application points at /usr/bin/steam, which doesn't exist on NixOS.
settings.application = [
{
title = "Steam";
command = [ "/run/current-system/sw/bin/steam" "steam://open/bigpicture" ];
steam_integration = true;
}
];
# Opens the ports on these interfaces only; see Security below.
# firewallInterfaces = [ "tailscale0" ];
};See all options at search.nixos.org.
This repository is also a flake that builds from the latest commit. Add it to your system flake's inputs and import its module. See nix/README.md for details.
The flake module replaces the nixpkgs one, and its options are slightly different: openFirewall instead of firewallInterfaces, a uid option you may need to set if the user's uid isn't declared in your config, and the user isn't added to input for you.
The flake package (nix profile install github:hgaiser/moonshine) has only the binary, udev rules and Vulkan layer. It doesn't include the systemd unit, so on other distros use one of the native packages above.
On Fedora Atomic distros, download the .rpm from the releases page and layer it:
sudo rpm-ostree install ./moonshine-*.rpm
sudo systemctl rebootAfter reboot, follow the Enable the service steps below.
Use the installer script:
curl -fsSL https://github.com/hgaiser/moonshine/releases/latest/download/moonshine-install.sh | bashThis deploys moonshine to /opt/moonshine/ and configuration drop-ins to /etc/. The installer registers these files with SteamOS so they persist across atomic updates.
These steps apply to every installation method above (the service is a systemd unit).
-
Enable user lingering:
sudo loginctl enable-linger $USERThis allows Moonshine to run applications in the user's session even when the user is not logged in (when running headless).
If your user is always logged in when you want to stream, you can skip this step.
-
Enable the service to start on boot and run immediately:
sudo systemctl enable --now moonshine@$USER
-
Gamepad support when streaming headless (no active desktop session): add your user to the
inputgroup, then log out and back in (or reboot) for it to take effect:sudo usermod -aG input $USERMoonshine creates a virtual gamepad per streamed controller, and the streamed game must be able to read it. When streaming while a desktop session is active, your user is already granted access to input devices as the active seat, so this step is not needed there. Run
moonshine healthcheckto verify — it reports aninput groupwarning if the group is missing.
The following dependencies are required to build and run:
# Build dependencies
sudo pacman -S --asdeps \
clang \
cmake \
jq \
libc++ \
rust
# Runtime dependencies
sudo pacman -S \
gcc-libs \
glibc \
libevdev \
libxkbcommon \
mesa \
opus \
wayland \
xorg-xwaylandThen build:
cargo build --release --workspaceSet up the environment:
# Install uinput/uhid kernel modules
sudo install -Dm644 dist/moonshine-modules.conf /usr/lib/modules-load.d/moonshine.conf
sudo modprobe uinput uhid
# Install udev rules for input device access
sudo install -Dm644 dist/60-moonshine.rules /usr/lib/udev/rules.d/60-moonshine.rules
sudo udevadm control --reload-rules
# Install ferriscope's Vulkan WSI layer for game rendering
dist/install-wsi.sh # builds as you, asks for sudo only to installThen run:
cargo run --release -- /path/to/config.tomlA configuration file is created automatically if the path you provide doesn't exist.
When using the AUR package, it defaults to $XDG_CONFIG_HOME/moonshine/config.toml.
Moonshine has a web control panel at http://localhost:47990 . With it you can:
- See the stream that runs now, with live graphs of latency, bitrate and frame rate, and stop it.
- See the health checks, and run them again.
- Pair new devices with their PIN, and rename or unpair paired devices.
- Add and edit applications and scanners, and hide scanned applications from clients.
- Change settings. Each setting shows if it applies now, at the next stream, or after a restart.
- Read the logs, and download a report for bug reports.
The control panel writes its changes to config.toml and keeps your comments in place.
By default, only this computer can open it. To open it from other devices, add their address range:
[ui]
port = 47990
allowed_networks = ["127.0.0.1/32", "::1/128", "192.168.1.0/24"]The control panel only answers to an IP address, localhost or this computer's name. To open it through a reverse proxy at another name, add that name to allowed_hosts, and add the address of the proxy to allowed_networks:
[ui]
allowed_networks = ["127.0.0.1/32", "::1/128", "100.64.0.0/10"]
allowed_hosts = ["moonshine.example.com"]The control panel then sees the address of the proxy, not the address of the browser. So anyone who can reach the proxy can open the control panel. Put authentication on the proxy, or only make it reachable from networks you trust.
Warning
Anyone who can open the control panel can add applications, which run commands as your user. Only add address ranges that you trust. The control panel has no password.
Set enabled = false in the [ui] table to turn the control panel off.
When you connect with Moonlight for the first time, it will show a PIN. Type it on the Clients page of the control panel. A notification will also appear on the host that you can click to open the pairing page, or you can visit it manually at http://localhost:47989/pin .
You can also pair from the command line:
curl -X POST "http://localhost:47989/submit-pin" -d "uniqueid=0123456789ABCDEF&pin=<PIN>"Each application runs in its own isolated streaming session. Add them to config.toml like this:
[[application]]
title = "Steam"
boxart = "/path/to/steam.png" # optional
command = ["/usr/bin/steam", "steam://open/bigpicture"]
steam_integration = truetitle: The name shown in Moonlight.boxart(optional): Path to a cover image.command: The command to run. First entry is the executable, the rest are arguments.working_directory(optional): The directory to start the application in, for example a game that loads its data from the directory it runs in.~and environment variables are expanded, and the directory has to exist. Thepre_commandandpost_commandcommands run there too. Defaults to your home directory.pre_command(optional): Commands to run before launching the application. Each entry is a separate command, executed in order. Runs synchronously — the session waits for all to finish.steam_integration(optional): Steam integration, as gamescope's-e; off by default. Turn it on for Steam (Big Picture), so its overlay and focus work. With it on, only Steam and Steam game windows can take focus, so leave it off for anything launched directly. With it off, Steam acts as on a desktop: its power menu has "Exit Big Picture Mode", not "Switch to Desktop". Games from the Steam application scanner have it on.post_command(optional): Commands to run after the streaming session ends. Each entry is a separate command, executed in order. Runs synchronously — the server waits for all to finish.
Example:
[[application]]
title = "Steam"
command = ["/usr/bin/steam", "steam://open/bigpicture"]
steam_integration = true
pre_command = [
["/usr/bin/systemctl", "stop", "conflicting.service"],
]
post_command = [
["/usr/bin/systemctl", "start", "conflicting.service"],
]Scanners automatically detect installed applications so you don't have to add them manually.
Steam scanner — finds all installed Steam games:
[[application_scanner]]
type = "steam"
library = "$HOME/.local/share/Steam"
command = ["/usr/bin/steam", "-bigpicture", "steam://rungameid/{game_id}"]Desktop scanner — finds applications from .desktop files:
[[application_scanner]]
type = "desktop"
directories = [
"$HOME/.local/share/applications",
"/usr/share/applications",
]
include_terminal = false
resolve_icons = trueLutris scanner — finds all installed Lutris games:
[[application_scanner]]
type = "lutris"
command = ["/usr/bin/lutris", "lutris:rungame/{slug}"]Games are matched by their Lutris slug.
Box art is automatically loaded from Lutris's coverart/ directory when available.
The default database path is ~/.local/share/lutris/pga.db.
You can override it with the pga_db option to point at a custom database location.
Heroic scanner — finds all installed Heroic Games Launcher games (Epic, GOG, Amazon and manually added games):
[[application_scanner]]
type = "heroic"
command = ["heroic", "--no-gui", "heroic://launch?appName={app_name}&runner={runner}"]If you installed Heroic from Flathub, launch it through Flatpak instead:
[[application_scanner]]
type = "heroic"
command = [
"dbus-run-session", "--",
"flatpak", "run", "com.heroicgameslauncher.hgl",
"--no-gui", "heroic://launch?appName={app_name}&runner={runner}",
]The dbus-run-session prefix keeps the game inside Moonshine's compositor instead of on your desktop.
See TIPS.md for why Flatpak needs it.
{app_name} is Heroic's internal game id and {runner} is the store it came from (legendary for Epic, gog for GOG, nile for Amazon, sideload for manually added games).
Commands are resolved against Moonshine's own PATH, which under the packaged systemd service is systemd's default rather than your login shell's.
A bare heroic therefore works for packages that install into /usr/bin, but not for an AppImage or anything under ~/.local/bin; use an absolute path in those cases.
Box art is automatically loaded from Heroic's images-cache/ directory for any art Heroic has already downloaded.
The default configuration directory is ~/.config/heroic, falling back to ~/.var/app/com.heroicgameslauncher.hgl/config/heroic when only the Flatpak is installed.
You can override it with the config_dir option.
Bottles scanner — finds games and applications in the Bottles Library tab:
[[application_scanner]]
type = "bottles"
command = ["bottles-cli", "run", "-b", "{bottle}", "--program-id", "{program_id}"]
umu_command = ["bottles-cli", "umu", "run", "--game", "{umu_game}"]Only entries you added to Bottles' Library ("Add to Library" on a program) are exposed — not every program Bottles discovers. UMU entries appear once Bottles reports them as ready, and Steam shortcuts in the Library are skipped. umu_command is optional: without it, UMU entries are skipped.
Limitation: Bottles launches executables that live outside the bottle (e.g. on a separate game drive) through
wine start, which exits immediately, so Moonshine ends the session shortly after launch. Games installed inside the bottle prefix are unaffected.
{bottle} is the bottle's name, {program_id} the program's internal id, {name} the entry's display name, and {umu_game} the id of a game managed through Bottles' UMU integration.
Commands are resolved against Moonshine's own PATH, so a bare bottles-cli only works for a natively installed Bottles. For Flatpak Bottles, see TIPS.md.
The default data directory is the first of ~/.local/share/bottles and ~/.var/app/com.usebottles.bottles/data/bottles that contains a library.yml — leftover data from an uninstalled native Bottles does not shadow the Flatpak install.
You can override it with the data_dir option.
Box art is automatically loaded from Bottles' grid images when available, falling back to the program's icon.
Faugus scanner — finds the games in your Faugus Launcher library:
[[application_scanner]]
type = "faugus"
command = ["faugus-launcher", "--game", "{game_id}"]{game_id} is the game's Faugus id.
Each game starts in the folder holding its executable (its working_directory), as it does when launched from Faugus' window: faugus-launcher --game on its own keeps the caller's directory, and some games quit right away when started anywhere else.
Hidden games are skipped unless you set include_hidden = true, and so are games using Faugus' Steam runner, which hands the game to Steam and exits shortly after; the Steam scanner launches those.
Box art is automatically loaded from the game's cover in Faugus when available, falling back to its banner and then its icon.
If you installed Faugus from Flathub, launch it through Flatpak, with the same dbus-run-session prefix as for Heroic:
[[application_scanner]]
type = "faugus"
command = [
"dbus-run-session", "--",
"flatpak", "run", "--command=/app/bin/faugus-launcher", "io.github.Faugus.faugus-launcher",
"--game", "{game_id}",
]The default data directory is the first of ~/.local/share/faugus-launcher and ~/.var/app/io.github.Faugus.faugus-launcher/data/faugus-launcher that contains a games.json, followed by the same under ~/.config and ~/.var/app/io.github.Faugus.faugus-launcher/config, where older Faugus releases kept their library.
You can override it with the data_dir option.
See TIPS.md for practical recipes and workarounds.
-
How does this compare to Sunshine?
- Sunshine supports more platforms and has more features overall. Moonshine is Linux-only.
- Moonshine runs each streaming session in its own isolated environment, separate from your desktop. This means your host PC stays usable while you stream, and it works without an active desktop session.
-
Can I use Moonshine to stream to two clients simultaneously?
This is currently not a supported feature and not a focus of Moonshine. If you are interested in adding support for this, feel free to open an issue or discuss on Discord.
-
How do I run the healthcheck?
Run
moonshine healthcheckto check GPU capabilities, codec support, and port availability. Pass--config <path>to also check configured ports and GPU preferences.
Moonshine is not designed for use on public networks. The underlying GameStream protocol has limitations that mean traffic is not fully encrypted at the application level.
If you need to stream over the internet, use a VPN such as Tailscale, WireGuard, or ZeroTier.
Do not expose Moonshine ports directly to the internet.
This wouldn't have been possible without the incredible work by the people behind the following projects:
- Moonlight, without it there would be no client for Moonshine.
- Sunshine, which laid a lot of the groundwork for the host part of the API.
- Inputtino, for a thorough implementation of input devices.
- magic-mirror, for inspiration of using Vulkan and a Wayland compositor for headless streaming.
