A Modular Remote Execution and Debugging Framework

Follow me on GitHub

Latest release Codacy Badge Build Status codecov GitHub license


A Modular Distributed Execution and Debugging Framework.

Molr provides a unified way to interact (locally or remotely) with executable code in order to run it and/or debug it. It is possible to provide input to it and retrieve output, return values and exceptions from this. The reference implementation (in the molr repository) is implemented in java. However, remote interaction is performed through a well defined REST API. This makes it very easy to implement ‘plugins’ (Moles) in any programming language.

Molr is designed to be completely asynchronous. For this purpose, reactive streams are used. The chosen implementation for this in java is Project Reactor.

The Name

As every connoisseur of spy movies knows, a mole is an agent who works for the other side. During the development of molr, we decided that we need fresh words … so our agents are called moles (Although we hope they are still good guys ;-).

Furthermore the framework is very modular. This results in the name molr:

mol[e] + mo[dula]r = molr


A mission is something that can be run and (in most cases) produces side effects.

This is important to note: The main purpose of molr is to produce side effects (e.g. change settings of a device, reconfigure something, …). Despite the missions can produce outputs, this is not the main focus of molr. In case you are looking for a framework for data processing, molr is definitely not what you need.

This is pretty much the whole definition of a mission. There is no language to which a mission is bound nor any interface it has to implement or so. If a mission can finally be used in molr, depends on the fact if there exists a mole that can execute (run/debug) a given mission.


A mole ist the central component in molr. It has the responsibility to execute certain type of missions. In principle, a mole is also not bound to be implemented in a certain programming language, as the remote moles can be plugged into molr as long as they implement a well defined REST API.

However, if a mole is implemented in Java, than it can (in addition to the remote usage) also be used embedded in the same jvm as the client application. The responsibilities of a mole include:

  • providing information of available missions
  • providing information about running missions (result/output/state)
  • running/stepping through missions

Fur further details, please refer to the Mole interface.

Off-the-shelf Moles

The following moles are already implemented in the molr-mole-core package and can be used right out of the box:

  • SingleNodeMole: Supports Missions that basically consist of single nodes (e.g. Runnables, Functions) which can only run, but never stepped through.
  • RunnableLeafsMole: This is up to now probably the most complicated java mole; It provides a simple DSL to generate missions that are organized in a tree form, can have sequential or parallel branches and have simple nodes, that execute simple java code, as leafs.
  • LocalSuperMole: Orchestrates a set of other moles, summarizes the available missions and delegates to the underlying moles accordingly. This allows a chaining/composition of moles. If remote moles are used here, then a microservice architecture can be created, which can lead out of ‘dependency hell’.

Complementary Moles

Moles, which depend on additional libraries and/or are implemented in different languages are not contained in the core packages, but are organized in different repositories. Currently, the following ones are available:

  • JUnit5Mole: A mole implemented in java that can run junit 5 tests. It resides in
  • Python Mole: This mole discovers functions in certain python packages as missions and can run them and even partially step through them. It resides in Since it is implemented in python itself, it only can be used as remote mole and not embedded in java.


The following is the molr structure of packages/jars. The main aspect which is taken into account while splitting packages is that of dependencies.

Click on the download badge to get to bintray, where you can find the code snippets to put into your gradle/maven files.

         package          description to be used when
Common elements for the molr project (e.g. domain objects and DTOs). No Spring dependency! always
Contains the interfaces and default implementations for moles, as well as utility methods. Depends on spring context only always (e.g. implementing a mole, using a mole - embedded or as client)
Contains the implementation of a remote mole, which can delegate to any mole reachable through a Web API. Depends on Spring webflux. using a mole as remote client
Exposes any mole as a REST service. This package has Java server dependency (e.g. Tomcat). exposing a mole as a rest service