Lichess Bot Setup Guide for macOS (BETA)

Welcome! This guide will walk you through setting up a Stockfish-powered bot on Lichess using Python on your Mac.

Note: This blog is in BETA. It will get better and more organized! Feel free to DM me with any questions.

---

Part 1: Setting Up the BOT Account

The first step is to upgrade your Lichess account to an official BOT account.

1. Get a BOT Account & API Token

1. Create an Account: Use a new Lichess account, or one with 0 games played.
2. Generate Token: Go to the API token creation page (all boxes are pre-checked).
3. Copy Token: Copy the token and put it somewhere safe! You will not be able to see it again.

2. Upgrade the Account via Terminal

Now, you'll use Terminal to send the upgrade request.

1. Open Terminal:

   • Press Command + Spacebarto open Spotlight Search.
   • Type Terminal.
   • Press Return (Enter)

2. Paste & Run the Command: Copy and paste the command below into Terminal, replacing the example token (lip_T8MoA0Bt5QzKJmFJxXMoeq8jJi3kGjK) with your previously generated token.

   curl -d '' [https://lichess.org/api/bot/account/upgrade](https://lichess.org/api/bot/account/upgrade) -H "Authorization: Bearer YOUR_TOKEN_HERE"
   

3. Verify Success:

   • If it prints ok}true, Amazing! You have a bot account now.
   • If it prints {"error":"No such token"}, double-check your token, and if needed, generate a new one.

You should now see a purple tag that says BOT on the left side of your username.

---

Part 2: Setting Up the Engine

Now that you have a bot account, you'll set up the chess engine (Stockfish) and the framework (lichess-bot).

1. Install Python & Clone the Framework

1. Install Python on Your Mac:

   • Go to the official Python website: https://www.python.org/downloads/
   • Download the latest stable version for macOS.
   • Run the installer and follow the instructions.
   • Verify: Open Terminal and type: python3 --version (e.g., you should see "Python 3.13.5")

2. Clone the lichess-bot Repository: Use the official framework.

   • In Terminal:

   git clone [https://github.com/lichess-bot-devs/lichess-bot.git](https://github.com/lichess-bot-devs/lichess-bot.git)
   

3. Change Directory & Install Packages:

   • Change into the cloned folder:

     cd lichess-bot
     

   • Install necessary dependencies:

     pip3 install -r requirements.txt
     

2. Download and Configure Stockfish

1. Download Stockfish for macOS:

   • Visit the official download page: https://stockfishchess.org/download/
   • Download the macOS ZIP file for the latest version.
   • Locate the ZIP file (usually in Downloads) and double-click it to extract the stockfish folder.

2. Prepare Stockfish in Terminal:

   • Navigate to the stockfish folder:

     cd ~/stockfish
     

   • Remove Quarantine Attribute (If necessary):

     xattr -d com.apple.quarantine stockfish-macos-m1-apple-silicon
     

     (If you get "No such xattr", ignore it and continue.)

   • Make Executable:

     chmod +x stockfish-macos-m1-apple-silicon
     

3. Test Stockfish:

   • Run it directly:

     ./stockfish-macos-m1-apple-silicon
     

   • If it runs, you will see something like: Stockfish 17.1 by the Stockfish developers...
   • Type uci to confirm functionality.

Debugging: Security Blocking

If macOS blocks the app for security reasons (you might get a message saying the app is from an unidentified developer):

1. Open System Settings.
2. Go to Privacy & Security.
3. Scroll down to the Security section.
4. Look for a message about blocking Stockfish and click Allow Anyway.
5. You may need to unlock with your password.
6. Repeat running Stockfish in Terminal. When prompted, choose Open.

---

Part 3: Final Configuration and Launch

1. Configure the config.yml File

1. Close Terminal, click Terminate running scripts, and then reopen it.
2. Navigate to your bot folder:

   cd ~/lichess-bot
   

3. Create the config file:

   cp config.yml.default config.yml
   

4. Open the config file in TextEdit:

   open -a TextEdit config.yml
   

5. Edit the file in TextEdit:
   • A. Add Your Token: Replace the example token with your actual one at the top:

     token: "YOUR_API_TOKEN_HERE"    # Lichess OAuth2 Token.
     

   • B. Find Your Username: Switch back to Terminal and type:

     whoami
     

   • C. Update Engine Path: Go back to TextEdit and search for engine:. Update the path using your whoami response:

     engine:
       dir: "/Users/YOUR-WHOAMI-Response-HERE/stockfish"
       name: "stockfish-macos-m1-apple-silicon" # The name of the file you downloaded
     

   • D. Save and Close the config.yml file.

2. Launch Your Bot!

You are ready to run the bot.

python3 lichess-bot.py config.yml

If you encounter issues, try this sequence:

cd ~/Downloads/lichess-bot-master  # Assuming default download path
source venv/bin/activate
python lichess-bot.py

Performance Notes

• This bot may consume up to 300% CPU on a Mac while playing. You can tweak performance settings in the text editor.
• 15-second games are not supported.
• Features like rematching and pairing systems are still under development.
• DO NOT share your API token with anyone. Use this bot at your own risk.

---

Starting and Stopping the Bot

Good luck, and have fun watching your bot play!