Skip to content

Configuring the PCoIP Software Client for Windows

The Software Client for Windows provides a number of configurable settings and behaviors, which allow the setting of user options, performance modes, and triggering actions like automated connections. These settings are not persistent and cannot be set via the user interface; they are set by launching the application using one of the methods described next.

To configure a client instance, you must launch it using one of these methods:

  • On the command line, with configuration values passed inline as flags, or
  • Via a URI, providing your configuration values in an encoded JWT string.

Setting Configuration Values on the Command Line

To set configuration values this way, launch the Software Client for Windows from a command prompt, and include the required options as flags. Multiple flags can be included in the same line. Use the following conventions when setting these parameters:

Type Format
Boolean No value is required; the flag implies "True"
Numeric Provide the parameter and then the numeric value, separated by a space.
String Provide the parameter and then the string value, separated by a space.
Values can be wrapped in double quotation marks if they contain spaces.

The following example launches the client in full-screen mode, sets log level 3, and points to a connection broker at broker.domain.com (if your application is installed somewhere else, use your own path instead):

"c:\Program Files (x86)\Teradici\PCoIP Client\bin\pcoip_client.exe"  --connection-broker  broker.domain.com  --log-level 3 --full-screen

The available settings are shown below.

Setting Configuration Values via a URI

Using this method, the Software Client for Windows is launched using a URI with configuration options (and, optionally, connection credentials) encoded in a JWT token string.

To use this method, create a URI with the following structure:

pcoip://[broker]/connect[?data={jwt}]

Where each segment shown above is:

Segment Description
pcoip:// Required. This scheme is registered with the operating system and will launch the Software Client for Windows.
broker Optional. FQDN of the connection broker to use. If the connection is not brokered, this can be omitted.
/connect Required. Requests a connection with the parameters defined in "?data"
?data={jwt} Optional. The string indicated by {jwt} here is a JWT payload, containing any required configuration settings and connection credentials. If all you want to do is launch the client with no options set, this can be omitted.

The JWT payload can contain both credential information and client configuration. To create the JWT payload:

  1. Create your configuration and credentials as a JSON object, using available configuration parameters and authentication credentials.
  2. Encode the object as a JWT token.
  3. Pass the token through the URI as the data parameter.

For example, the following JSON object would launch the client in full-screen mode, with log level 3:

{
    "fullscreen":true,
    "log-level":3
}

Encoded, and pointing to a connection broker at broker.domain.com, this would result in a URI similar to the following:

pcoip://broker.domain.com/connect?data=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxsc2NyZWVuIjp0cnVlLCJsb2ctbGV2ZWwiOjN9.3MRUQ4VeKHbCnkG4OIXsUYp2N1IGf6AzTIo8tnFoXoA

The available settings are shown below.

Configurable Settings

The following settings can be configured on the Software Client for Windows.

General Settings

These settings affect the client's behavior both in and out of PCoIP sessions.

Language

Sets the user interface language.

Caution: Localization is not available in this release

Localization has not been implemented in this version of the user interface, and will always display English text. This parameter is ignored.

Localization support will be implemented in a future release.

Options Default Type
English only in this release Not set string

Usage

Method Valid Full Alias Example
Command Line --locale --locale zh_CN
URI locale loc {loc: "zh_CN"}

Connection Settings

These settings control how the Software Client for Windows connects to PCoIP sessions.

Connection Broker

The connection broker's URL.

Note that this parameter is used by the command line only; when using the URI method, the connection broker URL is part of the URI (not part of the configuration JWT payload).

Values Default Type
The URL for the connection broker, if present string

Usage

Method Valid Full Alias Example
Command Line --connection-broker -b -b broker.domain.com
URI

Desktop

The name of the desktop to connect to.

Values Default Type
The name of a desktop to conect to string

Usage

Method Valid Full Alias Example
Command Line --desktop --desktop myDesktop
URI desktop vm {vm: "myDesktop"}

Domain

The domain to send to the connection broker.

Options Default Type
The name of the domain to provide to the connection broker. string

Usage

Method Valid Full Alias Example
Command Line --domain -d --domain domain.example.com
URI domain dom {dom: "domain.example.com"}

Hard Host

If connecting to a PCoIP Remote Workstation Card (also known as a hard host), provide its URL using this parameter.

This option is ignored if the connection-broker url is provided.

Options Default Type
The URL for the Remote Workstation Card. string

Usage

Method Valid Full Alias Example
Command Line --hard-host -h -h rwc.example.com
URI

Password

The password sent to the Connection Broker, for logging into a desktop. Transmitting passwords this way is not recommended.

Note: Command-line only

Passwords can only be sent via the command line. You cannot send a password in a JWT payload.

Options Default Type
A string password. Not set string

Usage

Method Valid Full Alias Example
Command Line --password -p -p mypassword
URI

Security Mode

The security mode used for validating connections.

Note: This setting can be provided in the user interface

This setting is available from the user interface, in addition to the methods described here. For details, see PCoIP Software Client Security Modes.

Options Default Type
0: Verification not required
1: Warn, but allow
2: Full verification required
1: Warn, but allow integer

Usage

Method Valid Full Alias Example
Command Line --security-mode -s -s 2
URI security-mode sec {sec:2}

Session ID

This setting launches the JSESSIONID. This parameter is only available via JWT; it cannot be used on the command line.

Options Default Type
The session ID to launch. Not set boolean

Usage

Method Valid Full Alias Example
Command Line
URI sessionid sid {sid: exampleSessionID}

Username

The username sent to the Connection Broker.

Options Default Type
The username to pass to the connection broker Not set string

Usage

Method Valid Full Alias Example
Command Line --username -u -u myUsername
URI username usr {usr: "myUsername"}

USB Settings

These settings control how USB devices connect to PCoIP sessions, including rules for which devices are allowed to be forwarded.

Disable USB

USB devices are available by default. Use this flag to disable USB connections. This will not prevent simple human input devices like mice or keyboards from connecting.

Options Default Type
true: disabled
false: enabled
false (USB enabled) boolean

Usage

Method Valid Full Alias Example
Command Line --disable-usb --disable-usb
URI disable-usb nousb {nousb: true}

USB Auto-Forward

This setting auto-forwards all non-HID devices to the host.

Options Default Type
True: Auto-forward USB devices
False: Do not auto-forward USB devices
False (do not auto-forward) boolean

Usage

Method Valid Full Alias Example
Command Line --usb-auto-forward --usb-auto-forward
URI usb-auto-forward uaf {uaf: true}

Note: This setting is available in the user interface

This setting is also available in the client's pre-session user interface, by clicking the gear icon and selecting USB Devices.

Vidpid Auto-Forward

To auto-forward specific devices, provide their VID and PID values separated by a comma (,). Multiple values can be provided, separated by spaces. Enclose the list in quotation marks.

Options Default Type
The list of VID,PID values to auto-forward Not set string

Usage

Method Valid Full Alias Example
Command Line --vidpid-auto-forward --vidpid-auto-forward "aa11,bb22 cc33,dd44"
URI vidpid-auto-forward vaf {vaf: "aa11,bb22 cc33,dd44"}

If you are not sure of the device's ID values, see Identifying Vendor and Product IDs for instructions.

Vidpid Black List

To block specific devices from auto-forwarding at all, provide their VID,PID values as a space-separated list using this parameter.

This setting overrides usb-auto-forward and the USB dialog in the client interface.

Options Default Type
The list of VID,PID values to block Not set string

Usage

Method Valid Full Alias Example
Command Line --vidpid-black-list --vidpid-black-list "aa11,bb22 cc33,dd44"
URI vidpid-black-list vbl {vbl: "aa11,bb22 cc33,dd44"}

If you are not sure of the device's ID values, see Identifying Vendor and Product IDs for instructions.

Session Behavior Settings

These settings control the client's behavior once a session is connected.

Fullscreen Mode

Fullscreen mode enables the display topology to support multiple monitors as an extended desktop.

If both fullscreen and windowed parameters are sent, the client will launch in Windowed mode.

Options Default Type
true: full screen
false: windowed
Not set (uses client's last-set mode) boolean

Usage

Method Valid Full Alias Example
Command Line --fullscreen -f -f
URI fullscreen full {full: true}

Windowed Mode

Launches the client in windowed mode.

If both fullscreen and windowed parameters are sent, the client will launch in Windowed mode.

Options Default Type
True: Launch in windowed mode
False: Do not request windowed mode
False (does not request windowed mode) boolean

Usage

Method Valid Full Alias Example
Command Line --windowed -w -w
URI windowed win {win: true}

Log Settings

These settings control logging functionality, including verbosity and file location.

Log Folder

A custom location for client log files.

Options Default Type
A valid system path to a folder Not set string

Usage

Method Valid Full Alias Example
Command Line --log-folder --log-folder path/to/folder
URI

Log ID

A unique ID that will identify sessions in all PCoIP log files (including those created by other components like agents and a connection manager).

Options Default Type
A unique session identifier Not set string

Usage

Method Valid Full Alias Example
Command Line --log-id --log-id abcde1234
URI

Log Level

Sets the log level. This parameter will override any existing configuration values.

Options Default Type
0: Critical
1: Error
2: Info
3: Debug
4: Verbose
Not set integer

Usage

Method Valid Full Alias Example
Command Line --log-level -l -l 2
URI log-level logl {logl:2}

Note: This setting is available in the user interface

This setting is also available in the client's pre-session user interface, by clicking the gear icon and selecting Logs.

Log Prefix

A user-defined prefix for log files. This value will be prepended to the timestamp in the log file name, like this:

<log-prefix value><timestamp>

Log files are saved in the location provided by log-folder.

Options Default Type
A prefix to use in generated log file names Not set string

Usage

Method Valid Full Alias Example
Command Line --log-prefix --log-prefix example-prefix
URI

Advanced Settings

Caution: General use of these settings is not recommended

These settings are intended for specific use cases, and can drastically alter the behavior of the Software Client for Windows. Unless you understand what these settings do, and have a clear need to use them, they should be avoided.

Disable Hotkeys

Session convenience hot keys, such as Ctrl+Delete+F12 (which disconnects a PCoIP session) are available to users by default. Use this flag to disable all hotkeys.

Options Default Type
true: disabled
false: enabled
false (hotkeys enabled) boolean

Usage

Method Valid Full Alias Example
Command Line --disable-hotkeys --disable-hotkeys
URI disable-hotkeys nohot {nohot: true}

Disable Menu Bar

The PCoIP client menu bar is available to users by default. Use this flag to disable the menu bar, preventing users from accessing it or executing any of its functionality.

Options Default Type
true: disabled
false: enabled
false (menu bar enabled) boolean

Usage

Method Valid Full Alias Example
Command Line --disable-menubar --disable-menubar
URI disable-menubar nomenu {nomenu: true}

Enable Scaling

This setting enables scaling on the PCoIP Client without having to specify the desktop resolution. This can only be configured on a single display. This is off by default.

Options Default Type
true: scaling enabled
false: scaling disabled
false (scaling disabled) boolean

Usage

Method Valid Full Alias Example
Command Line --enable-scaling --enable-scaling
URI enable-scaling scale {scale: true}

Force Native Resolution

This setting sets the resolution of the Client monitor to the native resolution when the session client is launched. This can only be configured on a single display.

Note: Windows client only

This parameter is only available on Windows clients. It will have no effect if provided to a Linux or macOS client.

Options Default Type
true: force enabled
false: force disabled
false (Resolution force disabled) boolean

Usage

Method Valid Full Alias Example
Command Line --force-native-resolution --force-native-resolution
URI force-native-resolution native {native: true}

Maintain Aspect Ratio

This setting maintains the display aspect ratio between the host and the Client. Maintaining the aspect ratio in this way can result in letterboxing if the two devices are naturally different.

This can only be configured on a single display.

Options Default Type
true: Maintain aspect ratio
false: Do not maintain aspect ratio
False (does not maintain aspect ratio) boolean

Usage

Method Valid Full Alias Example
Command Line --maintan-aspect-ratio --maintain-aspect-ratio
URI maintain-aspect-ratio aspect {aspect: true}

Quit After Disconnect

If this is enabled, disconnecting from the PCoIP session will immediately quit the {! ./_common/name.md! }.The pre-session interface will not be available after disconnecting.

Options Default Type
True: Quit on disconnect
False: Do not quit, show pre-session UI on disconnect
False (does not quit on disconnect) string

Usage

Method Valid Full Alias Example
Command Line --quit-after-disconnect --quit-after-disconnect
URI quit-after-disconnect qad {qad: true}

Set Host Resolution

This setting locks the resolution of your host application display.

Provide the value as a string, made up of the horizontal resolution, the letter "x", and the vertical resolution. For example, "1024x768".

This can only be configured on a single display.

Options Default Type
A fixed resolution the host must use. Not set string

Usage

Method Valid Full Alias Example
Command Line --set-host-resolution --set-host-resolution 1024x768
URI set-host-resolution res {res: "1024x768"}