KUMODeck

Hosting & deploy

kumodeck deploy <dir> publishes a folder of static files (your built web app or game) as a new version of an environment. Every version is kept; switching between them is instant. Apps that render on the server (Next.js, Astro, SvelteKit, Nuxt, React Router, TanStack Start, Hono…) deploy too: see Server-rendered apps.

Hosting is optional. Your app can live anywhere — your own server, itch.io, a CDN — and still use every other part of KUMODeck (list its origin in web.allowedOrigins if you want to stop other sites from using your publishable key). Hosted apps are served under your app's own subdomain — or your own domain — with no KUMODeck branding.

Deploy#

# production (deploy's default is development)
kumodeck deploy dist --env production
kumodeck deploy dist --env development -m "new boss fight"
# list versions (* = live)
kumodeck deployments
# make version 12 live again, instantly
kumodeck rollback 12
EnvironmentURL
productionhttps://<slug>.kumodeck.app/
developmenthttps://<slug>--dev.kumodeck.app/
local serverhttps://api.kumodeck.com/play/<slug>/ and https://api.kumodeck.com/play/<slug>--dev/

The folder must contain an index.html. Dotfiles and node_modules are skipped (.well-known/ is included); symlinks are not followed.

Server-rendered apps#

Apps that make their pages on the server — Next.js (with vinext or OpenNext, below), Astro (with its Cloudflare adapter), SvelteKit, Nuxt, React Router in framework mode, TanStack Start, Hono, SolidStart — deploy the same way you would to Cloudflare Workers: a Worker plus its static assets. Off by default: kumodeck deploy turns on serverRendering (and hosting, which it needs) for that environment and says so in one line, the same way a static deploy turns on hosting. To turn it on yourself: kumodeck features on serverRendering && kumodeck config push --env development (this also turns on hosting).

# build, then check with KUMODeck without deploying
kumodeck deploy --env development --dry-run
# build, upload what is new, make it live
kumodeck deploy --env development

Run it in the project folder without a folder argument. The CLI then:

  1. Detects the project: a wrangler.jsonc with main, or a server framework in package.json. Anything else — or kumodeck deploy dist, or a deployDir in kumo.json — is the static deploy above. --app / --static override it.
  2. Runs wrangler setup --yes if the project has no wrangler.jsonc yet (Cloudflare's own setup adds the adapter).
  3. Builds on your computer (npm run build, or pnpm / yarn / bun from the lockfile), then bundles with wrangler deploy --dry-run --outdir .kumo/app-build. Nothing is sent to Cloudflare by wrangler, and KUMODeck never builds your code.
  4. Asks KUMODeck for a dry run (sizes, files to upload, databases it will create, warnings), uploads only new files and switches the live version.

wrangler must be installed in the project (npm install -D wrangler); without it the CLI uploads the build as static files and says so. --json shows the detection, the build commands and what was sent.

  • Where it runs: https://<slug>.kumodeck.app/, https://<slug>--dev.kumodeck.app/ and your custom domains — not under /play/. POST requests (forms, server actions) reach the app.
  • Static or app: an environment serves whichever version is live. kumodeck rollback switches between static and app versions instantly.
  • Databases and files: D1, KV, R2 and Queue producers in wrangler.jsonc are created per environment and shared with Functions by binding name.
  • Your app's database: create the tables and query it with kumodeck db migrate DB and kumodeck db query DB "SELECT …" (the same as kumodeck functions db …). Functions do not need to be on. db migrate reads the folder from migrations_dir of that database in the app's wrangler.jsonc (default migrations). A SQL mistake answers d1_query_error with the database's message: fix the SQL.
  • Logs: what the app prints with console.log / console.error is kept for 7 days. Read it with kumodeck logs (together with Functions, mixed by time; --source app for the app only) or the MCP tool functions_logs (Logs). Lines are billed at cost like Functions logs; kumodeck deploy --no-logs keeps none for that version. A version deployed before apps had logs answers app_logs_unavailable: deploy again. Code that throws while starting answers app_script_error with the exception in details.error.
  • API keys and passwords: enter them in the dashboard (Functions → API keys and passwords) or with kumodeck functions secret put NAME; they are set for Functions and the app together (how; do not paste keys into your conversation with your AI). Do not put secrets in vars (the deploy warns about names that look like secrets).
  • Scheduled jobs: the app's Worker cannot have crons. Put them in Functions.
  • Cookies: KUMODeck removes Domain= from the app's Set-Cookie, so cookies stay on the app's own host.
  • Not available yet: image optimization (serve images as they are), ISR, Durable Objects, service bindings, native modules. The deploy Skill lists what to use instead.
  • Cost: requests and CPU of the app, billed at cost from your prepaid balance.

Next.js#

Next.js is built with vinext (Cloudflare's Next.js on Vite) — the recommended way — or with OpenNext (@opennextjs/cloudflare), which stays as the fallback. Both run without ISR for now. kumodeck deploy uses vinext when it is in package.json and OpenNext when only OpenNext is set up; with neither, it stops and prints the lines for both (next_adapter_choice). --next vinext / --next opennext chooses for one deploy.

vinext (recommended) — needs Node.js 22.18 or later:

  1. Install it: npm install -D vinext (or pnpm / yarn / bun add -D vinext).
  2. Run npx vinext check and change what it marks ✗.
  3. Run this once (it writes vite.config.ts and cloudflare.config.ts; the three choices are needed, or it stops and asks):
    npx vinext init --platform=cloudflare --cdn-cache=none --data-cache=none --image-optimization=none
  4. kumodeck deploy. The CLI runs vinext check and vite build (instead of steps 2–3 above) and uploads .cloudflare/output/v0. It does not change your files, and no Cloudflare account is needed.
  • If vinext check finds something vinext does not support, the deploy lists it. With OpenNext installed, it deploys with OpenNext this time; change the listed items and deploy again to use vinext. Without OpenNext, it stops (vinext_check_failed). kumodeck deploy --next vinext tries vinext anyway.
  • Image optimization (imagesOptimizer, bindings.images()) stops the deploy: vinext fails without it at runtime, so it cannot be left out. Init with --image-optimization=none; images are served as they are.
  • Keep the assets binding named ASSETS (as vinext init writes it).

OpenNext (the fallback) — for apps vinext does not support yet, or when vinext does not work. For OpenNext, step 3 above is opennextjs-cloudflare build (it runs next build); the CLI then copies the pages built at build time into the assets (.open-next/cache → .open-next/assets/cdn-cgi/_next_cache).

  1. Install @opennextjs/cloudflare and wrangler. If wrangler.jsonc or open-next.config.ts is missing, the CLI writes the smallest one it needs and says so (it never overwrites). The assets binding must be named ASSETS.
  2. An open-next.config.ts you already have must use the read-only cache from the assets. The CLI stops before building otherwise (it does not edit your files):
    import { defineCloudflareConfig } from "@opennextjs/cloudflare";
    import staticAssetsIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/static-assets-incremental-cache";
    
    export default defineCloudflareConfig({ incrementalCache: staticAssetsIncrementalCache });
  3. Set images: { unoptimized: true } in next.config (no image optimization yet; images are served as they are).
  4. kumodeck deploy (kumodeck deploy --next opennext when vinext is installed too).
  • revalidate has no effect yet; server-rendered pages and pages built at build time work. R2 / KV / D1 caches and queues for ISR (NEXT_INC_CACHE_*, NEXT_TAG_CACHE_*, NEXT_CACHE_*) are refused.
  • services (WORKER_SELF_REFERENCE) and images in OpenNext's wrangler.jsonc are not sent; the deploy says so.
  • Edge middleware works. Node.js middleware gets a warning (it is experimental in OpenNext too); if it fails, go back to Edge.

Both: Route Handlers and Server Actions reach the app. A static export (output: "export", then kumodeck deploy out) still works. Next.js needs Node.js compatibility: it is on by default with a compatibility_date of 2026-08-04 or later (vinext init also writes nodejs_compat). With an older date, KUMODeck adds nodejs_compat and says so (next_nodejs_compat_added): add it to compatibility_flags in wrangler.jsonc too, so local runs match.

If Next.js does not work#

Next.js on KUMODeck is in beta: it has not been checked on the production runtime yet. Every Next.js deploy says so (the warning vinext_beta for vinext, next_beta for OpenNext; when a deploy fails, the error's details.fallback points here too). If the app does not work after it is deployed, deploy it again in one of these ways.

If it was deployed with vinext, deploy it with OpenNext — install OpenNext if it is not there yet, then:

npm install -D @opennextjs/cloudflare wrangler
kumodeck deploy --next opennext   # development (deploy's default)

If it still does not work, try one of these two.

1. Export it as a static site — for apps that do not need server code on each request (no Route Handlers, Server Actions, middleware or cookies read on the server). In next.config:

const nextConfig = { output: "export", images: { unoptimized: true } };
export default nextConfig;
npx next build        # writes the site to out/
kumodeck deploy out    # development (deploy's default)

Server code the app still needs can move to the project's own Functions.

2. Render each page on request — remove ISR: delete export const revalidate = … from pages and layouts and next: { revalidate: … } from fetch calls (use cache: "no-store" where the data must be fresh), and remove the NEXT_INC_CACHE_* / NEXT_TAG_CACHE_* / NEXT_CACHE_* bindings from wrangler.jsonc. Then deploy as before:

kumodeck deploy        # development (deploy's default)

If it still does not work, keep the error's code and details from kumodeck deploy --json when you report it.

Custom domains#

Serve the production app on a domain you own, such as play.mygame.com. Your users, share links and X cards (the card tags and image URLs) then use that domain — they never see a KUMODeck URL. KUMODeck handles the certificate and the ownership check; you add two DNS records. Off by default.

kumodeck features on customDomains && kumodeck config push --env production
kumodeck hosting domains add play.mygame.com     # prints the DNS records to add
kumodeck hosting domains status play.mygame.com  # check again after adding them
kumodeck hosting domains                         # list
kumodeck hosting domains remove play.mygame.com  # asks first (--yes in scripts)

add prints the two records exactly as your DNS provider asks for them:

CNAME  play.mygame.com               <the CNAME target it prints>
TXT    _kumo-verify.play.mygame.com  kumo-verify=<your account's value>

The CNAME points the name at KUMODeck; the TXT proves the domain is yours (the value is the same for every domain on your account). Add both at the same time where you manage the domain (your registrar or DNS provider). KUMODeck checks every hour and starts serving once they are found — usually minutes, sometimes a few hours. Your <slug>.kumodeck.app URL keeps working, so links you already posted do not break.

  • Watch two things: status (pending → active, or failed) and verified (ownership proven by the TXT, with the time it was last confirmed). While something is missing, the output lists what to do next.
  • Keep the TXT record after the domain is live: KUMODeck re-checks it every day and stops serving on the domain if it is gone.
  • One TXT on a parent domain covers everything under it: _kumo-verify.mygame.com also proves play.mygame.com, www.mygame.com and so on, so further subdomains need only their CNAME.
  • A domain someone else merely signed up for is not theirs: whoever proves ownership with the TXT gets it. The only "already in use" refusal is when this app already uses the domain for the other purpose (Functions vs. hosting).
  • Root domains (mygame.com): some DNS providers cannot put a CNAME at the root. Use ALIAS / ANAME / CNAME flattening if your provider has it, or a subdomain such as play.mygame.com.
  • What changes when it is active: the URL returned by kumodeck deploy, share links, X card tags and image URLs use your domain (card tags you already put in <head>: get them again with kumodeck share tags --env production and replace them); sign-in redirects and web.allowedOrigins accept it automatically (https only).
  • Your own ad network (ads.txt): put ads.txt at the top of your files and deploy; it is served as-is at https://play.mygame.com/ads.txt. Ad networks read ads.txt only at the root of a domain you own, so on <slug>.kumodeck.app it is not your file — use your own domain for your own ad network. On a domain shared by several apps it comes from the app at the root (with no app at the root, the one at the shortest path). app-ads.txt is served like any other file, and a server function on its own domain can return /ads.txt from its code. A deploy that includes ads.txt where it is not served says so in its warnings. While the app uses KUMODeck's ads (ads.enabled), /ads.txt is KUMODeck's file on every address instead.
  • How many: no per-project limit — each domain costs the same (see Cost below). The only cap is on domains still waiting for their TXT record: up to 20 per environment at a time (the error's details.limit has the number). It stops anyone from queueing up sign-ups for domains they do not own; verified domains do not count, so verify them and add more.
  • Development too: the API also accepts the development environment (for example beta.mygame.com for testers). It keeps development's protection — search engines are told not to index it. The commands above add domains to production for now.
  • Clean-up: a domain whose TXT is never found is removed after 7 days, and one that stays not active for 14 days is removed too (so sign-ups for someone else's domain do not linger). You get an email 2 days before; add the missing record, or simply add the domain again later.
  • Cost: using your domain on KUMODeck costs $0.11 a month per domain (the certificate and serving on it), taken from your prepaid balance by the day. You still pay for the domain itself where you bought it. Remove the ones you no longer use.
  • Turning customDomains off stops serving on your domains (listing and removing still work).

The dashboard (Hosting) and the MCP tools hosting_domains_list / hosting_domain_add / hosting_domain_remove do the same.

One domain, several apps#

Several apps of the same account can share one domain, each at its own path. Run add with a path in each app's folder:

# this app at https://mygame.com/race/
kumodeck hosting domains add mygame.com/race
# another app at the root (optional)
kumodeck hosting domains add mygame.com

When another app of yours already has the domain, adding a path needs no new DNS records: it is live as soon as the domain is. Paths use lowercase letters, digits, - and _. Each app sits on a domain at one path; remove mygame.com in its folder takes only that app off (the domain stays while other apps use it).

  • Relative links: under /race/, a link that starts with / (/images/a.png, url(/bg.png), fetch('/data.json')) loads from the domain root, not from this app. Write it without the leading / (images/a.png). KUMODeck does not rewrite your files: add and each deploy list the file and line of every such link it finds (links built in code are not found).
  • Single-page apps (web.spaFallback): add <base href="/race/"> to index.html, or build with base /race/ (Vite's base).
  • One origin: every app on the domain shares localStorage, IndexedDB, cookies and Service Workers. Start each app's keys with its own name (race:best) and give a Service Worker the app's path as its scope. This is why only apps of the same account can share a domain.
  • Server-rendered apps only at the root of a domain (for example app.mygame.com).
  • web.allowedOrigins works per domain: every app on it counts as https://mygame.com.
  • Cost: still one domain — paths add nothing.

Changing the URL slug#

The slug is the name in your game's URLs (<slug>.kumodeck.app). You can change it later — once a day. Undoing your last change within 24 hours does not count.

# current slug, next change date, old slugs and their redirects
kumodeck slug
# free? what changes? (URLs, the two choices below)
kumodeck slug check sky-racers-2
# or --no-redirect: you must pick one
kumodeck slug change sky-racers-2 --keep-redirect
# turn the redirect of an old slug on (or off)
kumodeck slug redirect sky-racers on

When you change it, you choose what happens to links that use the old slug — there is no default:

  • Keep old links working (--keep-redirect): old URLs redirect (301) to the new ones, keeping the path and query (so share links still count). $1 a month per old slug, charged daily from your prepaid balance while it is on. It keeps working even if your balance runs out; it stops only when you turn it off.
  • Let them stop working (--no-redirect): old URLs show a neutral "Not found" page. No charge.

Either way the old slug stays reserved for your game as long as the project exists — nobody else can take it — so you can turn its redirect on or off later. Custom domains do not change.

When you delete a project, its redirects stop right away (and so does their charge), and players are signed out. 30 days later its slugs — the current one and the old ones — are free again: anyone can take them, and links you posted (on X and elsewhere) then open that person's page. Nothing else of your project goes with the slug (custom domains, server functions, share links and card images stay with your deleted project).

Changing the slug or a redirect asks you to confirm it is you (your password, or signing in again with Google etc.). The CLI asks for your password in a terminal; accounts without a password change it in the dashboard (Hosting → URL slug). The MCP tools project_slug_get / project_slug_check only read: an AI assistant cannot change your slug.

Secrets in deployed files#

Everything you deploy is sent to the browser, and anyone can read it. A real key in your HTML, JS, CSS, JSON or source map can be copied by anyone who opens the page and used by someone else — and you pay for what they do with it. So kumodeck deploy (before uploading) and KUMODeck itself (when a version is published, whether from the CLI, an AI agent or the dashboard) stop the deploy when a text file contains any of the following. Three checks overlap so that it works for keys from any service:

  1. The same text as a key you saved (KUMODeck only): when you save a key (the input box your AI assistant opens, or kumodeck functions secret put), a fingerprint for matching is kept instead of the value (an HMAC made with a server key; it cannot be turned back into the value). Publishing looks for the same text — even for services whose key shape is unknown. Deleting the key deletes its fingerprint.
  2. A known secret-key shape of a common service: the table below.
  3. Text that looks like a key: long random text right after a word like key, secret, token or password (or a service name).
StoppedNot stopped
your own secret key sk_…, Stripe sk_live_ / rk_live_ / whsec_, Anthropic sk-ant-, OpenAI sk-proj- / sk-…, Supabase sb_secret_ and the service_role key, Firebase / Google Cloud service account keys (JSON), AWS AKIA…, GitHub ghp_ / github_pat_, GitLab glpat-, Slack xoxb- / xapp- and webhook URLs, Discord bot tokens and webhook URLs, SendGrid SG., Twilio SK…, Mailgun key-, Mailchimp, Resend re_, Square sq0atp- / EAAA…, PayPal (Braintree), Cloudflare Origin CA keys, Netlify nfp_, Hugging Face hf_, Groq gsk_, Telegram bot tokens, Google AIza… (outside a Firebase config), -----BEGIN … PRIVATE KEY-----public keys (pk_…, Supabase sb_publishable_ and the anon key, the apiKey inside a Firebase config), Stripe test keys, images, audio and other binary files

The key shapes are based on the public rule set of gitleaks (MIT License).

The error lists the file, the line and what was found ("the same text as the key you saved as OPENAI_API_KEY", "a secret key from Supabase (starts with sb_secret_)", "text that looks like a key") — only the first few characters, never the whole value, and only the name for a saved key.

Fix it: take the key out of the page code and use it only from server-side code. Ask your AI assistant to open the box for entering it, or run kumodeck functions secret put NAME; call the service from a Functions function with that key, and have the page call your function instead. Rebuild and deploy again.

Meant to be public? Some keys are designed for the browser — for example a Google Maps key that is restricted to your site (HTTP referrer restriction). A Google AIza… key used on a server (for example Gemini) is not: anyone could use it on your bill. The same goes when "text that looks like a key" is really an ID. If you are sure, deploy with kumodeck deploy --allow-secret-like (MCP: allowSecretLike: true). The version records what was allowed (file, line and kind — not the value).

Game engines#

A game engine's web export is a folder with an index.html: upload the folder as it is. KUMODeck sends .wasm as application/wasm, and pre-compressed files (game.wasm.br, game.js.gz, …) with the right Content-Encoding.

EngineWhat to uploadAnything extra
Unitythe Web (WebGL) build foldernothing. See Unity games
Godot 4the Web export, saved as index.htmlwith Thread Support on, a _headers file. See Godot games
GameMakerthe HTML5 export foldernothing
Constructthe Web (HTML5) export foldernothing
Defoldthe HTML5 bundle foldernothing
Bevy, macroquad and other Rust or Emscripten buildsthe folder with index.html, the .js and the .wasmif the build uses threads (SharedArrayBuffer), the same _headers file as Godot with Thread Support
Phaser, Three.js, PlayCanvas, PICO-8the built foldernothing

Unreal Engine 5 has no web export. A game that needs threads needs these two headers, whatever the engine:

/*
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp

How uploads work#

  1. The CLI hashes every file (sha256) and sends the manifest.
  2. The server answers with the hashes it does not have for this project — only those are uploaded (8 in parallel, retried).
  3. finalize + activate switch the live version atomically.

Redeploying a large app after a small change uploads only the changed files. Development and production share uploads, so promoting the same build costs nothing.

Caching#

FileCache-Control
*.htmlno-cache (revalidated every load — a deploy or rollback is visible immediately)
hashed files under assets/, static/, chunks/ (e.g. app.3f9a1c.js)immutable, 1 year
everything elsemax-age=0, must-revalidate (cheap 304s)

ETags are content hashes; Range and HEAD are supported. /x redirects to /x/ when x/index.html exists; a 404.html at the root is used for missing paths.

Security headers#

Each app is served from its own subdomain, separate from the API and the dashboard, so apps cannot read each other's storage or a developer's session. A permissive CSP keeps CDNs, eval and WebAssembly engines working while blocking plugins and insecure (http:) loads. There is no frame-ancestors rule, so you can embed your app or game on other sites such as itch.io. Development deployments send X-Robots-Tag: noindex.

Custom headers and redirects (_headers, _redirects)#

Put a _headers and/or _redirects file at the root of the folder you deploy. They use the same format and limits as Cloudflare (Pages / Workers Static Assets), so a folder that works there works here. The two files themselves are not served.

# _redirects — from  to  [status]
/old-page        /new-page.html      301
/blog/:slug      /posts/:slug.html
/docs/*          /manual/:splat      302
/play            /game.html          200
/discord         https://discord.gg/example
  • Status 301, 302 (default), 303, 307, 308, or 200 (rewrite: the URL stays, another file is served; paths on your site only).
  • * captures anything as :splat; :name captures one path segment. The query string is kept unless the destination has its own.
  • The first matching line wins; destinations on other sites must use https://. Redirects run before files are looked up.
  • For a single-page app use web.spaFallback: true in kumo.json — /* /index.html 200 is ignored (as on Cloudflare).
# _headers
/*
  Content-Security-Policy: default-src 'self' https:
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp
/assets/*
  Cache-Control: public, max-age=31536000, immutable
/embed.html
  ! X-Frame-Options
  • Every matching rule applies. You can replace the default CSP, Cache-Control and other headers, or remove one with ! Name.
  • KUMODeck keeps a few headers to itself: Content-Length, Content-Encoding, Content-Range, Transfer-Encoding, Connection, ETag, Accept-Ranges, Set-Cookie, Clear-Site-Data. Development deployments always send X-Robots-Tag: noindex. Content-Encoding is set for you on pre-compressed files (Game engines).
  • Paths that KUMODeck answers itself (/.well-known/… generated from kumo.json, /.auth/…, /.card…) answer before your rules.
  • On the shared /play/<slug>/ addresses (local development), redirects to other sites, Service-Worker-Allowed and Strict-Transport-Security are not applied, because those addresses share an origin with the API.
Limit (same as Cloudflare)Value
_headers rules100
_headers line length2,000 characters
_redirects static rules2,000
_redirects dynamic rules (with * or :name)100
_redirects line length1,000 characters

Lines that cannot be read or go over a limit are skipped, not rejected. finalize (and, for server-rendered apps, activate) returns them in warnings with the line, the reason, and limit when a limit was exceeded. Server-rendered apps get the same files applied by Cloudflare itself.

Limits#

Limits KUMODeck chose (files per deploy, total size, one file, path length, and a server-rendered app's CPU time and subrequests per request) are being raised. When you pass one, the CLI message and the error's details.limit give the number. Why each exists and the way around it: Limits.

LimitValue
Files per deploy100,000 (same as Cloudflare Static Assets)
Total sizeno limit
Single file100 MB
Path length1,024 characters
Server-rendered app: asset files5,000 (see below)
Unfinished deploysa few per environment (too_many_pending_deployments), expiring after 24 h — so abandoned uploads cannot fill storage
Files never uploadedfiles and folders starting with a dot (except .well-known/) and node_modules — so a .env is never published
Server-rendered app: Worker64 MiB uncompressed (Cloudflare's own limit)
Server-rendered app: asset file25 MiB (Cloudflare's own limit)
Server-rendered app: per request30 s CPU, 10,000 subrequests by default (up to 5 min / 10 million with PUT …/functions/limits and app; CPU in effect grows with your prepaid balance, see Functions)

Over a limit, the API answers with a reason code such as 413 too_many_files or 413 file_too_large and details.limit (the exact limit). A server-rendered app's assets are re-sent to Cloudflare one by one when you publish, so they are capped at 5,000 for now (they will move to the same 100,000 as static sites once that upload can be split).

CI#

Skip kumodeck login and pass a secret key; the environment comes from the key:

KUMO_API_URL=https://api.kumodeck.com KUMO_SECRET_KEY=$KUMO_SECRET_KEY npx kumodeck deploy dist