Hackerspace idle CPU for the free chess commons.
idlefish is a small Sanca Hackerspace project for donating spare CPU time to Lichess analysis through fishnet, the volunteer compute client used by Lichess.
The project helps members run fishnet carefully on desktops, homelab machines, and small VPSes, then publish simple community metrics such as uptime, active nodes, and estimated CPU-hours donated.
The dashboard uses a pull model: each participating machine publishes a small read-only JSON metrics file, and GitHub Actions periodically fetches those files to rebuild the public page. Contributors do not need GitHub push access, and they can adapt the publishing setup to their own Linux environment.
It is not a fishnet replacement and it is not affiliated with Lichess.
Hackerspaces often have machines that sit idle for long stretches of time. When it is safe to do so, those machines can contribute useful Stockfish analysis capacity to the free chess community.
The goal is not to maximize numbers at any cost. The goal is to make spare compute donation visible, responsible, and easy to turn off.
Fishnet can use a lot of CPU.
On shared machines, small VPSes, or hosts already running services like MQTT, Grafana, Postgres, or TimescaleDB, start with 1 core and watch the machine for load, memory pressure, swap, and service slowdowns.
Fishnet keys are personal secrets. Never commit them, publish them in dashboard data, or paste them into issues or chat.
The public dashboard shows local community metrics:
- estimated CPU-hours donated
- analysis jobs completed
- chess positions analyzed
- active fishnet nodes
- fishnet service health
- service restarts
- load average and available memory
CPU-hours are local estimates from service/runtime data. They are not official Lichess contribution stats.
The dashboard also links to Lichess contribution options and the official fishnet project so visitors can find other ways to support the free chess commons.
-
Request a fishnet key from Lichess.
-
Clone this project on the machine:
git clone https://github.com/sancahs/idlefish.git cd idlefish -
Download or build the fishnet binary from the official fishnet releases, saving it as
./fishnetinside this directory. -
Install the conservative systemd service, or adapt the service setup to your environment:
sudo scripts/install-fishnet-systemd.sh ./fishnet
-
Configure fishnet manually:
sudo -u fishnet -H sh -lc 'cd /var/lib/fishnet && /opt/fishnet/bin/fishnet configure' -
Start the service:
sudo systemctl enable --now fishnet journalctl -u fishnet -f -
Collect local metrics:
IDLEFISH_NODE_NAME=my-node scripts/collect-local-metrics.sh > /var/www/idlefish/my-node.json -
Ask a maintainer to add your public metrics URL to
config/nodes.json.
More detailed setup notes are in docs/getting-started.md, docs/running-on-small-vps.md, and docs/publishing-node-metrics.md.
The v0 pull-based dashboard architecture is described in docs/architecture-v0.md.
Generate the static dashboard data:
python3 scripts/fetch-node-metrics.py
python3 scripts/generate-site.pyPreview locally:
just previewThen open:
http://localhost:8000
If that port is busy, pass another one:
just preview 8001To serve the already generated files without fetching fresh node metrics:
just servejust preview needs network access to fetch the public node metrics listed in config/nodes.json. If you are offline, use just serve to view the checked-in sample data.
GitHub Pages publishes the site/ directory using the workflow in .github/workflows/pages.yml. The workflow also runs on a schedule, fetches every URL listed in config/nodes.json, and rebuilds the dashboard without requiring node operators to commit anything.
This project helps people run and monitor fishnet responsibly.
It does not:
- implement a fishnet client
- reverse-engineer Lichess
- scrape private Lichess data
- store fishnet keys
- claim official contribution stats
MIT. See LICENSE.