Config reference (kumo.config.json)

Master data for one environment. Push it with kumodeck config push [file] --env <env> or edit it in the dashboard. The whole document is validated before anything changes; errors come back with a JSON path (multiplayer.modes[0].maxPlayers: …). Every section is optional, and every feature that costs money per use or changes what your users (called players in the API) see (external sign-in, sharing tools) is off until you enable it here.

{
  "version": 1,
  "resetTimeZone": "UTC",
  "features": { "saves": true, "hosting": true },
  "multiplayer": { "modes": [] },
  "auth": { "redirectUrls": [], "providers": {} },
  "web": { "allowedOrigins": [] },
  "share": {}
}

Common types#

Top level#

features#

Every feature is off until you turn it on. Only guest sign-in and reading the config always work. For a feature that is off, players and secret keys get 403 feature_disabled (with details.feature and details.configPath), and nothing is written — so nobody can run up your bill by calling an API your app does not use. The multiplayer WebSocket is closed with 4003 feature_disabled; a hosted app whose hosting is off is not served. Turn features on per environment (development and production have their own config): kumodeck features on <name> edits this file, then kumodeck config push --env <env>. kumodeck features shows what is on.

Unknown names are rejected on push (a typo would otherwise leave a feature off without telling you). A feature that is not offered right now cannot be turned on (403 feature_unavailable). Banning a user (dashboard, or POST …/players/:playerId/ban) always works; it needs no feature.

Some features keep their own switch elsewhere in this file: sign-in providers → auth.providers.<name>.enabled, the X tools → share.<tool>.enabled. KUMODeck Functions are turned on with kumodeck functions enable.

The dashboard (logged in as you) can always read your data while a feature is off, but using a feature from there (deploying) needs it on, just like from a secret key.

{ "features": { "hosting": true, "saves": true, "multiplayer": true } }

stats[] (max 128)#

multiplayer.modes[] (max 16)#

With no modes at all, a built-in default mode (2–8 players, 15 s) is available. Once you define any mode, only defined modes work.

auth#

Sign-in settings (guide). Guest and email sign-in always work; every external provider is off until you enable it.

Provider credentials are never stored in this file (it is pushed from your machine and kept in history); they are entered in the dashboard and stored encrypted.

{ "auth": { "redirectUrls": ["https://mygame.example.com/*"], "providers": { "x": { "enabled": true } } } }

web#

Your app can be hosted anywhere: on KUMODeck, on your own server, on itch.io. With the default (empty list) the SDK works from any origin. List origins to stop other sites from using your publishable key (you pay for usage): browser requests from other origins get 403 origin_not_allowed. Your KUMODeck-hosted URL and, in development, localhost are always allowed. Entries are origins without a path: https://mygame.example.com, https://*.itch.zone (any subdomain), http://localhost:5173, capacitor://localhost (your own app).

{ "web": { "allowedOrigins": ["https://mygame.example.com", "https://*.itch.zone"] } }

share#

Tools that help your app or game spread on X (guide). Everything is off by default; turn on only what you use.

The card tags need an image: either tags.image or images.enabled.

{
  "share": {
    "images": { "enabled": true, "title": "Space Cats", "background": "/card-bg.png" },
    "tags": { "description": "A tiny space game", "site": "@spacecats" },
    "links": { "enabled": true, "text": "I scored {score} in Space Cats. Can you beat it?", "hashtags": ["spacecats"] },
    "tracking": { "enabled": true }
  }
}

audience#

general (default), mixed or kids: who uses your app or game. kids treats every user as under 13. mixed treats users whose age is unknown as children until they declare an age.

integrity#

Server-side checks for reported stats. They run before a stat is stored; rejected values come back in rejected from POST /v1/stats and are logged as signals (nothing is acted on automatically).

The webhook receives POST { type: "stats.verify", environmentId, playerId, stats, submittedAt } with a Kumo-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + "." + body)> header (the secret is shown in the dashboard and at GET /v1/admin/integrity/webhook-secret). Answer { "approve": true } or { "results": { "<stat>": true } }.

Other sections#

See the REST API for request and response shapes.

Validation rules (cross-references)#

• Duplicate keys within a section are rejected
• minPlayers ≤ maxPlayers