Opereto agent is a single jar file that retrieves process requests from the center and executes them on a given host (requires JAVA 1.7.x or higher version).

Opereto considers a given agent as operational if the agent is online (connected).

The Agent utilises an optimised back-polling mechanism listening to Opereto center directives via HTTPS (authenticated with a username and a password). Based on this approach, there is no need to change firewall policies or network configurations. Agents can quickly and securely connect to Oepreto cluster from anywhere.

The agent runs with the privileges of the operating system user initiated it. If you run it as a root, for instance, Opereto processes will be able to perform any action or run any command that root may, including changes and deletion of critical operating system files and libraries. For that reason, in non testing environments, we recommend to create a unique user for opereto, assign it the required privileges and use this user to run the agent

Install & Run

To manually install the agent on a given host:

Run the agent .jar file from shell

Download the agent jar file and run:

java -XX:MaxPermSize=128m -XX:MinHeapFreeRatio=15 -XX:MaxHeapFreeRatio=30 -Xms128m -Xmx256m -jar opereto-agent-latest.jar -host https://OPERETO_SERVER -name AGENT_NAME -u USERNAME -p PASSWORD -loglevel info -log console

Install the agent service on Windows 

Download the agent zip package file:


net start opereto-agent | net stop opereto-agent

Install the agent service on Linux 

Download the agent tar file:


service opereto-agent [start|stop|restart|start]

*    If no agent name provided, the hostname will be used             

**  Valid agent names:

  • 3-128 characters
  • Stats with small letter
  • Allowed characters are: a-zA-z0-9_-


However, in most cases, we would like to install the agent automatically as part of a new environment setup. There are many ways to do that, depending on the virtual platform we use. Following are few common examples:


The installation package also contains an uninstall script. If required, please run this script to uninstall the agent. 

Agent local directory and logs

The agent directory is a hidden directory (.opereto) located in the home directory of the host user that originally initiated the Agent.  For instance, in case that user 'john' has started the agent on a Linux host, the agent local directory would be: /home/john/.opereto

.opereto directory contains the following subdirectories:

  • .work – for internal agent usage
  • work – workspace for running processes. For each running process, the agent creates a temporary directory named as the process ID. In this directory (.opereto/work/${pid}) the agent stores all the data required for the running process: service files, input property files and more. Opereto deletes the process subdirectory when process execution ends.
  • repository – a repository of cached services.
  • log – agent log files.

Agents troubleshooting

In case of agent execution or connectivity failures, you can use the following guidelines for debugging:

  1. Firstly, check the log. Most agents issues will show as exceptions on the log. You will find all agent logs in the home directory of the user initiated the agents under .opereto directory (e.g. ~/.opereto/log/) unless specified differently in the agent command line. If you find nothing in the log, try to restart the agent in debug mode using the -loglevel debug flag.
  2. Check if the agent process or service is up and running. In Linux you can run ps -aux | grep opereto-agent or service opereto-agent status (if executed as a service). In Windows, check in the task manager for Java processes, etc.
  3. Check that java version is valid – should be 1.7.x or higher.
  4. Make sure that the agent host can connect to the OperetoBox via https. You can run, for instance, telnet OPERETO_CLUSTER_URL 443.
  5. Check the permissions of the agent jar file. Make sure that your current user has permission to execute it.
  6. Verify that the agent jar is not corrupted by running the agent in a console mode from the agent directory: