KlangoRPA logoKlangoRPA
Runners

Runners

A Runner is a headless process that polls your Management server for pending jobs and executes bots on the machine where it runs. You can have as many runners as you need — on your laptop, a VM, a server, or anywhere Python runs.

Setup

Step 1 — Generate an API key

In the Web Console, go to Runners → New Runner. Give it a name (e.g. my-laptop), click Create, then copy the API key shown. This key is shown only once — save it now.

Step 2 — Run the setup wizard

KlangoRPA.Runner --setup

Enter the Management server URL (e.g. http://localhost:8766 or your server's address) and the API key from Step 1. The wizard writes a config file at ~/.config/KlangoRPA/remote-runner.json.

Step 3 — Start the Runner

KlangoRPA.Runner

The Runner appears as Online in the Web Console within a few seconds. Keep it running in a terminal, or set it up as a system service using the scripts in scripts/ (systemd on Linux, Task Scheduler on Windows).

Note — Make sure only one Runner process runs per config file. Multiple processes sharing the same API key will all claim jobs unpredictably. If you start multiple Runners, create a separate key and config for each one.

Python & Library Requirements

Runners execute bots using the Python interpreter on the Runner machine. Python 3.9 or later is required. The Runner installs bot dependencies automatically via pip before each run.

Library allowlist

For security, the Runner only installs Python packages approved in your workspace's library allowlist. By default, 12 common packages are pre-approved:

playwrightopenpyxlpandasrequestsbeautifulsoup4lxmlpsycopg2-binarySQLAlchemyPillowpython-dotenvpyautoguipynput

To add more packages, go to Web Console → Libraries. Users with the Dev role or above can propose packages; users with the Adminrole can approve them.

Desktop bots — extra requirements

  • Windows desktop bots: pywinauto, pywin32, comtypes (pre-approved)
  • Linux desktop bots: xdotool and wmctrl must be installed as OS packages (not via pip)

Bot Compatibility

Each bot has an Automation Kind: Web, Desktop Windows, or Desktop Linux. The Management server checks the kind against the Runner's OS before dispatching a job.

Bot KindCompatible Runners
WebAny (Windows or Linux)
Desktop WindowsWindows Runners only
Desktop LinuxLinux Runners only

If you try to dispatch a Desktop Windows bot to a Linux Runner, the job is rejected immediately with an error — no Python is executed.

Runner Groups

Runner Groups let you dispatch bots to a pool of runners. The server claims the job to whichever available runner in the group picks it up first — simple load balancing without any extra configuration.

Create a group:

  1. Go to Web Console → Runner Groups → New Group.
  2. Add one or more Runners to the group.
  3. When dispatching a bot (Run modal, Queue, Trigger, Workflow), select the Group from the runner picker.

The group picker shows N of M online so you know how many runners are available before dispatching.

Note — Dispatch to a group is available in Triggers, Queues, and Workflows. The Bots Run modal (ad-hoc manual run) currently dispatches to a specific runner only.

Background Mode

By default, only one bot runs on a Runner at a time (the foreground slot). Background Mode lets a bot run concurrently alongside foreground bots, in a separate slot (up to 3 background bots simultaneously per Runner).

Enable Background Mode on a bot via Web Console → Bots → gear icon → Bot Config → Background mode.

Warning — Background Mode is for bots that do not need exclusive access to the display, desktop session, or shared local state. Using it for UI-driven bots on the same machine can cause clicks and keystrokes to interfere.

Imported Bots (Local Files)

If you have existing Python automation scripts you want to manage through KlangoRPA without re-recording them, you can import them as Imported bots. The script lives on the Runner machine's local filesystem rather than being uploaded to the server.

Hash verification

KlangoRPA can verify the integrity of imported scripts. After importing, click Re-sync in the Bot Config modal to have the Runner hash the file and send it back. Future runs display a Verified or Hash Mismatch badge in History.

Enable Strict Modeto abort runs when the hash doesn't match the last verified snapshot — protecting against unauthorized script changes.