Concepts

KUMODeck is a flat backend for vibe coding: web apps, games and more. Hosting, a database and sign-in are set up by the AI agent you already use, when you ask for them in plain words. Five ideas explain everything in it: projects, environments, keys, players (your users — the API calls them players) and master data. Three promises sit on top of them: you pick only the parts you want, your users see your app — not KUMODeck — and what you build on it stays yours.

A flat backend#

KUMODeck provides the parts a web app or game needs and adds nothing in front of your app: a database and your own server code (Functions), multiplayer, sign-in (guests included), cloud saves, hosting on your own domain, sharing on X, and control of all of it from your AI agent (Claude Code, Codex, …). Nothing is layered on top of your app: no store front and no KUMODeck branding in front of your users. Multiplayer rooms and the game recipes (Skills for games) are there for games; an app simply leaves them off.

Who takes care of what#

KUMODeck guards what would hurt you or your users if it broke. What you build and how it works stays with you, so you are free to build it your way — and KUMODeck does not take on the job of judging it.

Leaderboards and other game features: build them with a Skill#

Leaderboards and similar game features are not a KUMODeck service. You build them in your own database and Functions: ask your AI agent, and the leaderboard Skill in your template (.claude/skills/leaderboard/SKILL.md) puts the code together for you. The code, the data and the rules are yours — change them however your game needs.

Pick only what you need#

Every building block works on its own: use only hosting, only saves, only the database — or host the app yourself and use none of it. Only what you use is metered, at cost (Pricing).

Storing data: Protect in D1, not in saves. Anything a user must not be able to change themselves — scores and rankings, coins, credits, items, purchases, badges, anything shared between users — goes in the project's own Functions + D1. saves holds only what the user may freely write (settings, drafts, a solo game's progress). When unsure: if a user changing it by hand would be a problem, use your database. The table of what goes where is in saves and Functions.

Anything that costs money per use or changes what your users see is off until you turn it on:

The rest (saves, rooms) only does something when your app calls it or your config declares it.

Your app, not KUMODeck#

KUMODeck is infrastructure, like a CDN. Your users see your app or game, your URL and your card on X. KUMODeck's name does not appear in what they see: hosted pages, card images, share links, Functions responses, sign-in emails (they carry your project's name) and error messages they can reach are unbranded.

Projects#

A project is one app or game. You create it with kumodeck init or from the dashboard. It has a name, a slug (the URL name: lowercase letters, digits and single hyphens — -- is reserved) and belongs to one developer account. kumodeck init writes kumo.json (projectId, slug, api) next to your code. That file contains no secrets and is safe to commit.

Environments#

Every project has two environments: development and production. They share nothing at runtime:

Test runs never mix with real users' data, and a config experiment never reaches real users until you push it to production.

Keys#

Each environment has two kinds of API key. The environment is part of the key, so a key can never act on the wrong environment.

The SDK refuses a secret key outright. Keys are shown in plain text once at creation; the server stores only a hash. Rotate from the dashboard (create a new key, deploy, revoke the old one).

Developers (you, in the dashboard and CLI) authenticate separately with a developer session (kds_…).

Players#

A player is one user of your app or game (the API and SDK say player: players, playerId), scoped to one environment of one project — KUMODeck never tracks a user across projects.

• Kumo.init() signs in a guest automatically on first visit and resumes the same guest afterwards (the refresh token lives in localStorage, per publishable key).
• A guest can link an email later (auth.linkEmail) and keep every save. After that, the player can sign in on another device with auth.signInWithEmail.
• Sessions: a 15-minute access token (JWT) plus a 90-day rotating refresh token. Reusing an old refresh token revokes the whole chain (theft detection). The SDK refreshes transparently and coordinates across browser tabs.
• Banned players are rejected at sign-in, refresh and on every write, and their realtime connections are closed.

Master data (kumo.config.json)#

The rules the server enforces for your project are declared, not coded:

Push it with kumodeck config push (or edit it in the dashboard). Every push is validated as a whole and versioned; pushing identical content does not create a new version. Your app reads the public parts (GET /v1/gamedata/definitions), but only the server applies them: a modded client cannot change them. See the config reference.