ZeroSnake Arena

Your snake bot vs. everyone else's. A slither.io-style arena where every snake is a program. Write a JavaScript or TypeScript bot with Claude, another coding agent or by hand, deploy it with npx zerosnake deploy, and it plays everyone else's bots in rooms that run around the clock. It earns a rating, and recent deaths come with a replay and a trace of what your bot saw.

Play at zerosnake.dev: watch the arena, read the docs, see the leaderboard.

npx zerosnake init my-snake   # starter bot, CLAUDE.md, AGENTS.md and skills
cd my-snake
npx zerosnake sim             # your snake vs the house bots, in your browser
npx zerosnake test            # the same checks the server runs
npx zerosnake login           # once, with GitHub
npx zerosnake deploy          # it joins the arena when the checks pass

Needs Node.js 24+. The CLI is zerosnake on npm. Full walkthrough: Getting started. To work on the CLI or the template themselves, run them from a checkout: Working from a checkout.

How it works

• Engine (packages/engine): deterministic TypeScript at 10 ticks per second with a seeded RNG and its own math, so the same seed and bots give the same match. A replay is the seed plus every bot's actions.
• Sandbox (packages/sandbox): Workers can't eval, so each bot runs in its own QuickJS context compiled to WebAssembly, with no I/O and no clock. Bundles are instrumented to count work, so the per-tick budget is the same on a laptop and on the server. The same package runs in the CLI, the deploy checks and the arena.
• Arena (apps/arena): each room is a Durable Object that simulates in batches; a matchmaker fills rooms, and spectators get per-tick deltas over WebSocket.
• Rating (packages/rating): points per minute alive over a version's last 200 lives (a life lasts until the snake dies, up to 24 hours), ranked by the low end of its interval, so a lucky streak can't beat a steady record.
• Site (apps/web): TanStack Start on Workers, with D1, R2 and GitHub sign-in.

Rules, the bot API, limits and rating are documented in docs/; every number there links to the code it comes from. The product spec is SPEC.md, tasks are in Issues and Milestones, and contributing is in CONTRIBUTING.md.

Development

Requires Node 24+ and pnpm (corepack enable).

pnpm install
pnpm test        # vitest across all workspaces
pnpm typecheck
pnpm lint        # biome; `pnpm format` to fix

Path	What
packages/engine	deterministic simulation
packages/sandbox	QuickJS bot runner
packages/sdk	bot types and helpers
packages/renderer	three.js renderer
packages/cli	npx zerosnake
bots/house	built-in bots
apps/web	site (TanStack Start on Workers)
apps/arena	arena worker (matchmaker, rooms, checks)
template/	starter repo for bot authors

Operations

One public environment for now, deployed from main. It sits at the permanent addresses (the published CLI has https://zerosnake.dev built in) but its config and resources are still named staging (env.staging, zerosnake-*-staging). A separate staging can come later (below).

Environment	Site	Arena API
public (env.staging)	zerosnake.dev (www. redirects to it, see below)	api.zerosnake.dev
separate staging (later)	staging.zerosnake.dev	staging-api.zerosnake.dev

All of them are in the zerosnake.dev zone (Cloudflare account "Surnin Synergy").

Public environment

Cloudflare account "Surnin Synergy". Config lives in the env.staging blocks of apps/web/wrangler.jsonc and apps/arena/wrangler.jsonc.

Worker	URL	Health
zerosnake-web-staging	https://zerosnake.dev	/api/health
zerosnake-arena-staging	https://api.zerosnake.dev	/health (pings DO)

Resources: D1 zerosnake-staging (shared by both Workers), KV zerosnake-staging-auth (web only), R2 zerosnake-staging-{bundles,sources,replays,traces}, queues zerosnake-staging-checks and zerosnake-staging-checks-dlq.

Auth storage: web sessions (Better Auth) live in the KV namespace zerosnake-staging-auth, bound as AUTH_KV to the web Worker only, never to arena: the arena runs untrusted bot code and shares the D1, so no session token is kept there (D1 has only hashes of revoked ones). CLI tokens are in D1 as SHA-256 hashes, GitHub OAuth tokens encrypted. The namespace was made once with pnpm exec wrangler kv namespace create zerosnake-staging-auth (from apps/web); its id is in env.staging.kv_namespaces of apps/web/wrangler.jsonc.

Deploys happen automatically: .github/workflows/deploy-staging.yml runs after CI passes on main (or via "Run workflow"). It builds web, deploys arena (web binds to its Durable Objects), applies D1 migrations, deploys the built web, then curls both health endpoints. The old web runs against the new schema for a short while, so migrations must not break the code they replace (empty a table before dropping it in a later release). It skips while the repo secrets CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are unset. The token needs the account permissions listed at the top of the workflow plus the zone zerosnake.dev (Workers Routes: Edit, DNS: Edit) for the custom domains. Each deploy makes a Worker's custom domains exactly those in its routes (wrangler replaces the set), so a hostname removed from wrangler.jsonc is detached.

Manual deploy (needs wrangler login with access to the account):

pnpm --filter @zerosnake/arena deploy:staging
pnpm --filter @zerosnake/web deploy:staging

Migrations: generate with pnpm db:generate in apps/web, commit the SQL, and CI applies it. To apply by hand:

cd apps/web && pnpm exec wrangler d1 migrations apply DB --env staging --remote

Trace retention: life traces (R2 zerosnake-staging-traces, apps/web/src/shared/trace.ts) are kept 7 days. Add the lifecycle rule once per bucket:

cd apps/arena && pnpm exec wrangler r2 bucket lifecycle add zerosnake-staging-traces expire-traces --expire-days 7

Without it the arena's cron (every 30 minutes, apps/arena/src/traces.ts) deletes them anyway, up to 10,000 per run; the rule just makes that a no-op.

Replay retention: room replays (R2 zerosnake-staging-replays, apps/web/src/shared/replay.ts) are kept 2 days, plus the chunks of pinned lives: the 100 best lives of all time and the 5 best of each of the top 20 leaderboard bots, each pinned until 2 days after the last run that picked it. No lifecycle rule can express the exceptions, so don't add one: the site's cron (every 30 minutes, apps/web/src/server/replays.ts) deletes the rest, oldest chunks of each room first, at most 50,000 chunks, 300 list calls and 60 s per run (enough for a few hundred accelerated rooms at ~5,800 chunks a day each), and marks the lives that died in them (lives.replay_expired_at, migration 0012_replay_retention). If it can't settle the pinned lives, or they shrank to less than half of the last run's, it deletes nothing. Each run logs replays.swept and writes the replays.swept metric: outcome no_pins or failed, or more run after run, means replays are piling up (alerts and recovery in apps/web/README.md).

Admins, rate limits, metrics and alerts: see "Operations" in apps/web/README.md. Set ADMIN_USER_IDS / ADMIN_GITHUB_IDS in env.staging.vars for /admin. The rate limit and Analytics Engine bindings need nothing created beforehand.

Secrets (web): BETTER_AUTH_SECRET, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, set once with pnpm exec wrangler secret put <NAME> --env staging from apps/web. The GitHub App uses homepage https://zerosnake.dev and callback https://zerosnake.dev/api/auth/callback/github.

www

www.zerosnake.dev is a second custom domain of the site Worker, which redirects it to the apex (301, path and query kept; apps/web/src/server/www.ts). Static assets (/robots.txt, /sitemap.xml, /og.jpg, /assets/*, the favicon) are served before the Worker runs, so on www they would answer 200 instead. Until the zone has this Redirect Rule, only pages redirect: dashboard → zone zerosnake.dev → Rules → Redirect Rules → Create rule: when the hostname equals www.zerosnake.dev, dynamic redirect to concat("https://zerosnake.dev", http.request.uri.path), status 301, Preserve query string on (or the "Redirect from WWW to root" template). The Worker redirect stays as the fallback. run_worker_first would cover it too, but would run the Worker for every asset on the apex.

Separate staging (later)

Not set up yet. It would get its own wrangler.jsonc env with its own resources, secrets and GitHub App, on staging.zerosnake.dev (site) and staging-api.zerosnake.dev (arena). SITE_URL (apps/web/src/site.ts), DEFAULT_URL (packages/cli/src/remote/config.ts), robots.txt and sitemap.xml stay on zerosnake.dev: they describe the public site.