Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Important
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 for securely connecting a development PC to a remote Windows device. It supports PIN pairing, bidirectional file transfer, remote file deletion, game deployment and lifecycle management, and remote tool execution.
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 the game, tool job, or specified process on a remote Windows device. |
| wdRemote /action:copy | Copies files from the development PC to a remote Windows device. |
| wdRemote /action:copyfrom | Copies files from a remote Windows device to the development PC. |
| wdRemote /action:delete | Deletes a file or directory contents on a remote Windows device. |
| wdRemote /action:run | Runs an executable 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: <example-device-id>
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: <example-pin>
// Specify the result PIN to the pairing /action to wdRemote on the development PC
c:>wdRemote /action:pair /device:example-device /pin:<example-pin>
Successfully paired.
Client: <example-client-id>
Device: <example-device-id>
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.
This action 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:<remote device> /source:<source directory> /destination:<absolute or common root relative destination directory> [/root:<common root alias>] [/attributes:<-AHSR>]
| 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: | Relative destination paths are resolved under the selected Common Root. If an absolute path is specified, the Common Root is ignored. |
| /root: | An optional Common Root alias. If not specified, the default Common Root is used. |
| /attributes: | Optionally includes or excludes files and directories according to their file attributes. |
The /attributes: option supports the following letters.
| Letter | File attribute |
|---|---|
A |
Archive |
H |
Hidden |
R |
Read-only |
S |
System |
Letters before - are included. Letters after - are excluded.
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:example-device /source:c:\gamesource\x64\Debug /destination:Daily
// Deploys the contents of \\example-server\builds\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:example-device /source:\\example-server\builds\buildoutput /destination:october2025 /root:released
// Deploys everything except hidden files and directories.
c:\>wdRemote /action:deploy /device:example-device /source:C:\game /destination:game1 /attributes:-H
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:<remote device> /path:<absolute or Common Root-relative executable path> [/root:<Common Root alias>] [/args:"<arguments>"] [/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:example-device /path:Daily\Game.exe /args:"-level 2"
// Launches a game in a suspended state
c:\>wdRemote /action:launch /device:example-device /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:example-device
Return to the top of this topic.
wdRemote /action:terminate
Terminates the remote game, remote tool job, or specified remote process.
wdRemote /action:terminate /device:<remote device>
wdRemote /action:terminate /device:<remote device> /tool[:<pid>]
| Form | Behavior |
|---|---|
No /tool argument |
Terminates the remote game. |
/tool |
Terminates the remote tool job. |
/tool:pid |
Attempts to terminate the process with the specified process ID. |
Examples
// Terminates the remote game.
c:\>wdRemote /action:terminate /device:example-device
// Terminates the remote tool job.
c:\>wdRemote /action:terminate /device:example-device /tool
// Attempts to terminate the specified process.
c:\>wdRemote /action:terminate /device:example-device /tool:1234
Return to the top of this topic.
Copy and delete files
wdRemote /action:copy
Copies files from the development PC to a remote Windows device.
wdRemote /action:copy /device:HostName | IP Address /source:source directory /destination:remote directory [/root:gameRoot alias]
| Option | Description |
|---|---|
| /action:copy | Indicates that wdRemote should perform a copy operation. |
| /device: | The IP address or host name of the remote Windows device. |
| /source: | The source directory on the development PC. |
| /destination: | The destination directory on the remote Windows device. |
| /root: | An optional Common Root alias used to resolve a relative destination path. If omitted for a relative path, the default Common Root is used. Common Roots are ignored for absolute destination paths. |
Example
c:\>wdRemote /action:copy /device:example-device /source:C:\game /destination:game1
wdRemote /action:copyfrom
Copies files from a remote Windows device to the development PC. /source is the remote path, and /destination is the local path. /root resolves a relative remote source path and is ignored when /source is absolute.
wdRemote /action:copyfrom /device:HostName | IP Address /source:remote source directory /destination:local destination directory [/root:gameRoot alias]
| Option | Description |
|---|---|
| /action:copyfrom | Indicates that wdRemote should perform a copy-from-device operation. |
| /device: | The IP address or host name of the remote Windows device. |
| /source: | The source directory on the remote Windows device. |
| /destination: | The destination directory on the development PC. |
| /root: | An optional Common Root alias used to resolve a relative remote source path. |
Example
c:\>wdRemote /action:copyfrom /device:example-device /source:game1 /destination:C:\local_copy
wdRemote /action:delete
Attempts to delete a file or selected directory contents on a remote Windows device. Directory deletion is best-effort. The endpoint log records the number of items deleted and the number of failures, but not individual file paths.
wdRemote /action:delete /device:HostName | IP Address /path:remote directory or file [/root:gameRoot alias] [/include:pattern] [/exclude:pattern] [/excludedir:pattern] [/attributes:<-AHSR>] [/deleteroot]
| Option | Description |
|---|---|
| /action:delete | Indicates that wdRemote should perform a delete operation. |
| /device: | The IP address or host name of the remote Windows device. |
| /path: | The remote directory or file to delete. |
| /root: | An optional Common Root alias used to resolve a relative remote path. |
| /include: | Includes files matching the pattern. The * and ? wildcards are supported. |
| /exclude: | Excludes files matching the pattern. The * and ? wildcards are supported. Exclusion takes precedence over inclusion. |
| /excludedir: | Excludes directories whose names match the pattern. The * and ? wildcards are supported. |
| /attributes: | Includes or excludes files and directories by Archive, Hidden, Read-only, and System attributes. Excluding an attribute also excludes directories that have it, along with all of their contents. |
| /deleteroot | Attempts to remove the directory specified by /path after deleting its contents. The directory is removed only if it's empty. Regardless of this option, the operation attempts to remove empty subdirectories that pass the directory filters. |
Warning
Deletion can follow directory junctions and directory symbolic links beneath /path and delete matching files outside that directory. The command can still report success; no per-item results or undo operation are provided. Ensure /path is not itself a linked directory, and use /excludedir to exclude known linked subdirectories by name.
When /path identifies a single file, the search options and /deleteroot are ignored.
Examples
c:\>wdRemote /action:delete /device:example-device /path:game1
c:\>wdRemote /action:delete /device:example-device /path:game1 /exclude:"*.pdb" /excludedir:"logs"
c:\>wdRemote /action:delete /device:example-device /path:game1 /deleteroot
c:\>wdRemote /action:delete /device:example-device /path:game1\readme.txt
Run remote tools
wdRemote /action:run
Runs an executable on a remote Windows device.
wdRemote /action:run /device:HostName | IP Address /path:absolute executable path [/args:"arguments"] [/waitForExit] [/streamOutput] [/asAdmin]
| Option | Description |
|---|---|
| /action:run | Indicates that wdRemote should run an executable. |
| /device: | The IP address or host name of the remote Windows device. |
| /path: | The absolute path to the executable on the remote Windows device. |
| /args: | Arguments passed to the executable. |
| /waitForExit | Waits for the executable to exit. |
| /streamOutput | Streams standard output and standard error until the executable exits. |
| /asAdmin | Runs the executable as administrator. |
/waitForExit can't be combined with /streamOutput. /asAdmin can't be combined with /streamOutput.
Without /waitForExit or /streamOutput, the command reports the launched process ID and thread ID. With /waitForExit or /streamOutput, wdRemote.exe returns the remote process exit code.
Examples
c:\>wdRemote /action:run /device:example-device /path:C:\tools\mytool.exe
c:\>wdRemote /action:run /device:example-device /path:C:\tools\mytool.exe /args:"-arg1 -arg2" /waitForExit
c:\>wdRemote /action:run /device:example-device /path:C:\tools\mytool.exe /args:"-arg1 -arg2" /streamOutput
c:\>wdRemote /action:run /device:example-device /path:C:\tools\mytool.exe /asAdmin