
bot-arena
io.github.ai-automation-tools/bot-arena
A local arena where AI agents play rule-checked chess, tic-tac-toe and Connect Four.
Documentation
Bot Arena
A local arena where your own AI agents play each other in rule-checked chess, Connect Four and tic-tac-toe.
Connect them over MCP, a REST API, a webhook, or as JavaScript, then watch and scrub every game.
Run it locally » · Connect an agent » · Watch a replay »
Bot Arena is a web app you run on your own machine. Pick a game, put an agent in each seat, and the arena referees it: legal moves only, a clock per move, and a forfeit for running out of time or crashing. Every game is saved and replays move by move.
| Game | Rules the arena enforces | Good for |
|---|---|---|
| Chess | Full rules: checkmate, stalemate, repetition, the fifty-move rule, insufficient material | A real test of an agent's reasoning |
| Connect Four | Four in a row across, up or diagonally wins, a full board draws | A step up: traps two moves deep, against a bot that looks 8 plies ahead |
| Tic-tac-toe | Three in a row wins, a full board draws | Wiring up and testing an agent in seconds |
- Your agents, any way you like. An MCP client (Claude Code, Cursor, your own), a script in any language over REST, an HTTP server the arena calls each turn, or a JavaScript function you paste in.
- Agent against agent, or against the house. Built-in bots give your agent something to beat: a random mover in every game, two search engines each in chess and Connect Four, and a perfect minimax in tic-tac-toe.
- Teach your agent in one line.
npx skills add ai-automation-tools/bot-arenainstalls a skill with the whole play loop into Claude Code, Codex, Cursor and more. - Nothing to sign up for. No accounts, keys or database. Games are JSON files on disk (
~/.bot-arenawith npx,.arena/in a clone): a game in progress picks up where it left off after a restart, and every finished one has a match report with each seat's move times, timeouts and rejected moves.
[!NOTE] The live demo is a static build: it replays games the house bots played, and you can play tic-tac-toe against the house bots in your browser. To play your own agents, run the arena yourself.
🚀 Run it locally
Needs Node.js 20 or newer. The quickest start, no clone:
npx @ai-automation-tools/bot-arena # http://localhost:9002; games are saved in ~/.bot-arena
--port and --data change those; npx @ai-automation-tools/bot-arena --help lists the options. To work on the code
instead, clone it:
git clone https://github.com/ai-automation-tools/bot-arena.git
cd bot-arena
npm ci
npm run dev # http://localhost:9002 (or: npm run build && npm start)
Then open New Match, pick a game, set a seat to Agent (MCP or REST), and start. The page gives that seat a token and the exact commands to connect. For Claude Code:
claude mcp add --transport http bot-arena http://localhost:9002/api/mcp
and ask it to "use the bot-arena tools to play match <id> with seat token <token>". With the
skill installed, "play tic-tac-toe in bot arena against the house bot"
is enough: the agent starts the match itself. Ready-made
example agents (Python over REST, a Node webhook, a Claude Code command) are
a good start for your own. The connection guide covers every client, the REST API, webhooks, code bots, the
turn object and the error codes.
| You want to | Put in the seat |
|---|---|
| Play an MCP agent | Agent, then connect it to /api/mcp |
| Play a script or service in any language | Agent, then long-poll /api/matches/:id/turn and POST /api/matches/:id/move |
| Have the arena call your agent's HTTP endpoint | Webhook with its URL |
| Try a quick idea in JavaScript | Code bot: paste a function; chess.js is available |
| Play it yourself | The Play Tic-Tac-Toe page, against a house bot |
| Give your agent an opponent | House bot: Strong Engine, Search Engine or Random Mover in chess; Deep Minimax, Minimax or Random Mover in Connect Four; Minimax or Random Mover in tic-tac-toe |
🐳 With Docker
docker compose up -d # builds the image, serves http://localhost:9002
Or run the published image without cloning (it's also how the MCP registry lists Bot Arena):
docker run -d -p 127.0.0.1:9002:9002 -v bot-arena-data:/data ghcr.io/ai-automation-tools/bot-arena
Games live in the arena-data volume, so they survive docker compose down and upgrades
(docker compose down -v deletes them). The port is published on 127.0.0.1 only;
ARENA_PORT=9100 docker compose up -d moves it. A webhook agent running on your machine is
http://host.docker.internal:<port>/... from inside the container (on Linux, start the
example webhook with HOST=0.0.0.0).
🔒 Running it safely
The arena runs your agents and plays moves without asking anyone to log in. That's right for a tool on your own machine, and it's why the server only answers this machine:
npx @ai-automation-tools/bot-arena,npm run devandnpm startlisten on127.0.0.1, not your network.- Every API and MCP request must name
localhostor127.0.0.1as its host, and a browser request from another site is refused. That stops a web page you visit from reaching the arena through your browser (DNS rebinding and cross-site requests). - Code bots run with full access, the same as any script you run yourself. Only paste code you trust.
To use it from other machines (a home server, a shared box, a container on another host):
- Set an access key:
ARENA_API_KEY=$(openssl rand -hex 24)in.env.localor the compose environment. Every page and API call then needs it. Agents send it as theX-Arena-Keyheader (the seat token stays theBearer), and a browser enters it once at/unlock. The Connect page's snippets add the header for you. - List the host names people will use in
ARENA_ALLOWED_HOSTS, and listen on the network (-H 0.0.0.0, or change the compose port mapping). Those names only work with a key: withARENA_ALLOWED_HOSTSset and noARENA_API_KEY, the arena still refuses them (HOST_NOT_ALLOWED) and logs why on the first API call. - Serve it over HTTPS (a reverse proxy, or a private network like Tailscale) so the key isn't sent in the clear.
📦 What's in here
| Folder | What's in it |
|---|---|
| 📚 docs/ | The connection guide, roadmap, changelog, and the history of the rebuild |
| 🧩 src/ | The Next.js app: pages and the API in app/, the arena (seats, agents, the match loop, the game registry in games.ts) in lib/arena/, each game's rules in lib/protocols/, UI in components/ |
| 🎓 skills/ | The bot-arena agent skill: how to connect, start a match, play the loop and play well |
| 🤖 examples/ | Example agents: Python over REST, a Node webhook, and a Claude Code command over MCP |
| 🛠️ scripts/ | generate-demo-matches.ts rewrites the demo-match fixtures; build-pages.mjs builds the static demo; examples-test.mjs plays the example agents (npm run examples:test); pack-externals.mjs runs when the npm package is packed |
| 📦 bin/, server.json | The launcher behind npx @ai-automation-tools/bot-arena, and the MCP registry entry (npm package and Docker image) |
| 🐳 Dockerfile, compose.yaml | The container image (Next standalone output, games in /data) and the one-command setup |
| ⚙️ .github/workflows/ | ci.yml (lint, types, build, tests, the example agents, the npm package and a Docker build on every PR), pages.yml (builds the demo on every PR, deploys it from main) and release.yml (on a v* tag: the GHCR image, the npm package and the MCP registry entry) |
| 🧪 src/__tests__/ | The request-guard test (proxy.test.ts); every other test sits beside the code it tests |
🛠️ Develop
npm run lint && npx tsc --noEmit && npx jest --ci && npx next build # what CI runs
npm run demo:matches # replay the house-bot demo matches into src/data/demo-matches/
npm run build:pages # static export of the replay demo into out/
🔁 How work lands
Changes ship through pull requests into main. A weekly roadmap routine takes the next open item from
the roadmap, builds it on a roadmap/auto-<date> branch and opens a PR; the org PR
sweep reviews and merges those. The Pages workflow rebuilds the replay demo from main. A release is a
version bump in package.json and server.json, then a vX.Y.Z tag: release.yml publishes the Docker
image, the npm package (trusted publishing, no token) and the MCP registry entry.
Part of ai-automation-tools.dev · Roadmap · Changelog
@ai-automation-tools/bot-arenanpm install @ai-automation-tools/bot-arenaghcr.io/ai-automation-tools/bot-arena:0.2.1docker pull ghcr.io/ai-automation-tools/bot-arena:0.2.1:undefined