Optional Tosca Distribution Agent configurations

As of Tricentis Tosca 2026.1 LTS, Distributed Execution is no longer enabled by default. While Distributed Execution is included in both Tosca Commander and Tosca Server installations, it requires manual activation:

  • Tosca Commander: The Distributed Execution Agent option in the installer is disabled by default. You must enable it before starting the Tricentis Tosca installation.

  • Tosca Server: All Distributed Execution related services remain disabled by default. You must enable the DEX Server after the Tosca Server installation.

For detailed information how to enable the Distributed Execution Agent and DEX Server, see this Tricentis Knowledge Base article.

You can change most Agent settings in the Tosca Distribution Monitor (check out "Monitor, recover, and configure Agents in the Tosca Distributed Execution Monitor").

Additionally, you can modify the following settings in the configuration files:

Set a custom RDP port

The Agent needs an inbound port for the RDP connection. The default port for Remote Desktop on Windows is 3389.

If you have specified a different port for Remote Desktop on Windows, you must also change this port in your Agent configuration. You have to do this on every Agent machine where you have set a different port for Remote Desktop on Windows.

To do so, follow the steps below:

  1. Stop the Agent.

  2. On the Agent machine, open the ToscaRdpServer.dll.config  file. By default, this file is located at C:\Program Files (x86)\TRICENTIS\Tosca Testsuite\DistributedExecution\Rdp.

  3. In the applicationSettings section, enter a new value for RdpListeningPort.

  4. If you also want to modify the RDP connection retry setting, you can do so now.

  5. Update the Ocelot configuration files with the new port number.

  6. If you are done with your configurations, perform the following actions:

Example: Set port 4444

<applicationSettings>
    <Tricentis.RdpServer.Properties.Settings>
        [...]
        <setting name="RdpListeningPort" serializeAs="String">
            <value>4444</value>
        </setting>
        [...]
    </Tricentis.RdpServer.Properties.Settings>
</applicationSettings>

Define the RDP connection timeout

At run-time, the Agent tries to establish an RDP connection for 30000 milliseconds (30 seconds). If it isn't successful within that time frame, the Agent aborts.

You can change that time frame. Note that you have to do this on every Agent machine that needs a different time frame.

To change the time frame, follow the steps below:

  1. Stop the Agent.

  2. On the Agent machine, open the AgentSettings.xml  file. By default, this file is located at C:\ProgramData\TRICENTIS\Tosca Testsuite\7.0.0\DistributedExecutionAgent\Default\settings.

  3. In the userSettings section, enter a new value for EstablishRdpConnectionTimeoutMilliseconds.

  4. If you also want to modify the workspace log level setting, you can do so now.

  5. If you are done with your configurations, perform the following actions:

Example: timeout interval of 40 seconds

<AgentSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    [...]
        <EstablishRdpConnectionTimeoutMilliseconds>40000</EstablishRdpConnectionTimeoutMilliseconds>
    [...]
</AgentSettings>

Define RDP connection retry attempts

By default, the Agent doesn't try to re-establish the connection if the RDP connection is lost.

If you log in to an Agent which is currently executing, the execution stops and can't resume. To minimize risk, you can specify that you want the Agent to try and re-establish a lost connection. Note that you have to do this on every Agent machine that should try to reconnect.

To do so, follow the steps below:

  1. Stop the Agent.

  2. On the Agent machine, open the ToscaRdpServer.dll.config  file. By default, this file is located at C:\Program Files (x86)\TRICENTIS\Tosca Testsuite\DistributedExecution\Rdp.

  3. In the applicationSettings section, enter a new value for the following settings:

    • MaxConnectionRetries: enter the maximum number of retry attempts.

    • WaitBetweenRetriesMilliseconds: specify how many milliseconds the Agent should wait between tries.

  4. If you also want to modify the RDP port setting, you can do so now.

  5. If you are done with your configurations, perform the following actions:

During the retry attempt, the system logs out any active users.

So if you log in to an Agent which is trying to re-establish an RDP connection, the system will log you out shortly afterwards.

Example: 3 retries with a maximum wait of 20 seconds in between

<applicationSettings>
    <Tricentis.RdpServer.Properties.Settings>
        [...]
        <setting name="MaxConnectionRetries" serializeAs="String">
            <value>3</value>
        </setting>
        <setting name="WaitBetweenRetriesMilliseconds" serializeAs="String">
            <value>20000</value>
        </setting>
        [...]
    </Tricentis.RdpServer.Properties.Settings>
</applicationSettings>

Ocelot configuration

You must update the Ocelot configuration files if you perform any changes to the default port or endpoint address of the RDP Server. The sections below explain in detail where to find these files and how to update the relevant properties.

Update the Ocelot configuration file

To update the Ocelot configuration file of the RDP Server, follow the steps below:

  1. Open the ocelot.json file which is located at C:\Program Files (x86)\TRICENTIS\Tosca Server\Gateway.

  2. Search for two elements with the ServiceId value RdpService.

  3. Update the values of the following properties in these elements:

Property

Description

DownstreamScheme

Enter either http or https depending on the binding you chose.

Port

Enter the RDP Server port.

Apply the changes

Restart the following services to apply the changes: 

  • Tricentis.RdpService

  • Tricentis.GatewayService

Enable automatic confirmation of RDP login messages

If the Agent tries to set up an RDP connection, the machine may display a welcome message or a policy acknowledgment after login. This step requires manual interaction and can block your RDP session. You must select OK in the confirmation dialog before the desktop becomes available.

To avoid this issue, you can configure the Agent to simulate pressing the Space key after it establishes the RDP connection. This confirms the message and allows the agent to continue the session without interruption.

To do so, follow the steps below:

  1. Stop the Agent.

  2. On the Agent machine, open the ToscaRdpServer.dll.config file. By default, this file is located at C:\Program Files (x86)\TRICENTIS\Tosca Testsuite\DistributedExecution\Rdp.

  3. In the userSettings section, set the values for the following properties: 

    Property

    Description

    SendSpaceKey

    Set this to True to simulate pressing the Space key after the RDP sessions starts.

    SpaceKeyDelayMilliseconds

    Specify the delay between login and the simulated key press in milliseconds. The default value is 5000 .

  4. If you are done with your configurations, perform the following actions:

Example: Confirm login message after 5 seconds

<userSettings>
    [...]
      <setting name="SendSpaceKey" serializeAs="String">
        <value>True</value>
     </setting>
     <setting name="SpaceKeyDelayMilliseconds" serializeAs="String">
        <value>5000</value>
    </setting>
    [...]
</userSettings>

Set a key vault timeout for RDP credentials

If you store your RDP credentials in a key vault, the Agent fetches them before it opens an RDP connection. By default, the agent waits up to 30000 milliseconds (30 seconds) for a response.

If your key vault takes longer than 30 seconds to respond, for example, if it's hosted in a different region, sits behind a slow VPN, or handles many credential requests at the same time, executions fail before the credentials even arrive. To prevent this issue, use the KeyVaultTimeoutMilliseconds property in the DEX Agent settings file to increase the timeout. This gives your key vault enough time to respond.

To increase the timeout, follow the steps below: 

  1. Stop the Agent.

  2. On the Agent machine, open the AgentSettings.xml file. By default, this file is located at C:\ProgramData\TRICENTIS\Tosca Testsuite\7.0.0\DistributedExecutionAgent\Default\settings.

  3. Enter a new value for KeyVaultMilliseconds.

  4. If you are done with your configuration, perform the following actions: 

Example: Set key vault timeout after 60 seconds

<AgentSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    [...]
           <KeyVaultTimeoutMilliseconds>60000</KeyVaultTimeoutMilliseconds>
    [...]
</AgentSettings>