Skip to content


Runners are runtime environments used to execute the bots. It can be associated with a virtual machine, a container, or a physical machine. Basically, the BotCity Runner is an executed process to get tasks, download bot binaries and put them in execution.

The Runners module views information about the runtime environments, including basic information such as status, execution log, and screen (for GUI-based automation).


Runners Types

BotCity has two types of Runners, the Desktop and the Background.

Runners Desktop

They are Runners used to automate tasks that need to access a user's graphical interface (GUI), such as a desktop application, an ERP, or even direct actions in the operating system.

Desktop Runners can only perform one task at a time, preventing parallelism in executing the task.

Runners Background

Background Runners are used to automate tasks that do not use a graphical interface, such as headless web automation, crawlers, and API integrations.

It is possible to use more than one Background Runner in the same execution environment, thus managing to run more than one automation at the same time when they are defined to run in the background; in this way, it is possible to maintain parallelism in the execution.

How to setup a Runner

Configuring a new Runner can be divided basically into two steps:

  • Creation of a Runner in BotCity Maestro
  • Runner configuration in the runtime environment

Creating a new Runner in Maestro

Create a new Runner by clicking the + New Runner button in the top left corner.

Fill in the form with the required information and click on Create.

Here is an example of how to create a Runner:

New Runner

Configuring a Runner in the runtime environment

After creating the Runner in Maestro, we can configure the reference for this created Runner in our runtime environment.

This way, the Runner active in the runtime environment will be associated with the Runner created in the platform.

The easiest way to configure a new Runner in the runtime environment is through the BotCity Wizard. You can see more details about Wizard and SDK installation through the BotCity Studio SDK section.

Wizard Setup Runner

In the folder where the SDK was installed, open the wizard-X.Y.Z where X.Y.Z are the Wizard's version.

From this screen, we can select the Setup Runner option.

Wizard Setup Runner Auth

In this step, we will inform our access credentials so that the authentication in Maestro can be performed.


If you are using an exclusive workspace, for example: you can use this custom URL when informing the Server.

For the community version, use

By clicking next, you can select an existing Runner in your Orchestrator workspace or create a new one from the Wizard.

Wizard Runner options

Just select the Runner identifier you want to link to the Runner of this runtime environment.

Wizard Select Runner

That way, when starting Runner in the runtime environment via the SDK's BotRunner or BotRunner-gui scripts, this Runner will be associated with the Runner that was created in BotCity Orchestrator.


You can also create new Runners from the Wizard; just select the Create a new Runner option, and enter an identifier for the Runner.

In this case, the creation on the platform and the association with the runtime Runner will be done automatically.


Runner's configuration is defined by information in the conf.bcf file, located in the conf folder where the SDK was installed.

You can see more details about the config file through this link.

Runner Card

Each Runner created will have a Runner card that represents it, as we can see below:


The circle in green or red indicates whether or not a BotRunner is in execution in that resource right now.

For GUI-based automation, it’s possible to see a screenshot that is taken every minute (when enabled). Just click on the screenshot thumbnail to see in a higher resolution.

You can access the Runner Card menu to view additional information, such as:

Runners info

  • Info: Basic information about this runtime environment.
  • Logs: Automation execution log trace.
  • Screenshot: Download the current screenshot.
  • Edit: Update some info about this runtime environment.
  • Delete: Remove this Runner instance on Maestro.

Runner Telemetry


By default, telemetry information is not collected by Runner. If you want this information sent to Maestro, include an additional configuration.

In the conf.bcf file located in the conf folder of the SDK, just set the logTelemetry=true setting.

You can view the available configuration parameters by accessing this link.

You can access Runner's telemetry through the Info option of the Runner card menu, shown above.

Runner Infos

General Runner Information

Cards General infos


  • Status: Indicates the current Runner status, whether he is online or offline.
  • Last Task: ID of the last task executed.
  • Tasks Allocated: Indicates the number of automations allocated in this Runner.
  • CPU: Indicates the use of the machine's CPU where the Runner was allocated.
  • Memory Total: Total machine memory in %.

Runner Information

Runners Information


  • Label: Runner identifier.
  • Name: Runner name.
  • Remote Access: Remote access information.
  • Type: The Runner type.
  • Version: Identifies the version of the Runner being used.
  • Java Version: Indicates the Java version installed on the machine where the Runner was allocated.
  • Last Telemetry Update: Informs the last time (date and time) that telemetry has been updated.
  • Runner Uptime: The time the Runner has been or is active.

System Information

Runners Information


  • OS Name: Name of the machine operating system where the Runner is allocated.
  • OS Version: Version of the machine operating system where the Runner is allocated.
  • CPU Architecture: Shows the architecture of the CPU.
  • CPU Usage: Indicates the percentage of use of the CPU.
  • Memory Total: Total system memory.
  • Memory Usage: Total memory in use.
  • Memory Free: Free total Memory.
  • System Uptime: The time the system is active.

Graph - Tasks per day

In addition to all the information, you can also follow a graph of the tasks performed on the Runner according to specific periods such as last week, last 15 days and last month.

Task Runner graphics

Processed Tasks

Accessing the Processed Tasks tab, you can view a list of tasks this Runner processed.

Runner Processed Tasks

Configuration File

Accessing the Configuration File tab, you can view the content of the conf.bcf file, which defines the Runner settings.

Runner Conf File