How to Register Your Chess Bot in 7 Steps

Want your AG (Artificial Gladiator) Champion (also called chess bot) playing real games against other people's AG Champions? On Artificial Gladiator League you don't need a server for that. Your code sits in a Hugging Face repo, and the site downloads it and runs it for you.

On the site we call a bot an AG Champion. It's a Python program that gets a board position and returns a move. This guide covers the seven steps in the order you'll do them, plus the mistakes that trip up most people the first time. There's also a guest option below if you'd rather try it first with no email. The site also plays Breakthrough, but the examples here use chess.

What you need

- A Hugging Face account. That's where your AG Champion files live.
- An email address, for the activation link. You can skip this if you start as a guest.
- Your Python code. If you don't have any yet, Step 3 shows how to copy a working example.

Want to try it first? Play as a guest

You don't have to make a full account to see your AG Champion in action. A guest account needs no email and no password. You sign in with Hugging Face, and the site only sees your public Hugging Face username.

Here's how it works:

1. Choose Continue with Hugging Face to sign in as a guest.
2. Open your Profile, go to the Gladiator tab and connect your repos. For a guest they must be Public, which means anyone can read your code.
3. The site downloads your repos and runs its usual checks in the sandbox, with stricter limits for guests.
4. Play unrated practice games in the Lobby against other guests.

Guests skip two things from the steps below: the Gated setting with the approval of ArtificialGladiatorLeague (Step 2) and the AGL_VERIFY.txt file (Step 5).

The trade-offs are real, though. Guest games are unrated, and there's no leaderboard spot and no tournaments. Your downloaded copy is deleted when you log out or after a short idle time, and guest accounts are removed after a few days without use. You can delete your guest data yourself at any time.

If you like it, create a permanent account from the guest banner. Your connected repos stay. Then follow the steps below for the full setup. The details are on the https://agladiator.com/how-it-works/ page.

Step 1: Create your account

Go to the registration page and fill in a username, a password, your email and an AG name, which is the display name of your AG Champion (bot). Choose your country of residence, tick the confirmation boxes, accept the terms and click Create Account.

Check everything before you submit. Your username, AG name and country can't be changed later.

An activation email arrives. Click the link in it. If nothing shows up after a few minutes, look in your spam folder.

Step 2: Create your Hugging Face repo

A repo is just a folder of files on Hugging Face. You need one for your bot. A second repo for data files is optional.

The quickest start is to copy one that already works. Open the example account, open one of its repos and click Duplicate this repo to copy it into your own account. Now you have a bot that already passes the platform's checks.

Then change two settings. Both matter:

1. In your repo's Settings, turn on Access Requests. This makes the repo Gated, so only people you approve can read it.
2. In the repo's access settings, approve the account ArtificialGladiatorLeague. The site reads your code through that account.

If you skip either one, saving your repo in Step 4 will fail.

If you add a data repo (for an opening book, for example), the rule is the opposite: it must be Public.
Playing as a guest? Skip the two settings above and keep your repo Public instead.

Step 3: Write your bot

Your AG Champion needs two functions:

- load(ctx) runs once, when the bot starts. Open your files here.
- get_move(state, fen, player) runs on every move. It receives the position as a FEN string and must return one legal move as plain text, like e2e4.

Here is the smallest version that works. It plays a random legal move:

``python
import random
import chess

def load(ctx):
return {}

def get_move(state, fen, player):
board = chess.Board(fen)
legal = list(board.legal_moves)
if not legal:
return ""
return random.choice(legal).uci() `

Save it as chess_mcvs.py at the top level of your repo. That's the file name the site looks for by default. Then swap the random choice for your real engine. Minimax, MCTS, a neural net: anything works as long as it returns a legal move in time.

Two limits to know about. Your code runs in a sandbox with no internet, so calls like requests will fail. And every move has a time limit. Both are explained under [Sandbox limits](/how-it-works/#rule-limits).

Add a small config_model.json to your repo too:
`json
{
"entrypoint": "chess_mcvs.py",
"files": ["chess_mcvs.py"]
} `

The https://agladiator.com/how-to-upload/ explains every field.

Step 4: Register your repo on the site

Log in, open your Profile and click the Gladiator tab. In Hugging Face Model Repo, type your-username/your-repo-name. Leave the data repo box empty unless you really have a data repo. For chess it may be pre-filled with owner/chess-data. Delete that text if you don't have the repo, or saving will fail.

Click Save and verify.

The site now shows you a 32-character verification code. You'll also see a red message saying AGL_VERIFY.txt wasn't found. That's normal. You haven't added the file yet.


Step 5: Prove the repo is yours

On Hugging Face, create a file named AGL_VERIFY.txt in your repo and paste the verification code into it. Commit it to the main branch.

Put it at the top level of the repo, not inside a folder. This is the most common reason verification fails. If you also use a data repo, it needs its own AGL_VERIFY.txt with the same code.

Go back to the Gladiator tab and click Verify Ownership. If it passes, the site runs a quick check on your code and locks in that version of your repo.
Guest accounts don't need this step.


Step 6: Run Diagnostics

Open the Diagnostics tab, pick your game and click Run diagnostics. It can take a few minutes, because it really runs your bot on sample positions.

Read the report and fix whatever it flags, then run it again. You're finished when the report ends with RESULT: your model works correctly. Diagnostics never changes your repo, so run it as often as you like.

Step 7: Play

Open the Lobby (it's labelled "Hatzar Grutaot" in the menu) and challenge another player. Your bot plays by itself.

To enter a tournament you first need to play a number of rated games in the Lobby, currently 30. After that, open a tournament and click Register or Join. Guests can't do this part, because guest games are unrated and tournaments need a full account.

One warning: once you've joined a tournament, don't push anything to your repo. Even a README edit creates a new version, and that disqualifies you automatically.

Mistakes that catch most people

- Not approving ArtificialGladiatorLeague. Without it, saving your repo fails.
- Putting AGL_VERIFY.txt in a subfolder. It has to be at the top level of the repo, on the main` branch.
- Making the data repo Gated or private. The data repo must be Public. The bot repo is the one that's Gated.
- Editing the repo after it was approved. A new commit resets your rated-games count to zero, and you'll need to click Re-check Ownership.

Quick answers

Can I try it without making an account?
Yes. Sign in as a guest with Hugging Face and connect Public repos. You can play unrated games against other guests. Rated games, the leaderboard and tournaments need a full account, and you can upgrade later without losing your repos.
Do I need to host a server?
No. The site runs your code on its own servers.
Can I use PyTorch or other libraries?
Only the libraries installed in the sandbox. There's no internet during games, so nothing can be installed later. The list is on the [How it works](/how-it-works/#rule-limits) page.
Can I update my bot later?
Yes, outside tournaments. Just remember that a new commit resets your rated-games count.
I'm stuck. Where do I look?
Run Diagnostics first. It explains problems in plain language. The [troubleshooting section](/how-to-upload/#troubleshooting) of the full guide covers the rest.

Have more questions? Do not hesitate to contact us at contact@agladiator.com.