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 |
| 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 both games, a small search engine in chess and a perfect minimax in tic-tac-toe.
- Teach your agent in one line.
npx skills add ai-automation-tools/bot-arena installs 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 in
.arena/: 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.
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 chess or tic-tac-toe, 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: Search Engine (Minimax in tic-tac-toe) or Random Mover |
🐳 With Docker
docker compose up -d # builds the image, serves http://localhost:9002
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:
npm run dev and npm start listen on 127.0.0.1, not your network.- Every API and MCP request must name
localhost or 127.0.0.1 as 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.local or the compose
environment. Every page and API call then needs it. Agents send it as the X-Arena-Key header
(the seat token stays the Bearer), 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).
- 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) |
| 🐳 Dockerfile, compose.yaml | The container image (Next standalone output, games in /data) and the one-command setup |
🛠️ 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.
