Application Configuration

Applications allow you to launch games and programs directly from Moonlight. Each application can have custom commands, working directories, and preparation commands.

Adding Applications

Applications are configured through the Sunshine Web UI or by editing the apps.json file.

Via Web UI (Recommended)

Open Sunshine Web UI at https://localhost:47990
Navigate to Applications or Configuration > Applications
Click Add New or similar button
Fill in the application details
Save the application

Via apps.json File

The apps.json file is located in your Sunshine configuration directory. It contains a JSON array of application objects.

Manually editing JSON requires valid syntax. Use the Web UI to avoid errors.

Application Fields

name

string

required

The display name shown in Moonlight.

"name": "Desktop"

cmd

string

required

The command or executable to launch.

"cmd": "C:\\Program Files\\Steam\\steam.exe"

output

string

Log file path for application output (useful for debugging).

"output": "steam.log"

working-dir

string

Working directory for the application. Defaults to the executable’s directory if not specified.

"working-dir": "C:\\Program Files\\Steam"

detached

array

Commands to run detached (don’t wait for completion). Useful for launchers that spawn child processes.

"detached": ["steam://open/bigpicture"]

image-path

string

Path or URL to cover image displayed in Moonlight.

"image-path": "desktop.png"

elevated

boolean

Run with elevated privileges (Windows only, requires Sunshine service).

"elevated": false

exclude-global-prep-cmd

boolean

Skip global prep commands for this application.

"exclude-global-prep-cmd": false

prep-cmd

array

Commands to run before/after launching the application.Each entry can have:

do - Command to run before launch
undo - Command to run after exit
elevated - Run with elevated privileges (Windows)

"prep-cmd": [
  {
    "do": "cmd /C \"FullPath\\qres.exe /x:1920 /y:1080\"",
    "undo": "cmd /C \"FullPath\\qres.exe /x:2560 /y:1440\""
  }
]

Common Application Examples

Desktop

{
  "name": "Desktop",
  "output": "",
  "cmd": "",
  "image-path": "desktop.png"
}

Steam Big Picture

Windows
Linux/FreeBSD
macOS

{
  "name": "Steam Big Picture",
  "output": "",
  "detached": ["steam://open/bigpicture"],
  "prep-cmd": [
    {
      "undo": "steam://close/bigpicture"
    }
  ],
  "image-path": "steam.png"
}

{
  "name": "Steam Big Picture",
  "output": "",
  "detached": ["setsid steam steam://open/bigpicture"],
  "prep-cmd": [
    {
      "undo": "setsid steam steam://close/bigpicture"
    }
  ],
  "image-path": "steam.png"
}

{
  "name": "Steam Big Picture",
  "output": "",
  "detached": ["open steam://open/bigpicture"],
  "prep-cmd": [
    {
      "undo": "open steam://close/bigpicture"
    }
  ],
  "image-path": "steam.png"
}

Steam Game (URI Method)

Windows
Linux/FreeBSD
macOS

{
  "name": "Surviving Mars",
  "output": "",
  "detached": ["steam://rungameid/464920"],
  "image-path": "surviving-mars.png"
}

{
  "name": "Surviving Mars",
  "output": "",
  "detached": ["setsid steam steam://rungameid/464920"],
  "image-path": "surviving-mars.png"
}

{
  "name": "Surviving Mars",
  "output": "",
  "detached": ["open steam://rungameid/464920"],
  "image-path": "surviving-mars.png"
}

Steam Game (Direct Executable)

Windows
Linux

{
  "name": "Surviving Mars",
  "output": "",
  "cmd": "MarsSteam.exe",
  "working-dir": "C:\\Program Files (x86)\\Steam\\steamapps\\common\\Surviving Mars",
  "image-path": "surviving-mars.png"
}

{
  "name": "Surviving Mars",
  "output": "",
  "cmd": "MarsSteam",
  "working-dir": "~/.steam/steam/SteamApps/common/Surviving Mars",
  "image-path": "surviving-mars.png"
}

Epic Games Store Game

{
  "name": "Surviving Mars",
  "output": "",
  "cmd": "com.epicgames.launcher://apps/d759128018124dcabb1fbee9bb28e178%3A20729b9176c241f0b617c5723e70ec2d%3AOvenbird?action=launch&silent=true",
  "image-path": "surviving-mars.png"
}

Preparation Commands

Preparation commands allow you to change system settings before launching an application and restore them afterward.

Change Resolution and Refresh Rate

Windows (Built-in)
Windows (QRes)
Linux (X11)
Linux (Wayland)
macOS

Sunshine has built-in Windows display configuration. See the Audio/Video Configuration page for Windows-specific settings like dd_resolution_option and dd_refresh_rate_option.

Using the QRes tool:

"prep-cmd": [
  {
    "do": "cmd /C \"C:\\Tools\\qres.exe /x:%SUNSHINE_CLIENT_WIDTH% /y:%SUNSHINE_CLIENT_HEIGHT% /r:%SUNSHINE_CLIENT_FPS%\"",
    "undo": "C:\\Tools\\qres.exe /x:2560 /y:1440 /r:144"
  }
]

"prep-cmd": [
  {
    "do": "sh -c \"xrandr --output HDMI-1 --mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} --rate ${SUNSHINE_CLIENT_FPS}\"",
    "undo": "xrandr --output HDMI-1 --mode 3840x2160 --rate 120"
  }
]

Using wlr-xrandr for wlroots compositors:

"prep-cmd": [
  {
    "do": "sh -c \"wlr-xrandr --output HDMI-1 --mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}@${SUNSHINE_CLIENT_FPS}Hz\"",
    "undo": "wlr-xrandr --output HDMI-1 --mode 3840x2160@120Hz"
  }
]

Using displayplacer:

"prep-cmd": [
  {
    "do": "sh -c \"displayplacer \\\"id:<screenId> res:${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} hz:${SUNSHINE_CLIENT_FPS} scaling:on origin:(0,0) degree:0\\\"\"",
    "undo": "displayplacer \"id:<screenId> res:3840x2160 hz:120 scaling:on origin:(0,0) degree:0\""
  }
]

Environment Variables

Sunshine provides environment variables you can use in commands:

SUNSHINE_CLIENT_WIDTH

number

Resolution width requested by the client

SUNSHINE_CLIENT_HEIGHT

number

Resolution height requested by the client

SUNSHINE_CLIENT_FPS

number

Frame rate requested by the client

SUNSHINE_CLIENT_HDR

string

Whether client requested HDR (“true” or “false”)

SUNSHINE_APP_ID

number

The unique identifier of the currently running application

SUNSHINE_APP_NAME

string

The name of the currently running application

Cover Images

Cover images are displayed in the Moonlight app selection screen.

Image Format

Supported formats: PNG, JPG, JPEG
Recommended size: 1280x720 or 1920x1080
Aspect ratio: 16:9

Image Location

Relative Paths: Place images in the Sunshine configuration directory:

"image-path": "steam.png"

Absolute Paths:

"image-path": "C:\\Images\\steam.png"

URLs:

"image-path": "https://example.com/images/game-cover.jpg"

Platform-Specific Considerations

Windows

Elevated Privileges

If Sunshine is installed as a service (default), you can run applications with administrator privileges:

{
  "name": "Game With AntiCheat",
  "cmd": "game.exe",
  "elevated": true
}

This launches without UAC prompt when using Sunshine service.

Path Escaping

Use double backslashes in JSON:

"cmd": "C:\\Program Files\\Game\\game.exe"

Linux (Flatpak)

Flatpak runs in a sandbox. Commands must be prefixed with flatpak-spawn --host:

"cmd": "flatpak-spawn --host steam"

macOS

Use open command for applications and URLs:

"cmd": "open -a \"Game Name\""

Complete Example

Here’s a complete application configuration with resolution changes:

{
  "name": "Cyberpunk 2077",
  "output": "cyberpunk.log",
  "cmd": "steam://rungameid/1091500",
  "detached": ["steam://rungameid/1091500"],
  "exclude-global-prep-cmd": false,
  "elevated": false,
  "prep-cmd": [
    {
      "do": "cmd /C \"C:\\Tools\\qres.exe /x:%SUNSHINE_CLIENT_WIDTH% /y:%SUNSHINE_CLIENT_HEIGHT% /r:%SUNSHINE_CLIENT_FPS%\"",
      "undo": "C:\\Tools\\qres.exe /x:2560 /y:1440 /r:144",
      "elevated": false
    }
  ],
  "image-path": "cyberpunk2077.png"
}

Troubleshooting

Application won't launch

Check output log for errors
Verify executable path and working directory
Test command manually in terminal
Check if elevated privileges are needed

Wrong resolution

Verify prep-cmd syntax
Check environment variables are available
Enable “Optimize game settings” in Moonlight
Test prep-cmd manually

Steam games don't launch

Use URI method: steam://rungameid/<appid>
Add to detached commands
Ensure Steam is running
Check game AppID is correct

Cover image not showing

Check image path is correct
Verify image format (PNG/JPG)
Use absolute path or URL
Restart Moonlight client

Prep commands fail

Check command syntax
Test commands manually
Verify tools are installed
Check elevated permissions if needed

Best Practices

Use URI Methods

For Steam/Epic games, use launcher URIs instead of direct executables for better compatibility

Test Commands

Always test prep commands manually before adding to configuration

Add Logging

Use the output field to capture logs for troubleshooting

Environment Variables

Use SUNSHINE_CLIENT_* variables for dynamic resolution changes

Next Steps

General Settings

Configure global prep commands

Audio/Video

Optimize streaming quality for your applications

Get Started

Installation

Configuration

Guides

Deployment

Application Configuration

Adding Applications

Via Web UI (Recommended)

Via apps.json File

Application Fields

Common Application Examples

Desktop

Steam Big Picture

Steam Game (URI Method)

Steam Game (Direct Executable)

Epic Games Store Game

Preparation Commands

Change Resolution and Refresh Rate

Environment Variables

Cover Images

Image Format

Image Location

Platform-Specific Considerations

Windows

Linux (Flatpak)

macOS

Complete Example

Troubleshooting

Best Practices

Use URI Methods

Test Commands

Add Logging

Environment Variables

Next Steps

General Settings

Audio/Video

Build docs developers (and LLMs) love

Get Started

Installation

Configuration

Guides

Deployment

​Adding Applications

​Via Web UI (Recommended)

​Via apps.json File

​Application Fields

​Common Application Examples

​Desktop

​Steam Big Picture

​Steam Game (URI Method)

​Steam Game (Direct Executable)

​Epic Games Store Game

​Preparation Commands

​Change Resolution and Refresh Rate

​Environment Variables

​Cover Images

​Image Format

​Image Location

​Platform-Specific Considerations

​Windows

​Linux (Flatpak)

​macOS

​Complete Example

​Troubleshooting

​Best Practices

Use URI Methods

Test Commands

Add Logging

Environment Variables

​Next Steps

General Settings

Audio/Video

Build docs developers (and LLMs) love

Adding Applications

Via Web UI (Recommended)

Via apps.json File

Application Fields

Common Application Examples

Desktop

Steam Big Picture

Steam Game (URI Method)

Steam Game (Direct Executable)

Epic Games Store Game

Preparation Commands

Change Resolution and Refresh Rate

Environment Variables

Cover Images

Image Format

Image Location

Platform-Specific Considerations

Windows

Linux (Flatpak)

macOS

Complete Example

Troubleshooting

Best Practices

Next Steps