KUMODeck

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#

TypeRule
keylowercase 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
texta string (1–1,000 chars) or a map of language code → string: { "en": "Coins", "ja": "コイン" }. Language codes look like en, ja, pt-BR
long textsame 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#

FieldTypeDefault
$schemastring—ignored (for editor tooling)
version11format version
resetTimeZoneIANA 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.

FeatureWhat it opensNeeds
emailLoginemail sign-up / sign-in / verification / password reset, linking an email to a guest
savescloud saves (kumo.saves)
statssubmitting and reading stats (kumo.stats). The per-minute submit cap (integrity.stats.maxSubmitsPerMinute) always applies
inventorycurrencies and items the user reads and spends (kumo.inventory.get / consume); ad rewards land here
multiplayerrooms, matchmaking, the realtime WebSocket
realtimeChannelsrealtime channels (kumo.realtime): named channels that deliver messages instantly; nothing is stored. The WebSocket connects when either this or multiplayer is on
voicevoice 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
hostingkumodeck deploy and serving your app on KUMODeck
statsVerificationvalue rules and the verification webhook in integrity.statsstats

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[]#

FieldTypeDefault
keykeyrequired
titletext—
aggregationsum | max | min | latestsumhow reports combine
maxPerSubmitnumber > 0—largest value accepted in one report (anti-tamper floor)

currencies[]#

FieldTypeDefault
keykeyrequired
titletext—
initialinteger ≥ 00granted to a new user
maxinteger 1–1e121e9balance cap; grants are clamped

items[]#

FieldTypeDefault
keykeyrequired
titletext—
descriptionlong text—
kindconsumable | durable | collectibleconsumabledurable/collectible = owned or not; cannot be spent
maxinteger 1–1e91e9 (consumable), 1 (durable, collectible)per-player cap

multiplayer.modes[]#

FieldTypeDefault
keykeyrequiredused in rooms.quickMatch(key) / rooms.create(key)
titletext—
minPlayers1–1,0002quick match starts when this many are waiting
maxPlayers1–1,0004must 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
fillTimeoutSeconds0–30015start with fewer players after this long; 0 = wait forever
transportserver | p2pserverp2p = players exchange game messages directly over WebRTC (peer-to-peer mode). No referee: do not use it for competitive or prize matches
p2p.maxPlayers2–84mesh 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.relayOnlybooleantrueroute everyone through the TURN relay so players never see each other's IP address. Players under 13 are always relayed, whatever this says
limits.maxMessageBytes1,024–1,048,57616384size of one send (JSON). Rooms of this mode only
limits.maxStateBytes1,024–1,048,57665536shared room state in total
limits.maxPlayerStateBytes256–65,5368192one player's state
limits.messagesPerSecond1–24030messages one connection may send per second (bursts up to twice this)
limits.seatHoldSeconds1–360020how 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.

FieldTypeDefault
redirectUrlsURL[] (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.enabledbooleanfalseSign in with KUMODeck (no registration needed: just turn it on)
providers.google.enabledbooleanfalseSign in with Google (needs your OAuth client in the dashboard)
providers.discord.enabledbooleanfalseSign in with Discord (needs your OAuth client in the dashboard)
providers.apple.enabledbooleanfalseSign in with Apple (needs your Services ID and key in the dashboard)
providers.x.enabledbooleanfalseSign 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#

FieldTypeDefault
allowedOriginsorigin[] (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.

ValueMeaning
"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.

FieldTypeDefault
images.enabledbooleanfalserender 1200×600 card images (default card + score / challenge cards)
images.titletext (≤ 60)—app name drawn on the card
images.backgroundpath in your deployment—PNG / JPEG (≤ 2 MB, 2:1 works best) behind the text
images.fontpath 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.enabledbooleanfalseno 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.imageAlttext—card text
tags.imagepath in your deployment or https:// URL—fixed card image (otherwise the rendered default card)
tags.site@handle—twitter:site
links.enabledbooleanfalsekumo.share() issues share ids (?ks=) and challenges can be restored
links.texttext (≤ 200)—default post text; {score} are replaced
links.hashtags / links.viastring[] (max 5) / handle[] / —added to the X post
tracking.enabledbooleanfalsecount visits / new users / plays per share id (aggregates only)
inAppBrowser.enabledbooleanfalseallow "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.

FieldTypeDefault
enabledbooleanfalseuse ads in this app
interstitial.enabledbooleanfalsetrue = also use interstitials (the production ad network is rewarded video only)
interstitial.minIntervalSeconds90–360090minimum gap between interstitials
interstitial.initialDelaySeconds180–3600180no interstitial this soon after a session starts
rewarded.dailyLimit1–2020rewarded 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).

FieldTypeDefault
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.maxSubmitsPerMinute1 or more60reports per user per minute
stats.webhook.urlhttps URL—your server decides (http://localhost allowed in development)
stats.webhook.timeoutMs100–100001500
stats.webhook.onFailureaccept | rejectacceptwhat 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#

SectionDefinesAPI

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