To run PowerShell tasks in the Windows environment using the Bridge agent, remoting must be enabled. There are two ways to enable this:
Remote Session (Default):
PowerShell remoting must be enabled by default for tasks to run successfully. The PowerShell engine task runs only on the local (Bridge-installed) machine, while other PowerShell task states work on both local and remote machines.
To enable remoting on the local host, use the command: Enable-PSRemoting. For more details, click here.
You can verify or manually enable remoting using the command: winrm quickconfig. For more information, click here.
Without Remote Session:
When executing PowerShell scripts directly without a remote session, this functionality is not available by default. You need to configure it manually.
Steps:
Go to the Bridge installation folder: Bridge >> config >> powershell.properties.
Add the following property: bridge.pwsh.script.execute.session=false.
In Windows, open Services, locate Qntrl Bridge, and Restart.
After this configuration, PowerShell tasks will execute in a non-remote session.
Keys | Description |
task_details | A JSON object that contains the details of the task. |
activity_name | Name of the activity performed in the PowerShell Engine module. |
execution_path (optional) | Executable path of the installed PowerShell in the remote Windows machine. |
host | Address of the Windows machine where the activity has to be performed. |
credential | A JSON object that contains credentials of the machine in which the PowerShell script has to be executed. |
name | Name of the machine credential. |
task_name | A system-defined name for the respective modules. 'pwsh_task' is the task name for PowerShell Engine. |
Request data
{ "task_details": { "activity_name": “file”, "execution_path": "<PATH OF EXECUTABLE FILE>", "host": "<HOST_NAME>", "script_name": "<name of the script file>" }, "credential": { "name": "<CREDENTIAL_NAME>" }, "task_name": "pwsh_task"}
Request data
{ "task_details": { "activity_name": "install_app", "execution_path": "<PATH OF EXECUTABLE FILE>", "host": "<HOST_NAME>", "file_path": "<PATH FOR THE APP TO BE INSTALLED>", "msi_file_name": "<NAME OF THE MSI FILE>" }, "credential": { "name": "<CREDENTIAL_NAME>" }, "task_name": "pwsh_task"}
Request data
{"task_details": {"activity_name": "uninstall_app","execution_path": "<PATH OF EXECUTABLE FILE>","host": "<HOST_NAME>","app_name": "<APPLICATION_NAME>"},"credential": {"name": "<CREDENTIAL_NAME>"},"task_name": "pwsh_task"}
Request data
{"task_details": {"activity_name": "start_service","execution_path": "<PATH OF EXECUTABLE FILE>","host": "<HOST_NAME>","service_name": "<NAME OF THE SERVICE>"},"credential": {"name": "<CREDENTIAL_NAME>"},"task_name": "pwsh_task"}
Request data
{"task_details": {"activity_name": "stop_service","execution_path": "<PATH OF EXECUTABLE FILE>","host": "<HOST_NAME>","service_name": "<NAME OF THE SERVICE>"},"credential": {"name": "<CREDENTIAL_NAME>"},"task_name": "pwsh_task"}
Request data
{ "task_details": { "activity_name": "restart_server", "execution_path": "<PATH OF EXECUTABLE FILE>", "host": "<HOST_NAME>" }, "credential": { "name": "<CREDENTIAL_NAME>" }, "task_name": "pwsh_task"}
Navigate to Bridge/config/powershell.properties
Add this line, bridge.pwsh.script.execute.session=false
Then restart the Qntrl Bridge service from Windows Services.
There are a few common reasons this might happen. Check the following:
Is the credential name correct?
Ensure the credential name matches the one provided in the request data.
Is the username formatted correctly?
The format depends on whether the machine is part of a domain:
If not using a domain: <hostname>\<username>
If part of a domain: <domainname>\<username>
Is the password valid?
Confirm that the password is correct.
Ensure the password is not expired or recently changed.
Test the Credentials in PowerShell
Run the below command to manually verify if the username and password work:
Enter-PSSession -ComputerName localhost -Credential $cred
A login prompt will appear.
If the credentials are valid, you’ll enter the session.
If they’re invalid, PowerShell will show an error.
Verify the execution_path is correctly pointing to the installed PowerShell executable.
Ensure the script_name is correct and uploaded to the task.
Check if the host (target machine) is reachable from the Bridge-installed machine.
Review Bridge logs under <Bridge-Path>/logs/
Confirm the file_path and msi_file_name are correct and accessible from the target machine.
For uninstall, ensure app_name exactly matches the installed application’s name.
Restart will fail if any user is currently logged in to the target machine.
Ensure the machine is idle before executing the restart_server activity.
Make sure the service_name matches the actual service name (case-sensitive).
Check that the user in the credential has permission to manage Windows services.
Confirm that the host IP/name is accessible from the Bridge server.
Verify network connectivity between Bridge and the target machine.
Restart the Qntrl Bridge service via Services (Windows) or command line.
Review logs under <Bridge-Path>/logs/ for any errors.
Check if PowerShell remoting or session settings are misconfigured.
You are currently viewing the help articles of Qntrl 3.0. If you are still using our older version and require guidance with it, Click here.