Skip to content
SudokumaxSudokumax
Developer documentation ⌄
DevelopersDeveloper starter

Build a Sudoku app

A runnable game with a backend, persistent progress, server-side answer checking and explained hints. Keep the required Sudokumax link while building your own experience.

Developer kit 1.2.0MIT example code
On this page

Download and run

Download the developer kit

No repository access is required. Install Node.js 22.13 or newer and npm. The kit includes a lockfile, TypeScript declarations, a standard-library Python client, an MCP adapter, tests and a Dockerfile. Version and checksum.

unzip sudokumax-developer-kit-1.2.0.zip
cd sudokumax-developer-kit-1.2.0
npm ci
cp .env.example .env
# Edit .env locally and add your API key.
npm run smoke
npm start

Open http://localhost:3051. Create a puzzle, save progress, ask for a hint and reload. Get a free API key.

A complete request flow

  1. Your server prefetches five puzzles and stores their answers privately.
  2. The browser receives the puzzle, its ID, progress and visible website credit.
  3. An HttpOnly session cookie associates games with that browser. SQLite persists saved games across server restarts.
  4. Your server checks entries and completion against its saved answer. Per-move checks use no upstream API quota.
  5. Hints use the API with strategy: logical, explaining candidate eliminations before the next placement.

The example rejects changed givens, isolates browser sessions, limits request bodies and checks the Origin on writes. Sessions expire after seven days; add your own account and recovery system for long-term, cross-device progress.

Deploy with persistent storage

docker build -t sudokumax-starter:1.2.0 .
docker volume create sudoku-data
docker run --rm -p 3051:3051 --env-file .env \
  -e APP_ORIGIN=https://sudoku.example.com \
  -v sudoku-data:/data sudokumax-starter:1.2.0

Replace the domain, add an HTTPS reverse proxy and edge rate limits, and back up the volume. The container runs as a non-root user. Keep secrets outside the image.

SQLite requires one application instance and persistent disk. For Vercel or multiple instances, replace the example storage layer with a shared database and distributed session, quota and inventory handling. The README identifies the storage boundaries and deployment checks.

Production and capacity guide →

JavaScript, TypeScript and Python clients

import { SudokumaxClient } from './clients/client.mjs';
const api = new SudokumaxClient({apiKey: process.env.SUDOKUMAX_API_KEY});
const result = await api.call('generate', {count: 5, difficulty: 'medium'});

TypeScript resolves the accompanying operation-specific declarations. Python 3.10+ uses clients/sudokumax.py with no external dependencies. Errors expose the HTTP status, error code, application request ID and retry delay. The clients use bounded retries for safe operations and never automatically repeat generation or exports.

Install the local MCP adapter →