{"id":50737596,"url":"https://github.com/pocc/bga_stockfish","last_synced_at":"2026-06-10T15:01:58.138Z","repository":{"id":358533398,"uuid":"1241269533","full_name":"pocc/bga_stockfish","owner":"pocc","description":"Always-on chess opponent on Board Game Arena. Cloudflare Workers + Durable Objects.","archived":false,"fork":false,"pushed_at":"2026-06-01T22:35:10.000Z","size":6355,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T23:24:05.190Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pocc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-17T07:01:24.000Z","updated_at":"2026-06-01T22:35:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pocc/bga_stockfish","commit_stats":null,"previous_names":["pocc/bga_stockfish"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/pocc/bga_stockfish","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pocc%2Fbga_stockfish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pocc%2Fbga_stockfish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pocc%2Fbga_stockfish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pocc%2Fbga_stockfish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pocc","download_url":"https://codeload.github.com/pocc/bga_stockfish/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pocc%2Fbga_stockfish/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34157453,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-10T15:01:57.273Z","updated_at":"2026-06-10T15:01:58.126Z","avatar_url":"https://github.com/pocc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BGA Stockfish\n\nAn academic project: a chess bot that plays games on\n[boardgamearena.com](https://boardgamearena.com), backed by a Cloudflare\nWorker that races several public chess engines for each move.\n\nThe bot account is **`bot_stockfish`**. A live status dashboard runs at\n[https://stockfish.ross.gg/](https://stockfish.ross.gg/).\n\n## Two halves\n\n1. **`worker/`** - the production system. A Cloudflare Worker plus Durable\n   Objects that hosts both the chess engine and the autonomous BGA bot\n   driver. It logs into BGA, keeps friendly invites open, accepts games,\n   plays moves, and answers chat, all on a self-scheduled 5-second tick.\n2. **`bga/`** - a TypeScript BGA client library and a collection of\n   Playwright recon/one-shot scripts, reverse-engineered from real games.\n   The worker embeds its own copy of the client; the `bga/` scripts are kept\n   for debugging and endpoint discovery.\n\n## Bot behavior (the rules)\n\n- **Friendly games only.** The bot fails closed: it will not play a table\n  unless BGA carries a positive friendly/unranked signal. It never plays a\n  ranked or ELO-affecting game.\n- **Auto-accepts** both realtime and turn-based friendly invites, and keeps\n  one open invite of each kind in the lobby.\n- **Never accepts a draw.** A draw records as 0.5/0.5 and skews the win/loss\n  stats, so the bot declines every draw offer and tells the opponent they\n  can resign or propose a collective abandon instead.\n- **Accepts a collective-abandon proposal** automatically (it ends the game\n  with no score, so it does not skew stats).\n- **Opponent chat is untrusted.** The bot replies with a fixed canned line\n  to anything that is not an exact difficulty keyword, so chat is data and\n  never instructions.\n\nSee [AGENTS.md](AGENTS.md) for the full operational reference and\n[docs/](docs/) for architecture and security notes.\n\n## Quick start\n\nEngine probe (needs the admin secret on the public route):\n\n```bash\ncurl -X POST https://stockfish.ross.gg/bestmove \\\n  -H 'content-type: application/json' \\\n  -H \"x-admin-secret: $BOT_ADMIN_SECRET\" \\\n  -d '{\"fen\":\"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1\",\"depth\":12}'\n```\n\nBot status (public, drives the dashboard):\n\n```bash\ncurl https://stockfish.ross.gg/bot/status\n```\n\n## Develop \u0026 deploy\n\n```bash\ncd worker\nnpm install --ignore-scripts   # sharp's optional postinstall fails on Node 25\nnpm run dev                    # local wrangler dev server\nnpm run test:run               # vitest\nnpx wrangler deploy            # runs tests first via predeploy\n```\n\nWorker secrets (`wrangler secret put`): `BGA_USERNAME`, `BGA_PASSWORD`,\n`BOT_ADMIN_SECRET`, and the optional `RAPIDAPI_STOCKFISH_KEY`. Deploy\ncredentials live in `worker/.env.local` (gitignored). Full details in\n[AGENTS.md](AGENTS.md) and [docs/security.md](docs/security.md).\n\n## Documentation map\n\n| File | What it covers |\n| --- | --- |\n| [AGENTS.md](AGENTS.md) | Operational reference: endpoints, gotchas, engine chain, deploy. |\n| [docs/architecture.md](docs/architecture.md) | How the worker, Durable Objects, engine race, and bot loop fit together. |\n| [docs/security.md](docs/security.md) | Threat model, admin gating, friendly-only enforcement, secrets, chat injection. |\n| [bga/docs/chess-api.md](bga/docs/chess-api.md) | Reverse-engineered BGA chess endpoints. |\n| [bga/docs/bga-api.md](bga/docs/bga-api.md) | General BGA lobby/auth endpoints. |\n| [bga/docs/endpoints-observed.md](bga/docs/endpoints-observed.md) | Empirical response shapes and quirks. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpocc%2Fbga_stockfish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpocc%2Fbga_stockfish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpocc%2Fbga_stockfish/lists"}