Contact Us 1-800-596-4880

Runtime Manager Agent Architecture

The Anypoint Runtime Manager agent is a Mule plugin that exposes the Mule JAVA API as a service, allowing users to manipulate and monitor Mule instances from external systems.

This document shows an overview of the Runtime Manager agent architecture and its main components.

Runtime Manager Agent Main Components

Mule Service

Connects to Mule. This component is not aware of the transport layer (how the messages are going to be communicated by/to the user).


Handles the communication layer. Includes keep-alive status, security and protocol.

External Message handler

Exposes a Web Service API to users. Any incoming message (e.g. a deployment request) is handled by an external message handler. Depending on the request, a Mule service or multiple Mule services may be executed.

Internal Message Handler

Called by a Mule service every time it receives a Mule notification.


The agent has three ways to communicate with Mule, outlined below.

Synchronous communication

Example: Get deployed applications.


Asynchronous Communication

Example: Deploy and notify about the deployment stages.


Push Communication

Example: Push JMX information to an external system.


Architecture Diagram

The agent’s architecture is quite simple:

  • The transports handle communication.

  • The external message handlers dispatch messages.

  • The services connect to Mule.

  • The internal message handlers dispatch Mule notifications.

The interaction of each component is shown in the diagram below for each of the three types of messages (synchronous, asynchronous and push):


How Components Interact

Below is an outline of a typical sequence of component interaction:

  1. An external system sends a request to the agent.

  2. An external message handler is executed, and calls a Mule service using the interface.

  3. The Mule service calls Mule to perform the corresponding action.

  4. Mule responds with a notification.

  5. The service maps the notification to an agent notification, and looks for the internal message handlers that may handle the notification type.

  6. The corresponding internal message handlers are executed.

Runtime Manager Agent Configuration

At startup, the Runtime Manager agent reads its configuration from the file $MULE_HOME/conf/mule-agent.yml. You must manually add, then edit this file with your installation’s configuration parameters. The format is self-explanatory; a sample file is available for download.

During installation, you also have the option to configure the Runtime Manager agent using a quick-start script. For details, see Install or Update the Runtime Manager Agent.

Configurable Components

You can configure component attributes in the mule-agent.yml file. For this purpose, you can annotate the class attributes as @Configurable.

public class MyRequestHandler implements ExternalMessageHandler
    private MuleService muleService;

    public String host;

Runtime Manager Agent WebSocket Protocol

Communication over WebSockets to the agent implements the HTTP protocol. All messages sent to and from the agent are HTTP messages sent as binary messages or text (depending on the agent configuration) over WebSocket. These HTTP messages are the same as those used in the agent REST communication.

WebSocket Handshake

Handshaking is a process specific to the WebSocket transport. On startup, the agent sends a handshake request to the WebSocket address corresponding to the console (obtained from the agent configuration). After this, the agent ignores all incoming messages not recognizable as a handshake response. When it receives a message that it identifies as a handshake response, it checks that the response is valid. If it is, the agent begins responding to all incoming messages.

Handshake Request

Below is an example of a handshake request.

POST handshake HTTP/1.1
Content-Type: application/json
Message-Id: ${messageId}
accept: application/json
Content-length: 1234

"agentVersion": "1.0.0",
"muleVersion": "${muleVersion}",
"uniqueId": "${uniqueId}"

Handshake Response


Message-Id: ${messageId}


Message-Id: ${messageId}