Game Table platform: a touchscreen board lying flat on a table, players' phones as private decks, a Linux Table Host that runs the games, and a cloud service at games.skylar.technology that enrolls tables, collects metrics and logs, and brokers remote players, with its console for admins at games-console.skylar.technology.
This repository implements phases 1a, 1b and 1c of the Game Table — Concept & Architecture document: lobby, seats, game selection, the game runtime with replayable logs, AI-only simulation, the board control API, pause on a lost service connection, the console, a table PC kit, remote play over WebRTC, automated tests, and four playable games with their own board and phone UIs and rules for players: Roulette, Pachisi, Hold'em and Coin Flip. More games can come from other repositories, private ones included (Extra-game repositories below); klaushofrichter/extra-games is the public example, with Chess, Liar's Dice, Backgammon, Mexican Train and Last Card. Decisions are recorded in docs/decisions.md; the words for the platform's parts (board, deck, seat plate, watcher, sling, console, the seat names…) are in the glossary. New here? The cookbook says what to ask an AI agent to play, build a game, keep games private, host a game service or ship a change, and the architecture overview shows how a game works with the platform.
Requires Node.js 26 (TypeScript runs natively, no build step).
npm install
npm test # the automated tests: lobby, cloud, sign-in and each game's rules
TABLE_KEY=dev npm run hostOpen http://localhost:8080/board/ on the table PC (full screen, 1920 × 1080 or 4K). Phones on the same WiFi scan the QR code, or type the URL shown under it. When no seat is free, the QR panel and the phone say so, and + AI player and Invite are greyed out (D-129): choose more seats on the board, or remove a player. During a game the lobby's QR panel is not shown: Settings › Show join code shows the QR code and the address, so a phone that lost its seat can rejoin (D-130).
On one machine with Docker, without the cloud service, DNS or HTTPS: docs/runbooks/local-docker.md,
written for people and for coding agents (deploy/local/). It needs no cloud service, also not for games from other
repositories, private ones included (cloned, runbook Part B). On a Windows PC with Docker Desktop, in PowerShell:
powershell -ExecutionPolicy Bypass -File deploy\local\setup.ps1 -Start (runbook, On a Windows PC).
For development with a local cloud service: docker compose -f deploy/docker-compose.yml up --build starts a cloud service and a table host. The table shows a 6-character pairing code; approve it in the console at http://localhost:8081/admin (in local development it asks for ADMIN_TOKEN: change-me-dev-admin-token unless you set your own), or with
curl -X POST -H "Authorization: Bearer ${ADMIN_TOKEN:-change-me-dev-admin-token}" http://localhost:8081/admin/api/tables/pair/<CODE>Or skip the pairing code: create an access code in the console (Access codes) and start with
TABLE_CODE=ABCD-EFGH docker compose …, or type it on the board under Advanced (Access codes below).
scripts/local-table.sh runs a Table Host on a Mac or a Linux computer against the live service at games.skylar.technology (Node 26 needed), without containers. It first updates the checkout to the latest main; --branch production or --branch experiment/card-sling runs another branch, and --no-pull runs the checkout as it is. CLOUD_URL= scripts/local-table.sh --extra ../extra-games adds the games of another checkout as they are (e.g. a branch of extra-games not released yet). It opens the board in the browser, puts the computer's WiFi (default-route) address in the QR code, and keeps the table's identity and API key in ~/.gametable-local (or ~/.gametable-mac, where an older table lives), so a restart is the same table. The first time, the board shows a pairing code: approve it in the console at https://games-console.skylar.technology. Allow node to accept incoming connections when the system asks, or phones cannot join. scripts/local-table.sh --code ABCD-EFGH uses an access code from the console instead, so no approval is needed. CLOUD_URL= scripts/local-table.sh (or --offline) runs it without the service, and scripts/local-table.sh --offline --all-games plays every game checked out beside games-service (each folder there with a games/ folder, brought up to date unless --no-pull) without the service or the console (D-247). The board then says once that it is a local table: without the service no remote player can join, and its games run from the clones on this computer, named with their branches (D-251).
The board can show on another screen on the same network, such as an iPad, a TV or a second computer, while the table runs on its computer (D-190). On the board, open the settings (gear) › Board on another screen…: it shows a QR code and a link. Open it on the other screen (scan it with the iPad's camera, or type the link into its browser), and the board moves there; the table's own window says "The board moved to another screen" and offers to take it back.
- Same network only: the link works from private addresses (home WiFi), never from the internet, and not through a remote player's invite.
- The screen is remembered (a cookie derived from the table key), so it shows the board again after a reload or a restart. The link carries the table key: whoever opens it can run the table, so show it only on your own screens.
- One board at a time (D-132): opening it on another screen moves it, and Show the board here moves it back.
- Sound: browsers play sound only after the page has been touched, except the table's own kiosk browser. Until then a board with sound on shows Tap to turn the sound on at the top; any tap or click on the board does it (D-195).
- No configuration and no extra port: the table already listens on the network for the phones.
ALLOW_REMOTE_BOARD=1(every device on the network gets the board) is for Docker setups and not needed for this.
| Path | What it is |
|---|---|
packages/protocol |
Message envelope, manifest schema (zod), seat layouts and edges, lobby types |
packages/sdk |
defineGame, seeded RNG, the GameContext games receive, count() and list() for end-of-game texts, cards (cards.ts) |
apps/table-host/src |
HTTP + WebSocket server, lobby (table.ts), game runtime and replay (runtime.ts), game logs (logs.ts, game-log.ts, and log-format.md, the README in every log), move lists and the Game Viewer's endpoints (moves.ts, history.ts), simulation, cloud link, remote-play gateway (remote.ts, WebRTC), the game loader (games.ts), AI players with their time limits and worker thread (ai.ts, ai-worker.ts, D-112), the statistics window's data (stats.ts, D-140) |
apps/table-host/public |
Board and deck pages (plain HTML/CSS/JS), the board's Game Viewer (board/viewer.js) and statistics window (board/stats.js), the board with one player's deck beside it (board/play.html, D-175); shared/ has the board kit, the sling (sling.js, D-189), the rules renderer (markdown.js) and the players' terms of service (terms.md) |
apps/cloud/src |
Cloud service: pairing, access codes (access-codes.ts), heartbeat, metrics, log upload/download, download tokens, invites and WebRTC signaling; its persistent state (store.ts, SQLite), Google sign-in for admins (auth.ts), log metadata (log-meta.ts) |
apps/cloud/public |
The public website (/, site/, the terms of service at /terms), the console (/admin, on its own host when CONSOLE_URL is set) and the remote player's invite page (/i/CODE) with its service worker; the service also serves llms.txt, llms-full.txt and the developer guide and Docker runbook under /docs/ |
games/roulette |
European roulette, 1–6 players, simultaneous betting, three AI styles |
games/pachisi |
Ludo-style race with dice and captures, 2–4 players, two AI levels |
games/holdem |
Fixed-limit Texas Hold'em, 2–8 players, private hole cards, side pots, two AI styles |
games/coin-flip |
Guess heads or tails, 1–8 players, simultaneous, AI, players can join mid-game, optional time limit, per-player statistics |
games/quartet |
Test game (hidden unless SHOW_TEST_GAMES=1): exactly 4 humans, no AI, sequential turns, ends if a player leaves |
games/card-sling |
Test game for the sling (hidden unless SHOW_TEST_GAMES=1): cards pushed off the phone fly onto a pile, 1–8 players, AI (D-189) |
apps/cloud/src/game-repos.ts, apps/table-host/src/extra-games.ts, packages/protocol/src/bundle.ts |
Extra-game repositories: fetching and packing on the service, installing on tables, the bundle format |
scripts/e2e/ |
Browser end-to-end checks (Playwright): run-all.sh runs them all, play.py per game, layout.py, admin.py for the portal and sign-in, codes.py for access codes and a service restart, remote.py for remote play, watch.py for watchers, extra.py for extra-game repositories, logs.py for game logs, viewer.py for the Game Viewer, and one check per lobby feature (seats, names, away phones, rejoining, exchanges, watchers, playing from the board, …; see run-all.sh); shared helpers in common.py |
scripts/game-log.ts |
Reads a game log zip from the command line: an overview, a range of moves, one move in full with the state before and after (D-120) |
scripts/check-game-versions.ts |
A game's calendar version must change when its folder does (D-127b); --fix sets it |
scripts/sync-secrets.sh |
Puts the values from your local .env into GitHub and the cluster, without printing them |
scripts/release-notes.sh, release.sh |
The release step of the deploy |
scripts/site-screenshots.py |
Takes the game screenshots for the public website (apps/cloud/public/site/) from a host running every public game |
scripts/soak.ts |
AI-only soak run over every game and player count |
scripts/local-table.sh |
A Table Host on this computer against the live service, from any branch (see above) |
scripts/package/ |
Packages for one computer: Windows installer, macOS .pkg, Linux .tar.gz, on the release local-table (install guides in docs/install/, D-256) |
scripts/windows/game-table.ps1 |
Windows 11: downloads the games (private ones by name) and the tools it needs, and starts a table without the service (runbook, D-255) |
docs/ |
Decision log; the glossary, the cookbook and the architecture overview; developers/ (the game developer guide); runbooks/ for running a table locally with Docker and for resetting and restoring the service's state |
tests/ |
Vitest suites that drive a real host through the board control API and fake decks |
deploy/ |
Dockerfiles, docker-compose, the local Docker setup (local/), the table PC kit |
.github/ |
The three workflows, Dependabot, the CodeQL gate and its accepted-findings list |
| Variable | Default | Meaning |
|---|---|---|
PORT |
8080 | HTTP and WebSocket port |
TABLE_NAME |
Game Table | Shown on the board and decks |
TABLE_KEY |
random per run | Key for the board control API (X-Table-Key) |
PUBLIC_URL |
http://<lan-ip>:<port> |
Base of the join URL in the QR code |
CLOUD_URL |
unset | Cloud service; unset = development mode without cloud |
TABLE_CODE (or --code) |
unset | An access code from the console (D-113): the table is approved without a pairing code. Wins over a code typed on the board |
REQUIRE_CLOUD |
0 | 1 blocks new games while the cloud is unreachable (production) |
GRACE_MS |
300000 | How long a disconnected phone keeps its seat in the lobby (DECK_GRACE_MS in apps/table-host/src/host.ts; a running game holds seats without a limit) |
AI_DELAY_MS |
800 | Pause before an AI player acts |
MAX_REMOTE_PLAYERS |
4 | Remote players and watchers together (D-168) |
ALLOW_REMOTE_BOARD |
0 | Serve the board to every client, not only loopback: for Docker setups, where the browser is outside the container's loopback (the local Docker setup sets it). Not needed for Board on another screen… |
ALLOW_NO_LOCAL_PLAYER |
0 | 1 starts with the developer setting Games without a player at the table on (D-118); Advanced on the board (hammer and wrench, D-128) turns it on or off until the next restart |
BOARD_DECK |
0 | 1 starts with the developer setting Play from the board on (D-175): one player at the table plays from a deck beside the board, without a phone; Advanced turns it on or off until the next restart |
BOARD_PACING |
1 | 0: AI players don't wait for the board's animations (D-141) |
LOG_SNAPSHOT_EVERY |
0 | A snapshot of the whole game state in the log every N moves (D-116); 0: only the final state |
SHOW_TEST_GAMES |
0 | 1 lists the test games (quartet, card-sling) in the game menu; the tests and run-all.sh turn it on |
DATA_DIR, GAMES_DIR |
<repo>/data, <repo>/games |
Logs, saves, the table's identity and a typed access code (table.json) and extra-game bundles (extra-games/); the built-in games |
Everything the board can do is available over HTTP on the table PC, for tests and for local AI agents (for example a Claude session) running simulations.
K="X-Table-Key: dev"; H=http://localhost:8080/api/v1
curl -s -H "$K" $H/state # lobby state
curl -s -H "$K" -X POST $H/join/new # new join code (the board's QR code changes)
curl -s -H "$K" $H/games # games, selectable + reasons
curl -s -H "$K" -X POST $H/ai -d '{}' # add an AI seat
curl -s -H "$K" -X POST $H/face -d '{"edge":"west"}' # turn the lobby to a side (the board's corner buttons)
curl -s -H "$K" -X POST $H/game/select -d '{"gameId":"coin-flip","settings":{"rounds":5}}'
curl -s -H "$K" -X POST $H/simulation -d '{"gameId":"coin-flip","players":4,"games":100,"seed":42}'
curl -s -H "$K" $H/logs/<id>.zip -o run.zip # JSONL game logs
curl -s -H "$K" "$H/history/<id>/1/moves?offset=0&limit=25" # a finished game's moves (D-120)Full list: GET /state, /join, /games, /version, /metrics, /game/board, /logs, /logs/{id}.zip, /history, /history/{id}, /history/{id}/{game}/moves, /history/{id}/{game}/moves/{n}, /history/{id}/{game}/lines/{line}, /history/{id}/{game}/statistics, /connections, /debug and POST /logs/{id}/verify, /join/new, /layout, /face, /rotate, /seats/move, /ai, /game/select, /game/settings, /game/prefs, /display, /rules, /game/start, /game/end, /game/close, /game/resume, /game/play-now, /game/skip-timer, /game/save, /simulation, /players/{id}/ai-options, /players/{id}/color, /invites, /remote, /cloud/code, /developer, /exchange, /watchers/{id}/play, GET /saves, /qr?text=URL, DELETE /players/{id}, /watchers/{id}, /exchange.
Remote players reach a subset over WebRTC (D-057): reads, except the join code, logs, saves, simulations, invites, the remote settings, QR codes, the access code and the developer settings; changes only /layout, /exchange, /game/select|start|end|close|play-now|skip-timer|settings, /players/{id}/color|ai-options and /watchers/{id}[/play]. With board control they may also read /history (the Game Viewer, D-120), never the zips themselves.
Decks speak JSON envelopes over /ws: system.hello {joinToken, name} or {sessionToken} (remote decks: {name}; the deck played from the board, on the table PC: {boardKey, name}, D-175), then lobby.ready {ready}, lobby.rename {name}, lobby.leave, game.intent {name, payload} and game.gesture (a sling gesture, at most 512 bytes, passed live to every board as game.gesture {seat, data}, D-189). The host answers with system.welcome {playerId, sessionToken}, lobby.state, game.view {seat, view, events, over, timers, now} (this seat only), system.ack | reject {reason} | error {message}, and system.removed {reason} when the player is removed. The board says system.hello {role: "board", key} and gets game.board instead of game.view.
The contract between games and the platform is docs/developers/game-development.md:
the folder, the manifest, every rules hook and its exact behaviour, what the platform does about players (joining,
phones going away, leaving, exchanging a player), AI players, the end-of-game summary and awards, the board and phone
UI modules with everything they receive, rules for players, logs and replay, versions, testing, and a game repository
of your own, with a checklist. klaushofrichter/extra-games is a complete example of games written against it in a repository of their own. It is written for people and for language models; llms.txt is its index
for LLMs, served at https://games.skylar.technology/llms.txt (and the whole guide at /llms-full.txt).
In short: a game is a folder with manifest.json, rules.ts (pure, deterministic functions on a JSON state:
setup, onIntent, view, boardView, isOver, optional onTimer, onSeatChanged, onSeatJoined,
canContinueWithout, ai, aiFallback, describe), optional board.js and deck.js UI modules
(mount(root, ctx) → { update(view, events, info), destroy(), whenIdle? }), how-to-play.md and assets/. The
platform owns the lobby, seats, names, colours, away and leaving players, exchanges, pauses, AI scheduling, logs and
replay; a game never reimplements them. Start from games/coin-flip.
Games can also come from other GitHub repositories, private ones included (D-097), for private games and early
releases. The repositories the service lists are in deploy/game-repos.json. The public example is klaushofrichter/extra-games: five
complete games, tested against this repository, with CI and browser checks; copy its layout for a repository of your
own.
- The list:
deploy/game-repos.jsonis baked into the cloud image, so these repositories are back after every restart (D-098); change it by PR. In the console they are marked deploy config. - Console, Game repositories: you can also add
owner/nameand a branch there (kept across restarts, D-114). The service fetches each repository'sgames/folder as one bundle and lists its games; Refresh fetches again (it also does every hour). A private repository needsGAME_REPO_TOKEN, a fine-grained token with Contents: read on it; with several private repositories the one token must cover each of them (D-110). - Per table: tick a repository when approving the table's pairing code, or later on its row. The table installs the games within 15 seconds, between games, and its board marks them extra. Remote players see them too: their board comes from the table.
- A game repository has a
games/folder like this one, and its rules import the SDK by name:import { defineGame } from "@game-table/sdk"(the host maps the name to its own SDK). How such a repository is laid out and tested against this one:docs/developers/game-development.md, A game repository of your own.
Ticking a repository trusts its code on that table PC (rules run in-process, D-035). The ticks, and repositories added in the console, are kept by the service across restarts (D-114). A table approved with an access code gets the repositories of the code's scope instead of ticks.
An access code approves a table at once, without a pairing code (D-113). Create one in the console under Access
codes: a label, a validity (one week, one month, one year or forever) and the games it brings (built-in only, all
repositories, or chosen ones). The console shows the code, like ABCD-EFGH, once; the service keeps only a hash.
- On the table:
TABLE_CODE=ABCD-EFGHin the environment (the table PC's.env),--code ABCD-EFGHon the command line (alsoscripts/local-table.sh --code …), or Access code in the board's Advanced window (the tools button), which has a keypad. A code given at start wins and can't be changed on the board. The board shows what the service said about it. - One table per code: the first table that uses a code keeps it; any other is refused (in use) and waits with its pairing code. Release frees a code for a new table, for example after reinstalling the PC, and disconnects the old one.
- Validity counts only for that first use. A table connected past its code's validity keeps working and is flagged in the console, to disconnect by hand if it should stop.
- Games: the code's choice decides the table's extra-game repositories (all includes ones added later); edit it on the code's row and the table follows within 15 seconds, between games.
- Revoke or Delete disconnects the code's table; Reconnect on the table's row still brings it back. Codes that ended more than a year ago disappear by themselves.
A remote player gets an invite link (https://games.skylar.technology/i/CODE) from the board (Invite remote player…), optionally with their name (?name=, D-155). Opening it asks for a name (filled in from the link), then connects the browser directly to the table over WebRTC; the service only relays the connection offer and answer. The browser shows the same board as the table, with the player's private deck beside it.
remote browser ──(1) /api/remote/ws: offer──▶ service ──(2) /api/tables/ws──▶ table host
◀──────────────(3) answer───────────── ◀──────────────────────
◀═════════(4) WebRTC data channel "gt": board/deck files, API, live sockets═════════▶
- Relays: a direct connection fails behind some networks, typically a phone's hotspot or cellular data (the carrier's NAT), and some hotel, office or school networks. With a Cloudflare TURN key (
CF_TURN_KEY_ID,CF_TURN_API_TOKEN) the service fetches short-lived relay credentials (a day, renewed after half) and hands them to both ends with each connection; WebRTC uses the relay only when the direct way fails (D-209). OtherwiseICE_SERVERS(JSON) sets STUN/TURN for both sides, and without either, Google's public STUN is used. Optional: without a relay, remote play works wherever a direct connection does. Setting it up, checking it and troubleshooting:docs/runbooks/remote-play-relays.md. - The table needs outbound UDP; the table PC kit uses host networking. In bridged Docker (the dev
docker-compose.yml) remote play only works with a TURN server. - The remote board turns so the remote player's own seat is at the bottom of their screen. On an east or west seat, Use the full width shows the board upright instead (their seat at the side), and Put my seat at the bottom turns it back; the choice stays in that browser (D-101).
POST /api/v1/remote {"boardControl": false}(or the checkbox in the invite dialog) makes the board read-only for remote players. It is one switch for all of them, and a remote board has control only while its browser has a player at the table (D-167).- Watchers (D-168): Watch only in the invite dialog (
POST /api/v1/invites {"watch": true}; during a game, and when the seats are full, the board's invite is for watching) brings someone who sees the board, takes no seat and has no deck. A remote player who is exchanged, leaves or is removed keeps watching too. Remote players and watchers together stay withinMAX_REMOTE_PLAYERS. The board shows an eye with their number while anyone watches: tap it for the list, Remove (DELETE /api/v1/watchers/{id}; their window closes and that invite can't bring them back) and, in the lobby, Let play (POST /api/v1/watchers/{id}/play). During a game, Settings › Players › a player's name offers each watcher as the one to take the seat. Watchers leave by closing their window. They are listed in the lobby state aswatchers.
Every game is logged for analysis (D-008, D-116): to find out why a game or an AI misbehaved, by reading the log yourself or handing it to Claude.
- On the table, as the game goes: every record is written to
DATA_DIR/logs/running/while the game runs. When the game ends, for whatever reason, the log is packed into one zip inDATA_DIR/logs/. A game the table stopped in the middle of (switched off, crashed) is packed at the next start, marked interrupted. Simulations are packed at the end of the run. - To the service: packed logs wait in a queue (
DATA_DIR/logs/outbox/) and are uploaded when the table is online, retried after every heartbeat until the service has them. - In the zip:
README.md(the format, for a reader who has only the zip),run.json(game and version, table, start and end, players, settings, how it ended, counts, verification),game-001.jsonl(every move, timer and seat change, with refusals, events, AI timing and errors thrown by the rules) andgame-001.state.json(the final state). A simulation has one pair of files per game.LOG_SNAPSHOT_EVERYadds state snapshots. - Verified: every game is replayed when it ends, and
run.jsonsays whether it reached the same state; the console flags logs that do not replay.POST /api/v1/logs/{id}/verifyreplays a stored log on the table. - The move list (D-120): each finished game's zip also has
game-001.moves.jsonl, every record as a readable row in the game's own words (itsdescribe), with player moves numbered from 1, refused ones too; timers, players joining or leaving and pauses are rows between them, and a silence of two minutes or more without a pause shows as a gap. Each row names its line ingame-001.jsonl. The log also records when the game stood still and why (pause/resume: the service lost, an AI over its time, a player away; Play now). See Moves inlog-format.md. - Game Viewer on the board (D-120): Game logs under Advanced (D-128) lists the finished games on this table
(not the one being played). A game opens as a table of its moves, a page at a time, with filters (a player, moves
only, problems), Move # to jump to a move, and a simulation's games one by one; a move opens in full with its
intent, events, AI timing, the state before and after, and a reference to copy such as
20261016044059-pachisi-491f #54, so a developer can tell Claude exactly where to look. Remote players with board control can open it too. Simulations and older logs get their move list built when opened. - For developers and LLMs:
node scripts/game-log.ts <zip>reads a log without a table:info,moves 40-45,move 43(in full, with the state before and after),state 43 [--before],line 17;--jsonfor scripts,--games ../my-games/gamesfor games from other repositories (states and descriptions need the game's rules in the version the log was written with). - Console: Game logs lists them with their metadata and filters by game, table, date and kind. A download token
can be limited the same way (game, table, from and to), so one link gives a pipeline or a Claude session exactly
the logs it should read:
GET /dl/<token>lists them,GET /dl/<token>/<id>.zipfetches one.
In the cluster these come from the games-oauth Secret (created by scripts/sync-secrets.sh from your .env) and the Deployment.
| Variable | Meaning |
|---|---|
PUBLIC_URL |
https://games.skylar.technology; an https URL requires Google sign-in |
CONSOLE_URL |
The console's own host: https://games-console.skylar.technology in production (D-204, D-205); optional elsewhere. The console, sign-in and the session cookie then live only there, and PUBLIC_URL/admin sends people there; pages a table serves on PUBLIC_URL (remote play) can't use an admin's session. Its DNS record, ingress host and certificate, and the redirect URI in the Google client, must exist first. Unset: one host serves both |
DATA_DIR |
Where the state is kept (D-114): state.db (SQLite), snapshots/state.db (hourly and at shutdown) and logs/. In the cluster the PVC games-cloud-data at /data. Unset = memory only, lost at restart. A RESTORE_FROM_SNAPSHOT file there makes the next start use the snapshot |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET |
The service's own OAuth client, in Google Cloud project skylar-technology |
GOOGLE_REDIRECT_URI |
Exactly CONSOLE_URL/auth/google/callback (in production https://games-console.skylar.technology/auth/google/callback), or PUBLIC_URL/auth/google/callback without CONSOLE_URL; the service refuses to start otherwise. The Google client lists the same address as an Authorised redirect URI |
ALLOWED_EMAILS |
Comma-separated admin allow-list, checked at sign-in and on every request |
COOKIE_SECRET |
Signs the session cookie (openssl rand -hex 32, at least 32 characters). Replace it and restart to end every session |
ADMIN_TOKEN |
Optional bearer token for scripts (Authorization: Bearer …, at least 16 characters), on either host; in local development it is the portal sign-in |
TRUST_PROXY |
1 = trust X-Forwarded-For from loopback and the k3s pod/service networks, or a CIDR list |
PORT |
HTTP port (default 8081) |
MAX_REPLICAS |
Must be 1 (set by the cluster manifest); the service warns at start otherwise, since one process owns the database and the tables' sockets |
LOG_RETENTION_DAYS, ICE_SERVERS |
Log retention (default 90); STUN/TURN for remote play |
CF_TURN_KEY_ID, CF_TURN_API_TOKEN |
Optional, both or neither: a Cloudflare TURN key (Cloudflare dashboard, Realtime › TURN Server). Remote players behind a phone's hotspot or a strict network get a relay; the service asks Cloudflare for credentials that expire after a day, and the key stays with the service (D-209). scripts/sync-secrets.sh carries them into games-oauth |
DATA_LIMIT_MB, LOG_STORAGE_MB |
The service's storage budget in DATA_DIR (default 1024, the PVC's size) and the cap on game logs within it (default 256). The budget is counted from the service's own files, since a local-path volume has no quota; the oldest logs make way before free space in it drops below 15 % (at least 100 MB), and a log that can't fit is refused (the table keeps its copy). The console's Overview shows the use |
GAME_REPO_TOKEN |
Read token for private extra-game repositories (D-097) |
GAME_REPOS_FILE, GAME_REPOS |
The deploy-time repository list (default deploy/game-repos.json; none turns it off), and more repositories (owner/name@ref, comma-separated) for local development (D-098) |
PREVIEW_BANNER |
0 removes the PREVIEW / DRAFT sash from the public website's top right corner; it shows by default while the service is not live (D-177) |
APP_VERSION |
Stamped into the image by the deploy (YYYY.MM.DD.N); /health ({status, version}, on the Table Host also protocol) reports it; main for main builds, dev when unset |
The service keeps its state on the PVC games-cloud-data at /data (D-114; DATA_DIR above), within a 1 GiB budget.
Single records are removed in the console (D-115):
- Tables: Disconnect, then Delete removes a table for good and frees its access code, optionally with its logs. If that PC connects again, it shows a new pairing code.
- Game logs: Delete on a log, or Delete all simulation logs. Retention (90 days) and the budget remove old ones by themselves.
- Download tokens: listed by label and expiry (never the token itself) with Revoke.
- Access codes and console-added repositories: Delete and Remove on their rows.
Everything at once, and going back to a backup, are runbooks for someone with cluster access:
docs/runbooks/cloud-state-reset.md: empty the state and start over.docs/runbooks/cloud-state-restore.md: recover from the hourly snapshot (usually automatic), or restore the volume from Velero's daily backup (30 days).
Same shape as every service on the cluster:
feature branch → PR → main → (PR) → production → deploy
| Workflow | Trigger | Does |
|---|---|---|
production-checks.yml |
PR to main or production |
test (game versions, tests, typecheck, npm audit --audit-level=high, both images built and run non-root), e2e (all browser checks and the local Docker runbook), codeql (fails on any finding not in .github/codeql-accepted.tsv) |
build-push.yml |
push to main |
tests and typecheck, then both images as :main, and nothing else |
deploy-production.yml |
push to production |
on the in-cluster runner: calendar version, images as :<sha>, :v<version>, :latest, the cluster repository's manifest updated (push, then apply), rollout, smoke test until /health serves the new version, then a GitHub release with what the deploy verified |
main is built but never deployed. Releases are versioned YYYY.MM.DD.N (America/Chicago) at deploy time; nothing in the sources carries a version. Curated release notes go under ## [Unreleased] in CHANGELOG.md.
npm test # rules, fuzzing, lobby, concurrency, API limits, platform, pause, cloud, sign-in, access codes, the persistent store, remote play, extra-game repositories, rules for players, seat names, SDK texts, game logs (Vitest)
npm run typecheck # tsconfig.check.json: apps, packages, games, tests, scripts
node scripts/soak.ts 100 # 100 AI-only games per game and player count
scripts/e2e/run-all.sh out/ # every browser check, as CI runs them (pip install -r scripts/e2e/requirements.txt && python -m playwright install chromium)
# single checks; play.py and layout.py need a running host on port 8090 with TABLE_KEY=devkey
python3 scripts/e2e/play.py roulette out/ # also: pachisi, holdem, coinflip, endings, dialogs, rules (every game's rules on a 320 px phone), tabs
python3 scripts/e2e/admin.py out/ # the console, sign-in and logout (starts its own cloud and host)
python3 scripts/e2e/website.py out/ # the public website at / on a desktop and a phone (starts its own cloud)
python3 scripts/e2e/codes.py out/ # access codes: console, board keypad, a service restart, a second table refused (starts its own cloud and two hosts)
python3 scripts/e2e/remote.py out/ # remote play in a second browser (starts its own cloud and host)
python3 scripts/e2e/seat_loss.py out/ # a player lost during a game: the waiting card, the phone's banner, the return, Remove that ends the game (starts its own host)
python3 scripts/e2e/developer.py out/ # the developer setting: the last player at the table, DEV on the gear, a game of AIs only (starts its own host)
python3 scripts/e2e/logs.py out/ # game logs: a simulation from the board, a game with a phone, a table stopped mid-game, the console (starts its own cloud and host)
python3 scripts/e2e/viewer.py out/ # the Game Viewer: logs from the lobby and the settings, moves, filters, Move #, a move in full, facing east (starts its own host)
python3 scripts/e2e/extra.py out/ # extra-game repositories: console, table, remote player (starts its own fake GitHub, cloud and host)
python3 scripts/e2e/layout.py out/ # decks at 4 phone sizes x 3 games, the board at 5 screen sizes
# and one check per lobby feature, each with its own host: watch_lobby, invite_name, ai_wait, board_deck, card_sling,
# board_screen, sound_hint, seat_names, seats_full,
# rejoin, names, away, exchange, exchange_remote, one_board, settings_choice, next_hand (see each script's docstring)- Game rules run in-process; the isolated sandbox for third-party games comes later.
- The cloud keeps its state in SQLite on one volume (D-114), so it runs as exactly one replica.
- Tables authenticate to the cloud with an issued bearer token, not yet a key pair or certificate.
- Host-side AI configuration (
ai.hostConfig, e.g. API keys) is parsed but has no screen yet. For language models it will also hold the model, the effort and a cost limit per game (D-112). - werift waits up to 5 s for STUN during connection setup when STUN is unreachable.
MIT. Copyright (c) 2026 Klaus Hofrichter.