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, ads) is off until you enable it here.
{
"version": 1,
"resetTimeZone": "UTC",
"features": { "saves": true, "hosting": true },
"currencies": [],
"items": [],
"multiplayer": { "modes": [] },
"auth": { "redirectUrls": [], "providers": {} },
"web": { "allowedOrigins": [] },
"share": {},
"ads": { "enabled": false }
}Common types#
| Type | Rule |
|---|---|
| key | lowercase snake_case: ^[a-z][a-z0-9_]{0,127}$ (up to 128 characters). Keys are unique within their section; a currency and an item cannot share a key |
| text | a string (1–1,000 chars) or a map of language code → string: { "en": "Coins", "ja": "コイン" }. Language codes look like en, ja, pt-BR |
| long text | same as text, up to 2,000 chars |
| grant | { "currency": key, "count": n } or { "item": key, "count": n } — exactly one of currency / item. count is a positive integer ≤ 1e9, default 1 |
Top level#
| Field | Type | Default | |
|---|---|---|---|
$schema | string | — | ignored (for editor tooling) |
version | 1 | 1 | format version |
resetTimeZone | IANA zone | "UTC" | e.g. America/New_York. Unknown zones are rejected |
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.
| Feature | What it opens | Needs |
|---|---|---|
emailLogin | email sign-up / sign-in / verification / password reset, linking an email to a guest | |
saves | cloud saves (kumo.saves) | |
stats | submitting and reading stats (kumo.stats). The per-minute submit cap (integrity.stats.maxSubmitsPerMinute) always applies | |
inventory | currencies and items the user reads and spends (kumo.inventory.get / consume); ad rewards land here | |
multiplayer | rooms, matchmaking, the realtime WebSocket | |
realtimeChannels | realtime channels (kumo.realtime): named channels that deliver messages instantly; nothing is stored. The WebSocket connects when either this or multiplayer is on | |
voice | voice calls in channels created with voice (up to 100 people: peer to peer up to 8, through a relay server from 9; nothing is recorded) | realtimeChannels |
hosting | kumodeck deploy and serving your app on KUMODeck | |
statsVerification | value rules and the verification webhook in integrity.stats | stats |
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: ads → ads.enabled, 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[]#
| Field | Type | Default | |
|---|---|---|---|
key | key | required | |
title | text | — | |
aggregation | sum | max | min | latest | sum | how reports combine |
maxPerSubmit | number > 0 | — | largest value accepted in one report (anti-tamper floor) |
currencies[]#
| Field | Type | Default | |
|---|---|---|---|
key | key | required | |
title | text | — | |
initial | integer ≥ 0 | 0 | granted to a new user |
max | integer 1–1e12 | 1e9 | balance cap; grants are clamped |
items[]#
| Field | Type | Default | |
|---|---|---|---|
key | key | required | |
title | text | — | |
description | long text | — | |
kind | consumable | durable | collectible | consumable | durable/collectible = owned or not; cannot be spent |
max | integer 1–1e9 | 1e9 (consumable), 1 (durable, collectible) | per-player cap |
multiplayer.modes[]#
| Field | Type | Default | |
|---|---|---|---|
key | key | required | used in rooms.quickMatch(key) / rooms.create(key) |
title | text | — | |
minPlayers | 1–1,000 | 2 | quick match starts when this many are waiting |
maxPlayers | 1–1,000 | 4 | must be ≥ minPlayers. One room is one Durable Object, which handles about 1,000 messages a second: keep players × messages per second per player around 1,000 or less |
fillTimeoutSeconds | 0–300 | 15 | start with fewer players after this long; 0 = wait forever |
transport | server | p2p | server | p2p = players exchange game messages directly over WebRTC (peer-to-peer mode). No referee: do not use it for competitive or prize matches |
p2p.maxPlayers | 2–8 | 4 | mesh size limit; the mode's maxPlayers is capped to it and minPlayers must not exceed it. Joining a full mesh fails with p2p_room_full |
p2p.relayOnly | boolean | true | route everyone through the TURN relay so players never see each other's IP address. Players under 13 are always relayed, whatever this says |
limits.maxMessageBytes | 1,024–1,048,576 | 16384 | size of one send (JSON). Rooms of this mode only |
limits.maxStateBytes | 1,024–1,048,576 | 65536 | shared room state in total |
limits.maxPlayerStateBytes | 256–65,536 | 8192 | one player's state |
limits.messagesPerSecond | 1–240 | 30 | messages one connection may send per second (bursts up to twice this) |
limits.seatHoldSeconds | 1–3600 | 20 | how long a dropped player's seat is kept for resume |
Raising limits costs only your own game more (delivery, transfer, room time at cost). A room's shared state plus all player
states can never exceed 1.75 MB (one Durable Object value holds 2 MB). The room snapshot (room.limits) and every
payload_too_large / state_too_large error (details.limit) carry the actual numbers — read them instead of hard-coding.
multiplayer.idleTimeoutSeconds (10–86,400, default 600) closes a connection that is in no room, queue or channel for that long.
multiplayer.relayQuota.turnIssuesPerMinute (default 3,000) and multiplayer.relayQuota.sfuSessionsPerMinute (default 2,400),
each up to 15,000, set how many TURN relay credentials and voice (SFU) sessions this environment may create per minute.
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.
| Field | Type | Default | |
|---|---|---|---|
redirectUrls | URL[] (max 256, 2,000 chars each) | [] | pages of your app allowed as return addresses for email links and OAuth. Exact URL (any query), or a trailing * for a path prefix: https://mygame.example.com/*. Localhost in development and your KUMODeck-hosted URLs are always allowed |
providers.kumodeck.enabled | boolean | false | Sign in with KUMODeck (no registration needed: just turn it on) |
providers.google.enabled | boolean | false | Sign in with Google (needs your OAuth client in the dashboard) |
providers.discord.enabled | boolean | false | Sign in with Discord (needs your OAuth client in the dashboard) |
providers.apple.enabled | boolean | false | Sign in with Apple (needs your Services ID and key in the dashboard) |
providers.x.enabled | boolean | false | Sign in with X (needs your own X app's Client ID and Secret in the dashboard; where KUMODeck's shared X app is available, Use without setup works too; sign-in is free) |
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#
| Field | Type | Default | |
|---|---|---|---|
allowedOrigins | origin[] (max 256) | [] | web origins allowed to use your publishable key. Empty = any origin |
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"] } }rateLimits#
Raise, lower or remove rate limits for this app or game. Leave it out to keep the defaults.
| Value | Meaning |
|---|---|
"off" | don't apply this rule to this app |
{ "limit": n } | requests per window (window unchanged) |
{ "multiplier": x } | a multiple of the default (0.5 = half) |
window (with limit / multiplier) | change the window too: 30s, 10m, 1h, 1d |
{ "rateLimits": { "api.default.ip": { "multiplier": 5 }, "hosting.serve.ip": "off", "functions.invoke.ip": { "limit": 100, "window": "1m" } } }GET /v1/admin/rate-limits (secret key) lists the rules you can change with their defaults and current values. A 429
rate_limited also tells you the rule (rule), the limit (limit), the window (windowSeconds) and whether you can change it
here (configurable) in details. Limits are counted per app, so heavy use of another app from the same place (a school sharing one
IP address, say) doesn't affect yours. Requests above the default count as normal usage; with a rule removed, a third party flooding your app
is billed to you. Guards such as login and password reset can't be changed (the push fails with 400).
share#
Tools that help your app or game spread on X (guide). Everything is off by default; turn on only what you use.
| Field | Type | Default | |
|---|---|---|---|
images.enabled | boolean | false | render 1200×600 card images (default card + score / challenge cards) |
images.title | text (≤ 60) | — | app name drawn on the card |
images.background | path in your deployment | — | PNG / JPEG (≤ 2 MB, 2:1 works best) behind the text |
images.font | path in your deployment | — | extra TTF / OTF (≤ 10 MB). The built-in font covers Latin only; add a font for non-Latin scripts (for example CJK). |
images.theme | { background, accent, text } | #0f1115 / #ffcc33 / #ffffff | #rrggbb colors |
tags.enabled | boolean | false | no longer used: KUMODeck does not add tags to your pages (a push says so in one line). Put the tags from kumodeck share tags in your <head> |
tags.title / tags.description / tags.imageAlt | text | — | card text |
tags.image | path in your deployment or https:// URL | — | fixed card image (otherwise the rendered default card) |
tags.site | @handle | — | twitter:site |
links.enabled | boolean | false | kumo.share() issues share ids (?ks=) and challenges can be restored |
links.text | text (≤ 200) | — | default post text; {score} are replaced |
links.hashtags / links.via | string[] (max 5) / handle | [] / — | added to the X post |
tracking.enabled | boolean | false | count visits / new users / plays per share id (aggregates only) |
inAppBrowser.enabled | boolean | false | allow "open in your browser" as the same guest from X's in-app browser |
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 }
}
}ads#
Rewarded and interstitial ads (guide). Off by default. Frequency values can only be made stricter.
| Field | Type | Default | |
|---|---|---|---|
enabled | boolean | false | use ads in this app |
interstitial.enabled | boolean | false | true = also use interstitials (the production ad network is rewarded video only) |
interstitial.minIntervalSeconds | 90–3600 | 90 | minimum gap between interstitials |
interstitial.initialDelaySeconds | 180–3600 | 180 | no interstitial this soon after a session starts |
rewarded.dailyLimit | 1–20 | 20 | rewarded views per user per 24 hours |
rewards[] (max 32) | { key, title?, grants (1–8), dailyLimit? (1–20) } | [] | what each rewarded placement grants; key is the placement in kumo.ads.rewarded() |
audience#
general (default), mixed or kids: who uses your app or game. kids treats every user as under 13 (ads: rewarded only, non-personalized, child-directed).
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).
| Field | Type | Default | |
|---|---|---|---|
stats.rules[] | { stat, min?, max? } | [] | allowed range of a stat's value (e.g. a best time under 1 s is impossible → min: 1000) |
stats.maxSubmitsPerMinute | 1 or more | 60 | reports per user per minute |
stats.webhook.url | https URL | — | your server decides (http://localhost allowed in development) |
stats.webhook.timeoutMs | 100–10000 | 1500 | |
stats.webhook.onFailure | accept | reject | accept | what happens when your server is down or slow |
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#
| Section | Defines | API |
|---|
See the REST API for request and response shapes.
Validation rules (cross-references)#
- Duplicate keys within a section are rejected
- Every grant (ad rewards) must reference an existing currency or item
minPlayers≤maxPlayers