The same server where Buddy On-Premises is first installed acts as the default worker of the instance. If you wish, you can install more workers on other hosts for extra performance.


CPU2.6 GHz
Memory4 GB
Root disk30 GB

Extra workers require a Linux-type server (we recommend Ubuntu 18.04) with Docker and docker-compose installed to run.

The worker must be able to connect to the main Buddy instance and vice-versa. You can configure the IP address and ports of the worker during the installation.


DO NOT install the worker on the server where the main instance of Buddy is installed as it already contains a fully operational worker.

  1. Go to the settings tab of your standalone instance:

Workspace preferences tabWorkspace preferences tab

  1. Click Add a new worker and copy the installation command.

Worker installation commandWorker installation command

  1. Launch a terminal on the server where you want to install the worker and run the copied command. Once the license is accepted, Buddy will install and run the worker. The command will also register the worker in the main instance.

You can also generate the command from the CLI on the server with the main instance by running sudo buddy install-worker. This option allows for extra config options described below.

Non-interactive Installation

You can automate creating and launching workers with the yes parameter in the install worker command:

  1. First, we generate the installation command and token on the server with the main instance:
buddy --yes install-worker >
  1. Next, we upload to the worker server:
scp ...
  1. The last step is to set up permissions and run the installation script:
chmod +x

Upgrading workers

To update a worker, run the following command:

buddy update

The version of the worker and the main instance must be the same. If the versions are different, you will not be able to assign new pipelines to the worker, and all pipelines assigned previously will fail with the "Wrong version" status.

Managing workers

You can view the list of currently connected workers in the Workers tab of the application settings.


Workers tabWorkers tab

Each worker has a status: - Testing – the main machine is running a connection test with the worker - Error – unable to connect to the worker. Make sure to check the worker status and/or firewall settings - Wrong version – the working is running, but its version is different from the main machine. Make sure to upgrade both the worker and the main instance to the same version - Connected – the workes is running and ready to use

Locking workers

You can lock a worker and change its name in the edit options. Locked workers cannot be assigned to new pipelines, either automatically or manually.

Locking workersLocking workers

Workers and pipelines

Due to cache and filesystem configuration, a pipeline is always run on one dedicated worker. You can assign a pipeline to a specific worker in the pipeline settings. If you don't assign a pipeline manually, Buddy will delegate it to the worker with the lowest load at the time of the first execution.

Assigning pipelines to workers

You can assign a pipeline to the worker in the pipeline settings.

Please mind that assigning a pipeline to a new worker will erase the pipeline's cache and the first execution might be longer.

Assigning YAML-configured pipelines to workers

To define the worker on which the pipeline should be launched in YAML, you need to add the worker field:

Defining workers in pipelineDefining workers in pipeline

You can find the name of the worker in the Workers tab in Standalone settings:

Workers tabWorkers tab

Offline workers

If a worker is offline or in a different version than the main instance, all pipeline executions will end with an error. It is also impossible to browse the filesystems and view execution logs of the assigned pipelines.

You can remove an inactive worker from the worker list (see above). Once the worker is removed, the pipeline will be automatically assigned to a new worker on the next execution.

Dedicated workers

You can assign a worker to specific pipelines in the workspace and lock all other pipelines from using it. To do that, follow these steps:

  1. Launch the worker
  2. Assign selected pipelines to the worker
  3. Lock the worker on the worker list – it will no longer be possible to choose it from the worker list in the pipeline settings nor auto-assign it on the first execution.

Filesystem, static files and cache

A pipeline is always fixed to a specific worker together with its cache and filesystem. This means that whenever a pipeline is switched to another machine, the cache is recreated from scratch.

The exception are static files uploaded to the filesystem. The static files are always stored on the main instance of Buddy and will be automatically downloaded on the first execution on the new worker.


Backing up workers is performed exactly the same way as backing up the main instance.

Solving connection problems

In order to work properly, the worker and the main instance must be able to communicate in two ways. For that, you must properly configure the IP addresses and ports that both machines use for connection.

By default, the worker connects to the public IP address of the standalone (the address that you use to open Buddy in your browser). The default ports are 1090 and 1091.

You can change connection details in two ways:

  1. By running buddy configure on the worker and selecting the proper option
  2. By adding a parameter to the buddy install-worker command:

  3. --standalone-host – the IP address of the main instance. You can change it if you are running your workers in an internal network
  4. --internal-host – the IP address of the worker server to which the build server will bind (default for all IP's)
  5. --external-host – the IP address/domain of the worker server to which them main instance should connect. By default, Buddy will detect the IP of the server and will ask for a correct address in case it's not able to connect
  6. --runner-internal-port – the port on the worker server to which the backend application will bind (default: 1091)
  7. --runner-external-port – the port used by the main instance to connect to the application on the worker (default: 1091)
  8. --registry-internal-port – the port to which the application registry will bind on the worker (default: 1090)
  9. --registry-external-port – the port used by the main instance to connect to the application registry on the server (default: 1090)
  10. --name – the name of the worker that will be installed. Used to describe the worker in Buddy's GUI
Sign up for Buddy Digest

Best practices on CI/CD and fresh changelogs delivered weekly to your inbox.