Getting started

KUMODeck is a flat backend for vibe coding — web apps, games and more: hosting, your own server code and database, user logins, cloud saves, multiplayer rooms — behind one SDK and one CLI, and all of it can be set up by your AI agent. This page walks through one example, a small game from a starter template (the steps are the same for a web app), from nothing to a deployed game that remembers each player's best score, shared on X — every step is one command in your terminal.

1. Install the CLI and create your account#

npm install -g kumodeck     # or run any command without installing: npx kumodeck <command>
kumodeck signup                       # email + password; you are signed in right away

The CLI has zero dependencies and needs Node 22 or newer. signup creates your developer account and signs you in. Confirm your email next: paste the link from the confirmation email into kumodeck verify <link> (no email? kumodeck verify --resend). Adding prepaid credit, secret keys and AI agent (MCP) connections wait for it. Already have an account? kumodeck login. Your session is stored in ~/.kumo/credentials.json (file mode 0600). Point the CLI at a different server with --api <url> or KUMO_API_URL.

Tip Using an AI agent such as Claude Code, Codex or Cursor? Type kumodeck signup yourself (the password never goes through the assistant), then ask the assistant to do everything below. For the deposit, the assistant runs kumodeck billing topup and shows you the payment URL; you pay on that page. Each command prints the next command to run. See Use from an AI agent.

Tip Running the server yourself? pnpm install && pnpm dev in the repository starts everything on http://localhost:4000 with an embedded Postgres — no Docker. Every step on this page works against it.

2. Add prepaid credit#

kumodeck billing topup                # $5 minimum; prints a Stripe payment page, opens it, and waits until you have paid
# Paid $5.00 (card fee $0.45, at cost) — $4.55 added to your prepaid balance

There is no free tier: from the first request, what your project uses (API requests, hosting, saves, multiplayer, card images, Functions) is taken at cost from a prepaid balance, like an AI provider's API credits. So a new account adds funds before creating and deploying — $5 lasts a small app or game a long time (see the examples). You pay on Stripe's page yourself; the CLI never sees your card. kumodeck billing shows the balance any time, and the dashboard (Money → Prepaid) does the same with automatic top-up and a low-balance email.

While the balance is $0 or less and nothing else covers it (an automatic top-up that has not failed), the user-facing side of your projects pauses (your users see a neutral message) and new projects and deploys are refused with 402 — the error prints kumodeck billing topup. kumodeck billing and kumodeck whoami say plainly whether you are paused. Your dashboard, config pushes and top-ups keep working, and everything resumes on its own as soon as funds arrive. Details: Prepaid balance.

3. Create a project from a template#

kumodeck create my-game && cd my-game       # a playable game (template: vanilla-canvas)
kumodeck init                               # creates the project and writes your keys into public/kumo-config.js

create copies a starter template — it works offline and does not touch the server. Pick another one with --template phaser (also pixi, three, multiplayer-starter, functions-starter). Building a web app instead, or code you already have? Skip create and run kumodeck init in your project folder (or ask your AI agent to set it up); the rest of this page works the same.

init creates the project with two environments (development and production), saves kumo.json (including deployDir: "public", so kumodeck deploy needs no folder) and writes the two publishable keys into public/kumo-config.js for you. The page picks the development key on the --dev URL and on localhost, and the production key everywhere else. The secret keys are returned once: init saves them to .kumo/secrets.env (only you can read it; git ignores it) instead of printing them, so they stay out of your terminal history and out of your conversation with an AI assistant. Use them for CI, never put them in the browser. If the URL name (my-game) is already taken, init uses a free one KUMODeck suggests (my-game-2) and tells you.

4. Declare your project's rules#

Which features are on, prices, products and multiplayer modes live in kumo.config.json. The server owns these rules; a modified client cannot change a price.

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

kumodeck config push --env development

Every feature is off until you turn it on — the features line above opens exactly what this example uses (hosting and cloud saves). Anything else answers 403 feature_disabled, so nobody can run up your bill on features you do not use. kumodeck features lists them all; see the config reference.

A mistake in the file (a typo in a feature name, a mode with more minPlayers than maxPlayers) is rejected with the exact path, so you find it at push time instead of in production.

5. Call the SDK#

The SDK is served by your API at /sdk.js (global Kumo) and /sdk.mjs (ES module). init signs a guest in automatically, so the page works immediately; guests can link an email later without losing their data.

<script src="https://api.kumodeck.com/sdk.js"></script>
<script type="module">
  const kumo = await Kumo.init({ projectKey: 'pk_dev_…' });   // guest sign-in happens here
  const saved = await kumo.saves.get('best');                   // null on the first visit
  const score = 61;
  if (score > (saved?.data.score ?? 0)) await kumo.saves.set('best', { score });   // follows the user to every device
</script>

The templates already do this for you in public/kumo-boot.js — this is what to add to an app of your own. That is the whole integration. See Cloud saves for slots and conflict-safe writes.

6. Deploy#

kumodeck deploy --env development
# Deployed v1 to development: 5 files (22.3 KB)
#   https://api.kumodeck.com/play/my-game--dev/

deploy uploads the deployDir saved by init (public/ for a template; otherwise ./dist, or pass a folder). Uploads are content-addressed: only files the server has never seen are sent, so a redeploy of a 50 MB site that changed one script uploads one script. Production is the default environment for deploy. If hosting is off in that environment, deploy turns it on in kumo.config.json, pushes it there and tells you in one line — nothing else is switched on for you.

kumodeck config push --env production
kumodeck deploy --env production            # → https://my-game.kumodeck.app/
kumodeck rollback 3                         # instant: switch the live version back to v3

7. Share it on X#

kumodeck share on                           # X card image + share links + traffic per post, both environments; prints the card tags
kumodeck share link "first post"            # optional: a tracked URL for your own post

share on turns on three tools in kumo.config.json, pushes it and prints the card tags: put them in the <head> of index.html (or ask your AI agent to) and deploy again. The page then shows a large card on X; post its URL. The template's Share on X button posts the player's score as a challenge, and people who open that link see "Challenge: beat N!". Sign in with X stays off. Details: Sharing on X.

Next steps#

• Concepts — projects, environments, keys, players (your users) and master data
• Leaderboards with a Skill — ask your AI agent; the Skill builds one in your own database and Functions
• Play online together — for games: ask your AI agent "make it playable online"
• Multiplayer rooms — for games: quick match, room codes, shared state
• Sharing on X — cards, challenges and traffic per post (off until you turn them on)
• Functions — your own server code and SQL database
• Pricing — 0% fee, no free tier, everything at cost
• Security model — what the publishable key can and cannot do