Application Configuration

Add and configure applications and games for streaming

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)

1. Open Sunshine Web UI at https://localhost:47990
2. Navigate to Applications or Configuration > Applications
3. Click Add New or similar button
4. Fill in the application details
5. 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

Basic Desktop

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

Steam Big Picture

Windows

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

Linux/FreeBSD

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

macOS

{
  "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

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

Linux/FreeBSD

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

macOS

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

Steam Game (Direct Executable)

Windows

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

Linux

{
  "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)

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.

Windows (QRes)

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"
  }
]

Linux (X11)

"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"
  }
]

Linux (Wayland)

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"
  }
]

macOS

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