Concepts and rules

How the AGL Platform Works

The platform plays Chess and Breakthrough games for the program you build, called your AG Champion. You keep your files in your own Hugging Face account. The platform copies them to its own servers and runs them in a locked, isolated sandbox, so you never host anything yourself.

This page explains what happens and the rules that affect you. Looking for the setup steps? See How to register your AG Champion.

Before you read

  • You need nothing: no software to install and no sign-in.
  • To find one answer fast, use the contents list.

The big picture

Your AG Champion (Artificial Gladiator Champion) is the program that plays for you. It is Python code (Python is a programming language) that receives a board position and returns a move. You keep the code in a repo, which is a folder of files stored on Hugging Face. The platform copies your repo to its own servers and runs it in a sandbox, a locked box that cannot touch anything else, so you never host anything yourself.

  1. Your repo on Hugging Face
  2. Copied to the platform's servers
  3. Run in the sandbox
  4. Moves played in your games

Next step: Play as a guest

Just Want to Try It? Play as a Guest

This is the quickest way to start. A guest account needs no email and no password. You sign in with Hugging Face and connect your own Public repo.

Want the exact steps? See Quick start for guests.

  1. Continue with Hugging Face. The platform only receives your public Hugging Face username.
  2. Connect your Public repo. On the Gladiator tab, enter a model repo that belongs to your own Hugging Face account. The data repo is optional: leave it empty if you do not have one. A repo ID that contains "--" is rejected for guests, and size and file-count limits apply.
  3. Platform model check. The platform downloads a fixed version of your repo and runs the same checks in the sandbox, with stricter limits for guests. The check takes about a minute.
  4. Play unrated practice games against other guests, or watch your AG Champion play ShiRi, the platform's own AI opponent.
  5. Clean-up. Your downloaded snapshot is deleted at logout or after 2 idle hours, and the guest account after 3 days of inactivity. You can also delete your guest data at any time.
Note

Guests have no rated games, no leaderboard entry and no tournaments. The forum, blog and leaderboard are read-only for guests.

Next step: Want ratings and tournaments? Register a full account

Want Ratings and Tournaments? Register a Full Account, Step by Step

A full (registered) account is needed for rated games and tournaments. The path has seven steps. Each title links to the full instructions.

  1. Create your account Your country of residence, username and AG name are locked once chosen (see Your account).
  2. Create your Hugging Face repos A Gated model repo, and optionally a Public data repo. Approve the platform's account on the model repo.
  3. Write your AG Champion Python code with two functions, plus a config_model.json file that names your code file.
  4. Register your repos Enter them on the Gladiator tab of your Profile.
  5. Prove you own your repos Add the file AGL_VERIFY.txt with your code, then click Verify Ownership.
  6. Run Diagnostics Pass the model check in the Diagnostics tab.
  7. Play rated games and enter tournaments Tournaments have a qualification rule (see Tournament qualification).

Next step: Learn what the two repos are for

Your two repos: model repo and data repo

Hugging Face accounts can hold several kinds of repos. Your AG Champion uses the two below. Gated means only accounts you approve can read the repo. Public means anyone can read it.

The two repo types
RepoWhat it holdsNeeded?Visibility
Model repo Your code and config files (and weights, if you keep them there). The platform downloads it to its own servers and runs it in the sandbox to generate moves. Required Gated for registered accounts. A guest account connects a Public repo instead. A registered account must also approve the platform's account ArtificialGladiatorLeague on it.
Data repo Supporting data files your AG Champion needs while playing, for example opening books or precomputed tables. It is mounted read-only next to your model inside the sandbox. Optional Public

What happens if a repo does not meet these requirements is explained in Repo access.

Next step: See where your AG Champion runs

Where your AG Champion runs: the sandbox

A common question: "When I play, where does my AG Champion actually run?" It runs in a sandbox on the platform's own servers. The sandbox is an isolated, locked-down container (a Docker container). There is nothing for you to host or keep running.

The exact limits of the sandbox are listed in Sandbox limits.

How the sandbox is started, reused and stopped Technical

Your sandbox is kept warm. The platform keeps one sandbox container per AG Champion and reuses it between moves. Your load(ctx) function runs once, and each move only costs a get_move(state, fen, player) call. The container is not thrown away after every move.

  • It is started ahead of time when you open the Lobby or a game page, so the first move is not a cold start. The Lobby is labelled "Hatzar Grutaot" in the menu. This is Hebrew (חצר גרוטאות) and means "Scrapyard". The name was coined by Malka Haas.
  • An idle container is stopped automatically (after 15 minutes without a move) and started again when needed.
  • It is restarted if your model files change, the container dies, or a move times out.
  • Your code never runs outside the sandbox. If the sandbox itself is unavailable, that is a platform problem: the game is cancelled and nobody loses (see When the sandbox is unavailable).

Next step: See what happens at login, in a game and at logout

What happens when you log in, play and log out

Three moments matter. Each one is described below.

At login

Logging in prepares your private workspace on the server and makes sure your registered repos are available locally.

  • For each AG Champion you registered, the platform looks for a copy of your model repo in its shared Hugging Face cache (its stored copies of repos). If there is none yet, it downloads one now. If there is, nothing is downloaded. A problem here does not block your login.
  • Private model and data folders are created for your account (Chess and Breakthrough), and a per-session workspace folder is created for you.
  • Your data repo files are not downloaded at this point. They are fetched the first time your AG Champion is loaded into a sandbox. That normally happens in the background when you open the Lobby (where login lands you) or a game page.

During a game: how a move is generated

Every single move, for both players, is generated live by calling your AG Champion in its sandbox. Moves are never precomputed.

  1. Board position sent
  2. Your get_move runs in the sandbox
  3. Move validated
  4. Game state updated

If a move goes wrong, the platform follows the rules in When a move fails.

At logout

The private workspace created for you is removed from the server.

  • Your per-session workspace folder and your private model and data folders on the server are deleted. That includes the copy of your data repo files, which is downloaded again the next time your AG Champion is loaded.
  • You are removed from the online-players counter.
  • Your Hugging Face repos are not touched. They remain exactly as you left them and remain the source of truth.
  • Your Elo, match history and registered repo links are stored in your profile and are not affected by logging out.
  • Sandbox containers are not tied to your login. An idle one is stopped automatically after its idle timeout.
  • Guest accounts are cleaned up differently. See Clean-up for guests.

Next step: Play your AG Champion against ShiRi

Playing against ShiRi

ShiRi is an AI opponent built into the platform. It plays Chess and Breakthrough using Monte Carlo Vector Search (MCVS). In a ShiRi game your own AG Champion plays against ShiRi and you only watch. You do not move any pieces. It is a quick way to see your AG Champion play without waiting for another player.

  1. Your AG Champion moves (in the sandbox)
  2. ShiRi moves
  3. Repeat until the game ends

How to start

  1. Open Playing against ShiRi in the "Hatzar Grutaot" menu, or click Play against ShiRi on the home page.
  2. Choose the game (Chess or Breakthrough), the colour ShiRi plays (White, Black or Random) and the time control: minutes per side and increment (seconds added after each move), with the same options as Create Lobby Game.
  3. Choose the AI thinking time twice: your AI's time per move and ShiRi's time per move (3, 5, 8, 12 or 15 seconds each).
  4. Click Start Game and watch. The Stop button ends the game at any moment.

What you need

  • You must be logged in. Guests can play too.
  • You need your own AG Champion for the game you choose. You can only ever run your own AG Champion. If you have none for that game, the page says so and the game does not start.
  • Your model repo must be registered and its model check must not have failed. Registered accounts must also have proved ownership of the repo.
  • Guests: your repo must be downloaded and checked first. Until then the page shows "Preparing your model..." and the game does not start. Guests also have stricter sandbox limits.

What happens in the game

  • Every move of your AG Champion is generated live in its sandbox, exactly as in a Lobby game (see During a game). The move time limit is 30 seconds.
  • Your AI's thinking time is a target pace, as in a Lobby game: if your AG Champion answers faster, the move is shown only when that time is up. Your clock keeps running during this wait, because it is still your turn.
  • ShiRi's moves are calculated by the platform. ShiRi searches for the time per move you chose, and for less when her own clock is low.
  • Both sides have a clock and only one clock runs at a time. When a side moves, its clock stops and its opponent's clock starts at the same instant. The increment is added after every move. A side that runs out of time loses on time.
  • While a game runs, ShiRi also plays quick practice games in the background and learns from them. This memory is deleted when the game ends. Every new game starts with an empty memory.
  • A ShiRi game is unrated and is not saved. It does not change your Elo, does not count toward tournament qualification and does not appear in your game history.
  • A game that reaches 300 moves is declared a draw.

When your AG Champion fails in a ShiRi game

Different from Lobby games

In a ShiRi game no random move is ever played for your AG Champion, so a random move can never make it look better than it is. If your AG Champion returns no move, an illegal move, or does not answer in time, it forfeits and the page says why. A move such as e7e8 without the promotion letter counts as illegal, as everywhere on the platform.

Note

If the sandbox itself is unavailable, or the platform is missing your downloaded files, the game is cancelled with no result. The page says it is a platform problem and not your fault. This is the same principle as in When the sandbox is unavailable.

Next step: Read the rules and limits

Rules and limits

Guests only need to know Sandbox limits and When a move fails.

These rules have consequences for you. Each rule is explained once, here. Other pages link to this section.

Your account

Important

Your country of residence, username and AG name are locked once chosen. Your username and AG name cannot be changed at any point. To change your country of residence, you must contact support.

Your AG name is the display name of your AG Champion.

Repo access

Important
  • Approve the platform's account. In your model repo's Access settings, approve ArtificialGladiatorLeague. The platform uses that account to read your repo for the ownership check and to download it. Without the approval, saving, ownership checks and your games all fail.
  • The model repo must be Gated. When you save a repo, the platform checks that it exists and is Gated. A public model repo is rejected. Guest accounts use Public repos instead.
  • The data repo must be Public. When you save it, the platform checks it anonymously, without any token. A private or gated data repo is rejected.
  • No token needed. The platform does not ask for your Hugging Face token. It reads your Gated model repo with its own account.
Tip

Why Gated? Gating also protects your code from being copied by other visitors.

Tournament qualification

Note

You need 30 rated games with your AG Champion before you can join a tournament. Registering your AG Champion (Steps 1 to 6 of the setup guide) does not need them.

  • A game counts when it is finished, was played outside a tournament and is not a guest game. Chess and Breakthrough are counted separately.
  • The count goes back to 0 only when you change your model repo ID or the platform finds a new commit in your model repo. Re-checking ownership when nothing has changed does not reset it.
  • The platform checks the count again when the tournament starts. A player with fewer than 30 games is removed.

Why: 30 rated games establish a meaningful Elo rating and confirm that your AG Champion is stable and reliably responsive before it enters structured competition.

The period after you change your model repo ID is called the repo-change cooldown.

For how tournaments run, see How tournaments work.

Version pinning and disqualification

Warning

Do not push changes to your AG Champion repo after joining a tournament. You will be disqualified automatically. A changed SHA (the unique ID of a commit) is how the platform detects the change.

  • At tournament registration, the exact commit SHA of your model repo is recorded.
  • Before and during tournament games, the SHA is checked again. Any commit since registration triggers automatic disqualification.
  • Even trivial changes (README edits, whitespace) produce a new SHA. Freeze the repo once you are registered.
Important

Changes outside tournaments also have a cost. If you push a new commit to your model repo or your data repo after your AG Champion was approved, you cannot join tournaments until the platform approves the new commit. Lobby games stay available.

To fix it, click Re-check Ownership on the Gladiator tab, then play your qualifying games again (see Tournament qualification).

Sandbox limits

The values below are the platform's current settings. They can change.

What your AG Champion can and cannot do in the sandbox
LimitValueWhat it means for you
NetworkNone at allCalls such as requests or urllib fail.
Writable spaceA small temporary folder, /tmp (64 MB)Your model, your data and the runner are mounted read-only. /tmp is the only place you can write.
Memory512 MBKeep your AG Champion light.
CPU1 CPUKeep your AG Champion light.
Processes and threads128Do not start more than this at once.
Move time limit30 seconds per moveA slower move is replaced (see When a move fails).
Cold start time limit120 secondsStarting the container and running your load() may take this long.
Librariesnumpy, python-chess and torch (CPU only)The sandbox image is fixed and nothing is installed at match time. The project's sandbox image definition installs these libraries. Do not depend on other third-party packages.
Security settings of the sandbox Technical
  • Read-only filesystem. Your model, your data and the runner are mounted read-only.
  • Locked-down process. It runs as an unprivileged user, with all Linux capabilities dropped and privilege escalation disabled.

When a move fails

Note
  • If your AG Champion answers within the move time limit with a legal move, that move is used. It is shown at once, or after the configured thinking time target, whichever is longer.
  • If it is too slow, raises an error, returns nothing, or returns an illegal move, the platform plays a random legal move for that turn (captures preferred) so the game keeps going. When a move times out, the container is restarted.
  • The time your AG Champion spends thinking is deducted from your game clock.
Note

If your AG Champion's last model check failed, no random move is played and you forfeit the game.

Note

When the sandbox is unavailable. This is a platform problem, never your fault, so no player loses and no random move is played.

  • A game in the Lobby is cancelled with no result and no rating change.
  • A tournament game is cancelled the same way and replayed 60 seconds later, with the same colours and full clocks. A match gets up to 3 games.
  • After the last one, the match is postponed and the organizers are notified. Players see: "Match postponed because of a platform problem. The organizers have been notified."

Only a problem with the sandbox itself counts. A move that is too slow, a crash, no move or an illegal move from your own AG Champion keeps the rules above.

Note

Games against ShiRi follow different rules for failed moves: no random move is played and your AG Champion forfeits. See When your AG Champion fails in a ShiRi game.

Next step: See the ranking titles

Ranking titles

AGL titles are based on the FIDE Elo scale (FIDE is the international chess federation). Your AG Champion earns a title automatically as its Elo rating climbs, separately for Chess and Breakthrough.

Titles and the Elo range for each
TitleElo range
Super GM2700+
Grandmaster2500–2699
Intl. Master2400–2499
FIDE Master2300–2399
Cand. Master2200–2299
Expert2000–2199
Class A1800–1999
Class B1600–1799
Class C1400–1599
Class D1200–1399
Beginner< 1200

Why it is built this way

Four design goals Optional reading
  • Safe by default. Submitted code runs in a sandbox with no network, a read-only filesystem and CPU, memory and time limits, so an AG Champion can neither reach out nor change anything on the server. Details: Sandbox limits.
  • Fair, identical treatment. Every AG Champion, from a beginner's random-move bot to a Grandmaster-rated neural net, is called the same way, through the same load / get_move contract, inside a sandbox with the same limits.
  • Fast moves. Keeping one sandbox warm per AG Champion means your code is loaded once, not before every move, so the move time is spent thinking rather than starting up.
  • You stay in control. Your code stays in your own Hugging Face repo, which is Gated: only accounts you approve, including the platform's ArtificialGladiatorLeague account, can read it. You prove ownership with an AGL_VERIFY.txt file in your repo.

Frequently asked questions

Which games are supported?

Currently Chess and Breakthrough. Each game is registered independently, so you can enter different AG Champions for each.

How strict is the per-move time limit?

Each move has a server-side limit (30 seconds). Exceeding it does not forfeit the game: a random legal move is played for that turn. The exception is explained in When a move fails. Your thinking time is also deducted from your game clock, so always keep get_move fast.

Can I play against ShiRi myself?

No. In a ShiRi game your AG Champion plays and you only watch. See Playing against ShiRi.

Does a ShiRi game change my Elo?

No. ShiRi games are unrated, are not saved, and do not count toward tournament qualification. They are a safe way to test your AG Champion. One difference to remember: a failed move is a forfeit, not a random move (see When your AG Champion fails in a ShiRi game).

What is "AI thinking time", and is it guaranteed?

"Thinking time" (configured when creating or joining a game) is a target pace for AI moves, not a hard guarantee. Actual move latency depends on how fast your AG Champion runs inside the sandbox. Heavier models or deep searches take longer.

If a move arrives faster than the target, the platform waits to reach the target before showing it. If your AG Champion responds slower, the move is still accepted and used. The game creator and the joining player each set their own thinking-time target independently for their own AI.

Glossary

Short definitions of the terms used on this page and in the setup guide.

AG Champion
The program you build to play for you. Its full name is Artificial Gladiator Champion. It is Python code that receives a board position and returns a move.
AG name
The display name of your AG Champion. You choose it when you create your account, and it is locked afterwards.
AGL
Artificial Gladiator League. This is the name of the platform (agladiator.com).
Cold start
The first start of your sandbox, which includes running your load() function.
Commit
A saved change in a repo. Every commit has its own ID, called a SHA.
Config file
A small JSON file at the root of a repo that describes its files. JSON is a plain-text format for settings. The files are config_model.json and config_data.json. config_model.json names your entry-point file under "entrypoint". config_data.json is only for a data repo.
Contract
The two functions your code must define: load(ctx) and get_move(state, fen, player). There is no other interface.
Cooldown (repo change)
The period after you change your model repo ID. Until you have played 30 rated games, you cannot join tournaments. Diagnostics reports it as "Repo-change cooldown is active".
Data repo
An optional, Public repo with data files your AG Champion reads while playing, such as opening books.
Diagnostics
A tab on your Profile that checks a registered AG Champion from start to finish and tells you in plain language what to fix. It never changes anything.
Elo
The number that rates the playing strength of your AG Champion. Results of rated games update it.
Entry-point file
The Python file (.py) that the platform runs to start your AG Champion. You tell the platform which file to run by writing its name in config_model.json, under "entrypoint". NAME_OF_ALGO_FILE.py is a name you choose, for example my_bot.py. It must end in .py and have no spaces. Use the same name everywhere.
FEN
A line of text that describes a board position. It is the position your code receives in get_move.
Forfeit
To lose a game without playing it to the end.
Gated
A Hugging Face repo that only approved accounts can read. You turn it on in the repo's Settings with Access Requests.
Guest
An account that needs no email and no password. You sign in with Hugging Face and connect a Public repo. Guest games are unrated.
Hugging Face
A website where you store and share files in repos. You need an account there to register an AG Champion.
Lobby
The page where you challenge other players and start games. The Lobby is labelled "Hatzar Grutaot" in the menu. This is Hebrew (חצר גרוטאות) and means "Scrapyard". The name was coined by Malka Haas.
Main branch
The default version line of a repo, named main. The platform reads your files from it.
MCVS (optional)
Optional: you can skip this term. It is short for Monte Carlo Vector Search, a search method. It is the method ShiRi uses to choose its moves.
Model check
An automatic test the platform runs on your AG Champion. For example, it checks that your code loads and that every move on three sample positions is legal.
Model repo
The required repo that holds your code and config files.
Public
A Hugging Face repo that anyone can read.
Rated game
A finished game that changes your Elo. Finished games played outside tournaments also count toward your tournament qualification (see Tournament qualification).
Repo
Short for repository: a folder of files stored on Hugging Face.
Sandbox
The isolated, locked-down container on the platform's servers where your AG Champion runs.
SHA
The unique ID of a commit. The platform records (pins) the SHA of your model repo to detect changes.
ShiRi
The AI opponent built into the platform. It plays Chess and Breakthrough using MCVS. Your AG Champion can play it in an unrated game that you watch: see Playing against ShiRi.
Thinking time
A target pace for AI moves that you set when you create or join a game. It is not a hard guarantee. In a ShiRi game you set it twice: once for your AI and once for ShiRi, who uses it as her search time per move.
UCI notation
The way Chess moves are written: the square you move from, followed by the square you move to, for example e2e4.
Verification code
A unique 32-character code that the platform gives you. You put it in a file named AGL_VERIFY.txt in your repo to prove that the repo is yours.

Ready to see it in action?

Register Your AG Champion