Balancing Methods

There are four methods available for balancing Workbench Sessions across a cluster. The most appropriate method is installation specific and depends on the number of users and type of workloads they create.

System load

The default balancing method is system-load, which distributes sessions based on the active workload of available nodes:

balancer = system-load

The metric used to establish active workload is the 5-minute load average, divided by the number of cores on the machine. This is a good choice if you expect widely disparate CPU workloads and want to ensure that machines with high CPU utilization don’t receive new sessions.

User hash

The user-hash balancing method attempts to distribute load evenly and consistently across nodes by hashing the username of clients:

balancer = user-hash

The hashing algorithm used is CityHash, which will produce a relatively even distribution of users to nodes. This is a good choice if you want the assignment of users/sessions to nodes to be stable.


This method is currently supported for RStudio Pro Sessions only. It will evenly distribute RStudio Pro Sessions across the nodes of the cluster:

balancer = sessions


The custom balancing method calls out to external script to make load balancing decisions:

balancer = custom

When custom is specified, Posit Workbench will execute the following script when it needs to make a choice about which node to start a new session on:


This script will be passed two environment variables:

RSTUDIO_USERNAME — The user on behalf or which the new session is being created.

RSTUDIO_NODES — Comma separated list of the host and port of available nodes.

The script should return the node to start the new session on using its standard output. Note that the format of the returned node should be identical to its format as passed to the script (i.e. include the host and port).

Node host format

In earlier versions of RStudio, the custom load balancing script would always be passed a list of raw IP addresses in RSTUDIO_NODES; now, RSTUDIO_NODES will contain the hosts as specified in the load-balancer file. If you want to specify host names in your load-balancer file but work with raw IPs in your custom load balancing script, you can set the following option:


Note that this option is incompatible with SSL unless your servers’ SSL certificates contain IP addresses in their CN/SAN.