Skip to content

Runner Setup

As we saw previously, BotCity Runner is responsible for requesting tasks from BotCity Maestro and executing them in an runtime environment.

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

  • Creation of a Runner in BotCity Maestro (see more details here).
  • Runner configuration in the runtime environment.

In the following sections, we will look at more details on installing and configuring a Runner in the runtime environment.

Configuring a Runner in the runtime environment

BotCity Runner is part of the BotCity Studio SDK. To use the tools correctly, consult the documentation regarding the installation of the BotCity Studio SDK.

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

Wizard Setup Runner

From this screen, we can select the Setup BotCity 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 view all existing Runners in your Maestro workspace.

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 Maestro.


You can also create new Runners from the Wizard; just select the Create a new One 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.

Customizing Runner configuration


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.

The BotCity Studio SDK configuration file has some BotCity Runner-specific settings.

Some of these settings are already included by default when installing the BotCity Studio SDK.

machineId=<Runner ID>

In addition to the default settings, we can also include custom settings as needed.

In the table below, we can see more details about the additional configurations available that can be used in the Runner configuration file.

Setting Required Default Description
machineId Yes The unique identifier of the BotCity Runner instance.
javaParams No JVM parameters to be passed for the execution of the automation.
pythonBinary No python The Python binary to be used such as python3, py or the full path to the binary
logScreen No true If set to true, it enables screen sharing with BotCity Maestro for GUI based automations.
logApplication No true If set to true, it enables log sharing with BotCity Maestro.
logTelemetry (since 2.7.0) No false If set to true, it enables system telemetry sharing with BotCity Maestro such as CPU %, Memory Usage, etc.
startup No The path to a startup script to be executed once BotCity Runner starts its execution.
beforeTask (since 2.7.0) No The path to a script to be executed before each task.
debugEnabled (since 2.7.0) No false Whether or not to produce extra verbose log output.
ignoreSSL (since 2.7.0) No false Whether or not to ignore SSL issues when communicating with BotCity Maestro. This is useful when your network intercepts HTTPS connections.


In the conf.bcf file, you must include the name of the desired configuration and the value it will receive.

Starting the Runner

BotCity Runner now supports execution with or without a graphical user interface (GUI).

Execution with GUI

Simply run the BotRunner-gui script available with your BotCity Studio SDK or use the -gui parameter if invoking the botrunner.jar file manually.

In this case, it is necessary to click on the START button so that the Runner establishes a connection with the Maestro and starts processing the tasks.


Headless Execution (no GUI)

Simply run the BotRunner script available with your BotCity Studio SDK. Only a terminal referring to the Runner process will be started in this case.

Container Execution

It is possible to run the Runner in containers using our images, see more in the containers section.