Agent Host cannot start when IP address changes

Affected Version

  • Automation Agent Host 1.3.7,, 1.3.8, 2.0.0
  • Platform: Windows, Linux, Mac


When you register the agent host with an IP address that changes overtime, e.g. after the agent host machine restarted and was allocated a new IP address, the agent host cannot starts.


When the agent host is starting, it tries to bind to the host's IP address, which is stored in agent.config file since the time you successfully registered the agent host, so that you can access to the agent host UI with the URL: http://<IP address>:<port>. The binding failed if the IP address in the agent.config file is different from the actual IP address of the host machine.


There is a couple of solutions to overcome this issue:

  1. Preferred approach: allocate a static IP address to the agent host so it does not change overtime, and use this IP address when registering the agent host
  2. Or update the IP address of the agent host to the new one with below command:
    • On Windows: \path\to\agentctl-[version]> agentctl.bat config -Phost=<New IP Address>
    • On Linux or Mac: /path/to/agentctl-[<version]$ ./agentctl config -Phost=<New IP Address>

After that, you can start the agent host with below command:

  • On Windows: \path\to\agentctl-[version]> agentctl.bat start
  • On Linux or Mac: /path/to/agentctl-[version]$ ./agentctl start


This issue can be avoided if you register the agent host with the -Phost parameter set to localhost, like below:

On Windows:

\path\to\agentctl-[version]> agentctl.bat config -Phost="localhost"

On Linux or Mac:

/path/to/agentctl-[version]$ ./agentctl config -Phost="localhost"

then you can access to the host from your browser using this URL: http://localhost:<port> (if you did not specify a port when registering the agent host, the default port number is 6789) at any time without worrying about the IP address.

However, a drawback for this approach is that since the agent host does not bind to the actual IP address, it cannot be accessed from another machine/computer in your network using an URL like this http://<IP address>:<port>


Subscribe To Our Blog
Powered by Zendesk