Quiz and drawing games for team meetings.
The questions go up on the meeting-room TV, everyone answers on their own phone.
gamemash.io · Self-hosting · Contributing
![]() |
![]() |
![]() |
![]() |
| Join with the code on the TV | Answer before time runs out | See how you did | Draw the word, then rate |
The host opens GameMash on the big screen and lines up a few short games. Players scan the QR code or type the four-letter code on their phones and pick a name. There are no accounts and nothing to install. Points carry across every game, and one podium at the end covers them all.
- Pop quiz. Your own questions, multiple choice or true or false, with pictures if you want them. Every answer has a shape as well as a colour, so colour-blind players aren't guessing.
- Draw it. Everyone draws the same word against the clock. The drawings show up on the TV without names, and players rate each other's from 1 to 10.
Up to 100 players can join one session. Names, photos, answers and drawings only exist while the session runs: ending it deletes them, and a session nobody uses for 30 minutes deletes itself.
Use the hosted version at gamemash.io for free, or run your own on a single server.
Product decisions, progress and open questions live in docs/spec.md. To contribute, start with CONTRIBUTING.md.
Requires Node 24+, pnpm 10 and Docker (for Redis on port 6380 and MinIO on port 9000, console on 9001; set REDIS_PORT, MINIO_PORT or MINIO_CONSOLE_PORT to change them).
pnpm install
pnpm services # start Redis and MinIO in Docker
cp apps/api/.env.example apps/api/.env # first time only
pnpm dev # build packages, then watch everythingThe web app runs on http://localhost:5173 and proxies /api and /socket.io to the API on port 3000. The landing page runs on http://localhost:4321. Stop the services with docker compose down. Question images are stored in apps/api/.images; delete that folder to wipe them.
| URL | Screen |
|---|---|
/host |
Create a session (big screen) |
/host/:sessionId/setup |
Workshop: name the session, build the lineup |
/host/:sessionId |
Big-screen lobby with room code and QR code |
/ and /join/:code |
Join from a phone (name + optional photo) |
/join?code= |
Redirects to /join/:code (landing page form) |
/play/:sessionId |
Phone waiting screen |
Phones can't open localhost. Set VITE_PUBLIC_URL in apps/web/.env (see apps/web/.env.example) to an address the phone can reach, such as your machine's LAN address (http://192.168.1.20:5173) or an ngrok URL (ngrok http 5173), then restart pnpm dev. The lobby shows that address and puts it in the QR code, and Vite accepts it as a host. Without it the lobby uses the page's own address.
Environment variables for the API, web app and landing page
apps/api/.env:
| Variable | Default | Purpose |
|---|---|---|
HOST |
0.0.0.0 |
Listen address |
PORT |
3000 |
API port |
REDIS_URL |
redis://localhost:6380 |
Redis connection |
LOG_LEVEL |
info |
Pino log level |
TRUST_PROXY |
empty | Comma-separated proxy addresses whose X-Forwarded-For is trusted |
IMAGES_DIR |
empty | Folder for question images on disk (.images in .env.example) |
IMAGES_MAX_ACTIVE |
3000 |
Most question images kept across all sessions at once |
IMAGES_MIN_FREE_MB |
1024 |
Uploads pause when the disk has less free space than this |
S3_ENDPOINT |
empty | S3-compatible endpoint for question images, scheme and host only |
S3_BUCKET |
empty | Bucket for question images |
S3_ACCESS_KEY_ID |
empty | S3 access key |
S3_SECRET_ACCESS_KEY |
empty | S3 secret key |
S3_REGION |
auto |
Signing region (auto for R2) |
Question images are stored on disk under IMAGES_DIR and served by the API at /api/images/{sessionId}/{imageId}. Setting all four S3_* variables stores them in an S3-compatible bucket instead (presigned URLs, valid for an hour); a partial set stops the API at startup. With neither, the API runs with images turned off. Images live under sessions/{sessionId}/. Images that no question has used for 10 minutes are deleted when the setup is saved. All of a session's images are deleted when it ends, and every 10 minutes the API sweeps away the images of sessions that expired with nobody connected.
Uploads pause (image_storage_full) once IMAGES_MAX_ACTIVE images are held across all sessions or the disk drops below IMAGES_MIN_FREE_MB, so abuse can fill a limit but never the disk or a bill.
apps/web/.env:
| Variable | Default | Purpose |
|---|---|---|
VITE_PUBLIC_URL |
empty | Address shown in the lobby and its QR code |
API_URL |
http://localhost:3000 |
Where the dev server proxies /api and sockets |
apps/landing/.env:
| Variable | Default | Purpose |
|---|---|---|
PUBLIC_PLAY_URL |
https://play.gamemash.io |
The app's address, used by "Host a session" and join box |
Set PUBLIC_PLAY_URL=http://localhost:5173 (as in apps/landing/.env.example) to try those links locally.
To try the S3 image store in development, point the API at the MinIO container that pnpm services starts: S3_ENDPOINT=http://localhost:9000, S3_BUCKET=gamemash-dev, S3_ACCESS_KEY_ID=minioadmin and S3_SECRET_ACCESS_KEY=minioadmin.
Tests that need Redis use TEST_REDIS_URL (default redis://localhost:6380). The S3 image store tests use TEST_S3_ENDPOINT (default http://localhost:9000), TEST_S3_BUCKET (default gamemash-test, created on the fly), TEST_S3_ACCESS_KEY_ID and TEST_S3_SECRET_ACCESS_KEY (default minioadmin). Without Redis or MinIO those tests are skipped locally; in CI they fail. pnpm services starts both.
GameMash runs on one Linux server with Docker, defined in deploy/compose.yml: Redis, the API and Caddy, which handles HTTPS. Caddy serves the app on APP_DOMAIN, the landing page on LANDING_DOMAIN, and redirects every domain in REDIRECT_DOMAINS to the landing page.
- Point your domains (A and AAAA records) at the server.
- On the server, allow only SSH, HTTP and HTTPS through the firewall (
ufw allow OpenSSH && ufw allow 80,443/tcp && ufw allow 443/udp && ufw enable), and log in with an SSH key only. - Install Docker:
curl -fsSL https://get.docker.com | sh. - Clone the repository, then
cp deploy/.env.example deploy/.envand set the domains andPUBLIC_URL(the app's address, for examplehttps://play.example.com). - Start it:
docker compose -f deploy/compose.yml --env-file deploy/.env up -d --build. Caddy fetches the HTTPS certificates on the first request. - To update:
git pull, then run the same command again.
If you don't want the landing page, remove its two site blocks ({$LANDING_DOMAIN} and {$REDIRECT_DOMAINS}) from deploy/Caddyfile and the two variables from deploy/compose.yml.
The app's Content-Security-Policy in deploy/Caddyfile only allows images from the site itself; if you switch to an S3 bucket, add its origin to img-src. The landing page's policy is generated by Astro at build time.
Question images sit in the images volume, Redis data (sessions only, all with expiries) in redis-data. No backups are needed: nothing outlives a session.
How gamemash.io itself is deployed is described in docs/deploying.md.
| Command | What it does |
|---|---|
pnpm services |
Start Redis and MinIO (for S3 tests) in Docker |
pnpm dev |
Build shared packages, then run everything in watch mode |
pnpm lint |
Biome lint + format check |
pnpm format |
Biome autofix |
pnpm typecheck |
TypeScript across all workspaces |
pnpm test |
Vitest |
pnpm build |
Production build |
pnpm stories |
Ladle stories for @gamemash/ui (port 61000) |
apps/api– Fastify + Socket.io + Redis, question images on disk (or an S3-compatible bucket)apps/web– React, TanStack Router/Query, Zustand, Tailwind, Base UI, react-intlapps/landing– the static landing page for gamemash.io (Astro)packages/shared– types, constants and helpers shared by API and web; TypeBox schemas under@gamemash/shared/schemaspackages/games– game definitions (title, colour, icon) and game config; helpers under@gamemash/games/config, schemas under@gamemash/games/schemaspackages/messages– ICU message catalogspackages/ui– design system: tokens, Base UI primitives, layouts
GameMash is free software under the GNU Affero General Public License v3.0. If you run a modified version as a service for others, you have to offer them its source code.



