XBOX PC Remote (wdRemote.exe)

The XBOX PC Toolbox app is in preview. Download it from the Microsoft Store on Windows.

XBOX PC Remote (wdRemote.exe) is a command-line tool that enables two workflows that are required for building games on remote Windows devices. Use these two commands to:

Establish a trusted, secure connection between a development PC and a remote device using PIN pairing.
Deploy, launch, and terminate games on a remote Windows device.

wdRemote runs on a development PC and communicates with an instance of wdEndpoint.exe running on the remote device. See the Overview of XBOX PC Remote tools for a description of the role wdRemote and wdEndpoint play in the suite of remote development tools for Windows devices. Use either the XBOX PC Toolbox or WinGet to install wdRemote on your development PC. winget install Microsoft.Gaming.RemoteIterationClient Use wdRemote to run the commands listed in the following table.

Command	Description
wdRemote /action:pair	Establishes a trusted, secure connection between a development PC and the remote device via PIN pairing.
wdRemote /action:purgekeys	Removes all encryption keys and device pairings from a development PC
wdRemote /action:version	Displays the version of wdRemote.exe.
wdRemote /action:status	Displays the status of the connection between the development PC and the target device.
wdRemote /action:deploy	Deploys a game from a development PC to a remote Windows device.
wdRemote /action:launch	Launches a game on a remote Windows device.
wdRemote /action:resume	Resumes a game on a remote Windows device that was launched in a suspended state.
wdRemote /action:terminate	Terminates a game running on a remote Windows device.

Pairing remote Windows devices and security key management

wdRemote /action:pair

This command establishes a trusted, secure connection between a development PC and the remote device via PIN pairing. wdEndpoint running on the remote device generates the PIN. wdRemote /action:pair /device:HostName | IP Address /pin:pin number [/sshKey:filename]

Option	Description
/action:pair	Indicates that wdRemote should perform a PIN pairing operation.
/device:	The IP address or host name of the remote device.
/pin:	The PIN generated by an instance of wdEndpoint running on the remote device.
/sshKey:	An optional ssh key to install on the remote device. This key can be used to establish an ssh connection between the development PC and the remote device.

Example:

// Start the pairing process by obtaining a pin using `wdEndpoint /pair` on the remote device.  `wdEndpoint /pair` must be executed from a command prompt with Administrator privileges
c:>wdEndpoint /pair

wdEndpoint version: 1.0.0.0
No configuration found at 'C:\ProgramData\Microsoft GDK\wdEndpoint\wdEndpoint.json', using defaults.
Overriding security mode for pairing.

Device ID: 29aab0e953b95099388b169861940a7501c7c7be
Security Mode: Private
Common Roots:
  (Default) C:\ProgramData\Microsoft GDK\gameroot

Server startup.
Listening for requests on: https://+:4275/gamingTransport/.
Entered exclusive pairing mode for 120 seconds.
PIN: q87p7w  

// Specify the result PIN to the pairing /action to wdRemote on the desktop PC
c:>wdRemote /action:pair /device:myROGAllyX /pin:q87p7w

Successfully paired.
Client: a701ed911d794154737a1ed2cfe29e292d532561
Device: 231d6063b48cfc136f8ebdcad0a472edc7a27527

Return to the top of this topic.

wdRemote /action:purgekeys

All traffic between wdRemote and wdEndpoint is encrypted. wdRemote automatically creates the required encryption keys and certificates the first time it’s asked to connect to a remote device. These keys are also used in the pairing process. wdRemote /action:purgekeys removes all keys and device pairings from a development PC. wdRemote /action:purgekeys Return to the top of this topic.

Status and versioning information

wdRemote /action:version

Displays the version of wdRemote.exe. wdRemote /action:version Return to the top of this topic.

wdRemote /action:status

Displays the status of the connection between the development PC and the target device. wdRemote /action:pair verifies all device pairings and checks to ensure encryption is in effect. wdRemote /action:status /device:HostName | IP Address

Option	Description
/action:status	Indicates that `wdRemote` should display the status of the connection between the development PC and the device identified by the `/device:` argument
/device:	The IP address or host name of the remote device.

Return to the top of this topic.

Deploy, launch, and terminate applications

wdRemote /action:deploy

Deploys a game from a development PC to the target device specified by the /device: argument. All deployments are incremental, meaning only the files that have changed since the last deployment are transferred to the target device. Games are stored on the target device in a directory called a Common Root. By default, the Common Root is %ProgramData%\Microsoft GDK\gameroot. Destination paths passed to wdRemote are relative to the Common Root unless you specify an absolute path, in which case the Common Root is ignored. The location of the default Common Root can be changed, and more Common Roots added, by creating a file named wdEndpoint.json and placing it in %ProgramData%\Microsoft GDK\wdEndpoint\ on the target device. wdEndpoint.json contains a list of Common Roots in the following format.

{
  root:<absolute file path>,
  alias:<name>,
  default:true|false
}

Specifying default is optional. If multiple defaults are specified, the first one listed becomes the default. If no root is marked as default, the first one listed will become the default. The following example wdEndpoint.json defines two Common Roots, a default root at c:\developmentbuilds and another root at d:\releasedbuilds.

{
    "gameRoots": [
        {
            "root": "c:\\developmentbuilds",
            "alias": "primary",
            "default": true
        },
        {
            "root": "d:\\releasedbuilds",
            "alias": "released"
        }
    ]
}

wdRemote /action:deploy /device:HostName | IP Address /source:directory /destination:folder under gameRoot [/root:gameRoot alias]

Option	Description
/action:deploy	Indicates that `wdRemote` should perform a deploy action.
/device:	The IP address or host name of the remote device.
/source:	The directory on the development PC containing the game to be deployed.
/destination:	The directory on the target device where the game is to be deployed. This direction is relative to the Common Root.
/root:	An optional Common Root alias. If not specified, the default Common Root is used.

Examples

// Deploys the contents of c:\gamesource\x64\Debug to a directory named Daily under the default Common Root.  Using the example config file above, the game
// will be deployed to c:\developmentbuilds\Daily on the target device.
c:\>wdRemote /action:deploy /device:myROGAllyX /source:c:\gamesource\x64\Debug /destination:Daily

// Deploys the contents of \\releases\october2025\buildoutput to a directory named october2025 under the Common Root at d:\releasedbuilds.  Using the example config file above,
// the game will be deployed to d:\releasedbuilds\october2025 on the target device.
c:\>wdRemote /action:deploy /device:myROGAllyX /source:\\releases\october2025\buildoutput /destination:october2025

Return to the top of this topic.

wdRemote /action:launch

Launches a game on the remote device specified by the /device: argument. The process ID of the game that was launched is displayed as output. wdRemote guarantees that only one game is running at a time on the remote device. If a game is already running on the remote device when wdRemote /action:launch is executed, the running game is terminated before the new game starts.

wdRemote /action:launch /device:HostName | IP Address /path:path to exe in Common Root [/args:list of arguments] [/root:gameRoot alias] [/suspend]

Option	Description
/action:launch	Indicates that wdRemote should perform a launch action.
/device:	The IP address or host name of the remote device.
/path:	The path to the executable to launch. Relative paths are resolved under the Common Root. If an absolute path is specified, the Common Root is ignored.
/args:	A list of arguments to pass to the executable.
/root:	An optional Common Root alias. If it isn’t specified, the default Common Root is used.
/suspend:	An optional flag that launches the game in a suspended state. Use `wdRemote /action:resume` to resume a game that was launched with `/suspend`.

Examples

// Launches a game in the default Common Root, passing a command line argument to the game
c:\>wdRemote /action:launch /device:myROGAllyX /path:Daily\Game.exe /args:"-level 2"

// Launches a game in a suspended state
c:\>wdRemote /action:launch /device:myROGAllyX /path:Daily\Game.exe /suspend

Return to the top of this topic.

wdRemote /action:resume

Resumes a game on the remote device that was launched in a suspended state using wdRemote /action:launch with the /suspend flag. wdRemote /action:resume /device:HostName | IP Address

Option	Description
/action:resume	Indicates that `wdRemote` should perform a resume action.
/device:	The IP address or host name of the remote device.

Examples

c:\>wdRemote /action:resume /device:myROGAllyX

Return to the top of this topic.

wdRemote /action:terminate

Terminates the game running on a remote device. wdRemote /action:terminate /device:HostName | IP Address [/processid:id]

Option	Description
/action:terminate	Indicates that `wdRemote` should perform a terminate action.
/device:	The IP address or host name of the remote device.
/processid:	The ID of the process to terminate.

Return to the top of this topic.

Tools

Pairing remote Windows devices and security key management

wdRemote /action:pair

wdRemote /action:purgekeys

Status and versioning information

wdRemote /action:version

wdRemote /action:status

Deploy, launch, and terminate applications

wdRemote /action:deploy

wdRemote /action:launch

wdRemote /action:resume

wdRemote /action:terminate

See also

​Pairing remote Windows devices and security key management

​wdRemote /action:pair

​wdRemote /action:purgekeys

​Status and versioning information

​wdRemote /action:version

​wdRemote /action:status

​Deploy, launch, and terminate applications

​wdRemote /action:deploy

​wdRemote /action:launch

​wdRemote /action:resume

​wdRemote /action:terminate

​See also

Pairing remote Windows devices and security key management

wdRemote /action:pair

wdRemote /action:purgekeys

Status and versioning information

wdRemote /action:version

wdRemote /action:status

Deploy, launch, and terminate applications

wdRemote /action:deploy

wdRemote /action:launch

wdRemote /action:resume

wdRemote /action:terminate

See also