lichess-bot: putting a UCI or XBoard engine onto lichess as a bot account

What it does: a protocol bridge, not a chess program

lichess-bot is described as a bridge between lichess.org and bots, and more precisely as a free bridge between the Lichess Bot API and chess engines. That distinction is the whole design. The project does not contain an engine, it contains the machinery that lets a separate engine play on lichess. The engine speaks UCI or XBoard or a homemade protocol, the bridge translates that into the Bot API's stream of moves, and the games appear on lichess as live games you can watch. The consequence for a user is that the interesting part of the work is yours, and the bridge is the part that handles the account, the polling, the protocol edge cases and the things a chess engine has no business knowing about.

The feature list, which is mostly about the tournament harness

The features are worth reading as a list of the things a bot account has to do competently. It supports every variant and time control, so the engine does not have to care. It supports UCI, XBoard and homemade engines. Matchmaking, meaning challenging other bots, which is how you get games rather than waiting for a human. Offering draws and resigning, because a bot that can neither draws nor resigns is a bad opponent. Participating in tournaments, which is the main way to get rated play. Accepting move takeback requests from opponents, which is a real edge case that a scripted bot gets wrong. Saving games as PGN, so the games are usable afterwards. And local and online opening books, plus local and online endgame tablebases. That last pair is what turns a bot into a serious opponent, and both being available locally and online is unusual.

The six steps, and the order they depend on each other

The Steps section is a numbered list, and the ordering is not decorative. Install lichess-bot, then create a lichess OAuth token, then set up the engine, then configure lichess-bot, then upgrade to a BOT account, and then run lichess-bot. The upgrade step comes fifth and before running, which is the detail a newcomer gets wrong. The documentation is a wiki, with separate pages for How to Install, How to create a Lichess OAuth token, Setup the engine, Configure lichess-bot, Upgrade to a BOT account, and How to Run lichess-bot, and the README sends you there rather than duplicating the instructions.

Where the code lives, and what the entry points suggest

The repository layout is informative. There is lichess-bot.py at the top level, which is the entry point, a lib/ directory holding the bulk of the implementation, an engines/ directory, a docker/ directory, a docs/ directory and a wiki/ directory. Two files at the top level describe the extension points, extra_game_handlers.py and homemade.py, which correspond directly to two of the documented advanced options, Add extra customizations and Create a homemade engine. That is a clean signal that the project intends to be extended rather than merely run. There is also config.yml.default at the top level, which is the configuration template you copy and edit, a requirements.txt, a test_bot/ directory for the test suite, and a CITATION.cff for research use.

The dependency list is short, and python-chess does the engine work

The requirements are five lines. chess at about 1.11, PyYAML at about 6.0, requests at about 2.34, backoff at about 2.2 and rich at about 15.0. The acknowledgements section explains the role of the first one, giving thanks to Niklas Fiekas for the python-chess code which allows engine communication seamlessly. The other four have obvious jobs. PyYAML is the configuration file, requests is the API client, backoff is the retry policy for a network client talking to a public server, and rich is the terminal output, so a bot running over SSH gives you a readable log rather than a wall of print statements. The set is small enough to read in full, which is unusual for a project of this size and a good sign for the maintenance burden.

chess~=1.11
PyYAML~=6.0
requests~=2.34
backoff~=2.2
rich~=15.0

What it can run on, and the AGPL question

The Can run on list is short and useful. Python 3.10 and later, on Windows, Linux and MacOS, and Docker. The Docker directory in the repository confirms the container path is a real supported mode rather than an afterthought, and for a bot that runs continuously on a small machine a container is the sensible deployment. The licence is the item to read carefully. lichess-bot is licensed under the AGPLv3, or any later version at your option, and the README points at the LICENSE file for the full text. The AGPL is a network copyleft licence, so if you run a modified version of this bridge as a service for other people, the source obligation applies to the modified version. For a personal bot run on your own account that is not a practical concern, and for someone planning to build a hosted bot service on top of it, it is the first thing to check.

Upkeep and where the project stands

The last push to the repository was on 2026-10-14, the repository is not archived, and the primary language is Python. There are no GitHub releases, which is the usual arrangement for an application that people install from the wiki instructions rather than from a release artefact, and the CI configuration reflects a project with a real test suite, with separate GitHub Actions workflows for the Python build, the Python test and Mypy, so the type checking is a gate rather than an aspiration. The acknowledgements also credit the Lichess team, specifically T. Alexander Lystad and Thibault Duplessis, for working with the LeelaChessZero team to get the Bot API up, which is the context for why a bridge like this is possible at all. The project also asks that research use cite it through the Cite this repository menu and the CITATION file.

Editorial conclusion

lichess-bot suits a chess programmer who has an engine, or wants to write one, and wants it to play real games on lichess rather than analyse positions offline. It is the wrong choice if you need a bot that keeps playing at scale, because a lichess account and a bot token are the gating factors, and a poor fit for a closed engine you intend to keep private, because the AGPLv3 licence is the one to read first. Before you start, work through the six documented steps in order, since the OAuth token and the engine setup are prerequisites to running anything, and read the AGPLv3 terms, as the licence field says AGPLv3 or any later version at your option.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. lichess-bot-devs/lichess-bot on GitHub
4. README