---
title: "Getting started"
description: "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…"
url: "/docs/getting-started/"
lang: en
index: "/llms.txt"
---
# 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

```sh
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](/docs/claude-code/index.md).

> **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

```sh
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](/docs/pricing/index.md)).
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](/docs/pricing/index.md#prepaid-balance).

## 3. Create a project from a template

```sh
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](/docs/templates/index.md) — 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.

```json kumo.config.json
{
  "features": { "hosting": true, "saves": true }
}
```

```sh
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](/docs/reference/config/index.md#features).

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.

```html
<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](/docs/guides/saves/index.md) for slots and conflict-safe writes.

## 6. Deploy

```sh
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.

```sh
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

```sh
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](/docs/guides/sharing/index.md).

## Next steps

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