fairyfishnet

Distributed Fairy-Stockfish analysis for pychess.org.

fairyfishnet requires Python 3.8 or newer.

Installation

1. Request a personal fairyfishnet key on the pychess Discord server.

2. Install uv.

3. Install the worker as an isolated command-line tool:

   uv tool install --with pip fairyfishnet
   

4. Start the worker and follow the configuration prompts:

   fairyfishnet --auto-update
   

To upgrade manually:

uv tool upgrade fairyfishnet

The extra pip package keeps the worker's existing --auto-update behavior available inside the isolated uv tool environment.

systemd

Generate a service file after configuring the worker:

fairyfishnet systemd

The command prints a service definition that can be reviewed and installed under /etc/systemd/system/.

Docker

Build the image. The Dockerfile installs the latest released fairyfishnet package from PyPI; it does not install the current checkout:

docker build -t fairyfishnet .
docker run --rm fairyfishnet --key MY_API_KEY --auto-update

Fairy-Stockfish

fairyfishnet uses the pychess-variants build of Fairy-Stockfish.

A suitable precompiled engine is downloaded automatically. To use a locally built engine, run ./build-stockfish.sh and pass its path with --stockfish-command.

Engine lifecycle, UCI, dynamic variant, and cache invariants are documented in ENGINES.md.

Development

The repository uses a src/ package layout and keeps tests under tests/.

Create the locked development environment using the oldest supported Python:

uv sync --locked --python 3.8

Run the fast tests and quality checks:

uv run pytest -m "not engine"
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv lock --check --python 3.8
uv build

The engine integration tests download or launch Fairy-Stockfish:

uv run pytest -m engine

Apply formatting with:

uv run ruff format .

Whenever project or development dependencies change, refresh and commit the lockfile:

uv lock

Repository layout

src/fairyfishnet/__init__.py   package metadata only
src/fairyfishnet/cli.py        argument parsing, commands, signals, and worker orchestration
src/fairyfishnet/config.py     configuration loading and validation
src/fairyfishnet/engine.py     subprocess management and the UCI protocol
src/fairyfishnet/worker.py     job acquisition, move generation, and analysis
src/fairyfishnet/variants.py   server variants.ini download and scoped cache lifecycle
src/fairyfishnet/downloads.py  engine downloads and self-update handling
src/fairyfishnet/cpuid.py      low-level CPU capability probing
src/fairyfishnet/http_utils.py HTTP and release-version helpers
tests/                         focused unit tests and engine integration tests
scripts/                       release and maintenance helpers
doc/                           fishnet protocol documentation

The fast suite is intentionally split by subsystem, so a regression normally points to the module that owns the behavior. Tests marked engine download or launch Fairy-Stockfish and are therefore slower and require network access on a clean checkout.

Protocol

See doc/protocol.md for the worker/server protocol.

Releasing

Set UV_PUBLISH_TOKEN, then run:

uv run python scripts/release.py

The release helper runs tests, Ruff, Pyright, builds distributions, verifies a clean Git tree, creates the version tag, pushes it, and publishes with uv.

License

fairyfishnet is licensed under GPL-3.0-or-later. See LICENSE.txt.