Skip to content

Running the worker: overview

vdbergh edited this page Feb 3, 2022 · 45 revisions

Get username/password for fishtest

In case you have not done so already, get a new account/password registering on fishtest:

Please mind that after the registration you will be automatically redirected to the login page. The message "Permission Required. Creating or modifying tests requires you to be logged in. If you don't have an account, please Register." is an information, not an error message.

Install the worker

In case you have not installed the worker on your computer yet, follow the installation instructions on these pages :

Launch the worker

To launch the worker using the default parameters (e.g. using 3 CPU cores) simply open a console window in worker directory and run the following command:


Enter your username and password when the worker asks for them. Alternatively you can specify username and password on the command line:

python3 username password

Add the option concurrency to control the number of CPU cores allocated to the worker. The safest max setting suggested is to use the number of physical cores leaving one core for the OS.

On a PC dedicated only to fishtest it's possible to set concurrency to the number of virtual cores leaving one core for the OS, but with the number of workers contributed today to the framework this is not strictly necessary.

python3 --concurrency MAX-1

If you don't set the concurrency parameter then the worker will use 3 cores.

The worker writes the parameters into the configuration file fishtest.cfg, so next time you can start the worker with the simple:


On Linux and Macintosh, you can use the nohup command to run the worker as a background task.

nohup python3 &

Worker parameters

python3 [<username> <password>] [-h] [-P <URL protocol>] [-n <URL domain>] [-p <URL port>] [-c <number of cores>] [-m <memory>] [-t <test min thread number>] [-f <fleet flag>] [-c <compiler>] [-w] [-v]

<username>          : your username on fishtest, first argument
<password>          : your password on fishtest, second argument
-h / --help         : show the help message and exit
-P / --protocol       PROTOCOL     : protocol of the fishtest server URL (string {https; http}, default: https)
-n / --host           HOST         : address of fishtest server URL (string, default:
-p / --port           PORT         : port of fishtest server URL (number, default: 443)
-c / --concurrency    CONCURRENCY  : the number of core allocated to the worker (number or string {MAX; expression}, default: 3, MAX to use all cores)
-m / --max_memory     MAX_MEMORY   : memory used by the worker (number or string {MAX; expression}, default: system memory/2 expressed in MB)
-t / --min_threads    MIN_THREADS  : minimum number of thread that a test must have to be assigned to the worker (number, default: 1)
-f / --fleet          FLEET        : stop the worker when fishtest has no task to do (boolean, default: False)
-C / --compiler       COMPILER     : compiler used to build binaries (string {g++; clang++}, default: g++)
-w / --only_config                 : write the config file and exit (no parameter)
-v / --no_validation               : skip the username/password validation with the server (no parameter)

CONCURRENCY and MAX_MEMORY can be set with an expression, also involving MAX, eg:
--concurrency "min(max(8, MAX/3-1), MAX/2)"  --max_memory "MAX/2 if MAX>16384 else MAX*3/5" 

see the available expressions

Worker limitations for systems with a large number of cores

Currently, the game-playing program (cutechess-cli) used by the worker will flag games as lost on time in case of a very large (>32) concurrency for very fast games. Hardware with more than 32 cores will therefore be assigned to tests running at long time control (LTC). In very rare cases, no LTC tests run on fishtest, in which case the worker might be idle.

workers with very many threads (e.g. 100) might exceed some of the defaults limits on a linux server. Ensure that max user processes (ulimit -u) and open files (ulimit -n) are sufficiently large.

Running the worker on CPUs with different core types

Some CPUs (e.g. Alder Lake) feature cores of different strength (named P and E cores in the latter case). To avoid playing matches between engines running on different hardware one has to restrict the fishtest worker to a subset of identical cores. Under Linux this is achieved with the taskset command:

(for an 8 P + 8 E setup like i9-12900K)
taskset -c 0-15 python3 fishtest/worker/ foo bar --concurrency 16
taskset -c 16-23 python3 fishtest/worker/ foo bar --concurrency 8 (or 7)

Stop the worker

To stop gracefully the worker write a file named fish.exit near the script, the worker will stop after finishing the batch games. On linux simply run the command touch fish.exit. Remember to delete the fish.exit before the next start or the worker will exit immediately.

By the way you can stop as soon as possible the worker simply killing the process, e.g. CRTL+C in the command window, using the kill command on linux etc. The games played by your worker will be used by the framework, but the total batch games number will be credited to the user that will complete your batch.

GitHub API requests rate limit

The worker makes some GitHub API requests. GitHub sets these rate limits:

  • 60 requests/hour for single IP address for unauthenticated requests
  • 5000 requests/hour for authenticated requests

The lower rate is perfectly fine for the majority of CPU contributors, to switch to the higher rate:

  • login on your GitHub account (sign up for a free account on GitHub)
  • from the token creation page create a new authorization token enabling the "public_repo" scope, copy the <personal-access-token> number
  • create a text file:
    • Linux and Windows Subsystem for Linux: touch ${HOME}/.netrc && chmod 600 ${HOME}/.netrc
    • Windows: C:\Users\<Your_Username>\.netrc or C:\Users\<Your_Username>\_netrc (check your $HOME)
  • write this content:
login <personal-access-token>
password x-oauth-basic


login <your_github_username>
password <personal-access-token>
  • on Windows be sure to delete the .txt extension (_netrc, not _netrc.txt)

Run the worker on Google Colaboratory

You can test how the fishtest worker works using a free 2 cores instance for max 6 hours on Google Colaboratory:

  • signup for a free account
  • create a new notebook
  • paste this text writing your fishtest username/password:
!git clone --single-branch --branch master
!python3 fishtest/worker/ <username> <password> --concurrency MAX
  • start the notebook
  • you can save the notebook on your Google Drive