KBEA-00016 - Setting up users for a Windows Agent install

Article ID:360032828672
2 minute readKnowledge base


During a Windows Agent install, you have trouble with users being created, or you want to modify the number of agent users after an installation.


To allow the Agent to associate requests coming from system services, such as csrss (the Windows runtime subsystem), with a particular Agent, the security context associated with that request must be used, which is derived from the owner of the original process. This is why each Agent on one host must be run as a different user.

If you run multiple Agents with the same user, any job that uses system services (like .NET/c# compiles) will completely disrupt the build in unpredictable ways.

The simple case

As a convenience, multiple users (ECloudInternalUser1, etc.) are set up with proper permissions during installation. In general, this is the recommended way of running agents. In this case, you do not enter any user information during the installation.

The custom user with one Agent case

However, you may require agents to run as a particular user, so they can access network wide resources. If this is the case, and you use only one agent, you can use the installer dialog to configure that user. However, if there are more Agents, you must follow a more manual process. This is a known limitation of the current installer, and we hope to resolve this in a future release.

The custom user with multiple Agents case

  1. Ensure the users already exist.

  2. Configure the installer to set up one agent.

  3. Configure one of the users as the user to use for the one agent. This prevents the installer from creating the ECloudInternalUser users.

  4. Use ecconfig -numagents 6 to set the number of agents to start to 6 (or whatever number you desire).

  5. Use ecconfig -agentusers "username1/password1 username2/password2 …​ usernameN/passwordN" to assign different users to the agents.

  6. Stop and restart the agent service.

So did it work?

To see whether your setup succeeded, open the Windows task manager and look for processes called agent.exe (you may have to enable the listing of all processes). Each Agent process (there should be as many processes as you specified with the -numagents option) should run as one of the different users you specified with the -agentusers option.

Applies to

  • Product versions: All

  • OS versions: Windows