How to run a job that requires interacting with the desktop or screen in a Windows agent

Article ID:360029047492
2 minute readKnowledge base


When we try to run jobs that require interacting with the desktop or with the screen in a Windows agent which is installed as a service, the job fails. But if we run the command that the job is trying to run, from a command prompt opened in the windows agent, the command is completed without further issues.

When this happens, one of the most common causes is that the agent process is running inside what it is known as Session 0 Isolation, which was introduced back in 2007 in Windows Vista to avoid shatter attacks and it is still in use as of 2019.

This security feature causes the Jenkins agent to be running inside a less privileged session than most of the testing frameworks require to be able to run different test cases such as changing the screen resolution, open a browser, etc.


In this particular case, one of the potential approaches to resolve the issue is bringing the agent process out of that secure session. In order to do that, we will need to launch the agent from an interactive session, once we do that, we will be running out of the limits of Session 0 thus, the job will be able to run without additional problems.

Using Java Web Start

In newer versions of Jenkins (since 2.176.1) this launch method is no longer known as “Launch agent via Java Web Start”. Instead, you will find it as “Launch agent by connecting it to the controller” (formerly 'master').

  • Select `"Java Web Start`" or “connecting it to the controller” as launch method (It will depend on the Jenkins version). image::common-kb::001_launchmethod.png[Launch_Method]

  • Grab the Launch command and download the agent.jar to the directory where you are going to run the command from. image::common-kb::001_command.png[Copy_Command]

  • Open a Command Prompt window, if possible running it as Admin.

  • Launch the agent using the command from the location where you downloaded the agent.jar file. image::common-kb::001_launch_the_agent.png[Launch_Agent]

The only caveat for this procedure is that the agent will not be restarted if it fails or it is terminated, there are different ways to approach the solution of this problem but this is out of the scope of this Kb-Article.

Tested product/plugin versions