Deploying Your Game
This page covers everything about getting your game live on RUN.world: logging in, deploying builds, publishing, versioning, and managing visibility.
Log into RUN.world
You'll need to log in before you can deploy. From your Terminal:
rundot loginThis opens a browser window where you can log in with your Google account. Any command that requires authentication will alert you if you aren't logged in.
To force a new login session:
rundot login --forceYour session info is stored locally in ~/.rundot/ (macOS/Linux) or %USERPROFILE%\.rundot\ (Windows).
CI/CD Authentication
For automated pipelines (GitHub Actions, GitLab CI, etc.), use a per-game API key instead of interactive login.
Managing keys with the CLI
API keys are scoped to a single game and can only be managed by the game owner. The easiest way is the CLI (run from a normal interactive rundot login):
rundot game api-keys create --label "GitHub Actions" --expires-in-days 90
rundot game api-keys list
rundot game api-keys regenerate --key-id <KEY_ID>
rundot game api-keys revoke --key-id <KEY_ID>create and regenerate print the secret (an opaque rk_-prefixed string) once — save it immediately. Key management is intentionally unavailable when you are authenticated with an rk_ key; it requires an interactive owner login.
For moderating live leaderboard data from the CLI (view scores, remove entries, shadow-ban cheaters), see Leaderboard Moderation (CLI).
Generating an API key (REST)
If you prefer to script it directly, the same operation over the REST API:
The response includes a secret field (an opaque rk_-prefixed string), save it immediately, it is shown only once.
Using the key
Or set it as an environment variable in your CI config and pass it inline:
Headless playground login (use a playground key)
For headless playground login — no Google Sign-In, nothing embedded in vite.config — do not reuse the deploy key above. Mint a dedicated playground key (a pk_… key — a distinct type from your rk_ deploy key) instead: it can only open a playground session and is rejected (403) by every deploy, marketing, content-generation, and spend endpoint, so it's low-risk to keep on disk. The one-command way:
This writes a git-ignored, 0600 .env.local containing RUNDOT_PLAYGROUND_KEY=pk_… (read by the SDK playground plugin — distinct from the deploy key RUNDOT_API_KEY above); then npm run dev signs in headlessly. Clean up with rundot playground revoke-access. The key validates against RUN.world, so it keeps working across playground's periodic data resets. This applies to the playground environment only.
See Testing Locally With Playground for the full flow, how the key is handled (it never reaches the browser), and the CI / secret-manager variant.
Key properties
Game scope
Single game only
Key type
Two distinct, prefix-typed credentials: deploy (rk_, minted by api-keys create / this REST endpoint — full game access) and playground (pk_, minted by rundot playground grant-access — playground-login only, rejected by every mutation/spend route). The type is intrinsic to the key's prefix.
Who can create
Game owner
Expiration
1–365 days (default 365 for both api-keys create and playground grant-access; override with --expires-in-days)
Revocation
Instant: DELETE /v1/games/<gameId>/api-keys/<keyId>
Regeneration
POST /v1/games/<gameId>/api-keys/<keyId>/regenerate (revokes old, issues new)
Max per game
10 active keys (unrevoked and unexpired; expired keys no longer consume a slot)
Security notes
Keys are stored as SHA-256 hashes server-side; a database breach does not expose raw keys.
If a key leaks, revoke it immediately via the API. The old key stops working instantly.
Keys cannot create or manage other keys (prevents leaked-key self-replication).
Build your game
Don't forget to create a new build before deploying. If you're using our templates:
This compiles your game into the ./dist folder.
Share a private link
rundot deploy uploads your game as a private build and gives you a private link to share. Anyone with the link can play, but the game won't appear on Explore or in search results.
The private link plays in any desktop browser or in the RUN.world app.
Publish your game
Publish always means public. When you're ready for your game to appear on Explore and in search results on the RUN.world platform:
Or set visibility separately after deploying:
Every submission must be a new version, higher than the one that is already public (like an app store update). rundot deploy bumps the version for you; submitting the version that is already live is rejected. To ship a change to a live game, run rundot deploy --public again.
Multiplayer games: rooms already running keep the server bundle they started on. rundot deploy prints how many are still on the older bundle; close them with rundot rooms close --outdated, or deploy with --close-rooms to do it in one step. See Multiplayer rooms.
Managing visibility
Your game can be:
Public: Visible on the RUN.world Explore page
Private: Hidden from Explore and search, but playable by anyone you share the private link with. Great for testers.
Make the game private (hide from Explore; the private link keeps working):
To see all visibility options:
Controlling version numbers
rundot deploy increments your game's version automatically.
Use --bump to control versioning:
major: 1.0.0 → 2.0.0 (breaking changes)minor: 1.0.0 → 1.1.0 (new features) (default)patch: 1.0.0 → 1.0.1 (bug fixes)
Release notes
Beta.
--changelogand--announceare currently beta features. They're hidden unless you opt in by settingRUNDOT_BETA_FEATURES=1in your environment; without it the CLI rejects these flags and every deploy is a minor release.
Tell your players what changed in an update. Pass --changelog on deploy to attach release notes to the version:
Release notes are written in Markdown and render on your game's About tab, newest version first. Players can read the full history there.
Announced vs. quiet releases
By default a deploy is a quiet release: the changelog shows up on the About tab, but nobody is actively notified. When you ship something worth shouting about, add --announce:
An announced public release notifies your existing fans — players who liked your game get a message in their in-app inbox, and dormant players may receive a push notification (subject to a per-game weekly cap so they're never spammed). A quiet release only updates the release-notes display.
Images in release notes
You can embed images in your Markdown changelog, but they must be hosted in your game's own CDN bucket (the same bucket your build uploads to). Images from other origins are rejected by moderation and won't render. All release notes — text and images — pass through content moderation before they're shown to players.
Muting (for players)
Players who don't want update notifications for a specific game can tap Mute updates in the game's Release Notes section. They'll still see the release notes if they visit the page, but they won't get inbox or push notifications for that game's future releases.
Advanced options
Deploy command options:
--game-id: The game ID to deploy (reads fromgame.config.prod.jsonif not provided)--build-path: Path to your game's distribution/build folder--bump: Version bump type:major,minor, orpatch(default:minor)--uses-preloader: [Deprecated] Whether the host keeps its loading screen up until your game callshideLoadScreen()--public: Make this version visible on the Explore page--changelog: Markdown release notes for this version (shown on the About tab)--announce: Announce this release to fans — an announced public release notifies fans via inbox + dormant push; default is a quiet release that only updates the release notes
What happens under the hood:
Zips the build from your game distribution folder
Uploads the new version to RUN.world storage
Creates a new version entry for your game
Updates the
privaterelease to point to the new versionOptionally sets the version as public (visible on Explore)
Returns a share link: the private link, or the public link once published
Device Pixel Ratio (DPR) Clamping & Mobile Performance
By default, RUN.world automatically clamps window.devicePixelRatio to 1.5 on mobile devices (iOS & Android, covering native app webviews and mobile web browsers) via the "maxDpr" setting.
Why DPR clamping is enabled by default:
Modern mobile screens routinely have DPR 2.6x–3.5x ($1260 \times 2800$ physical pixels). Full-resolution rendering forces mobile GPUs to allocate massive 4K backbuffers, causing severe thermal throttling, fill-rate stalls, and sub-30 FPS frame drops on mid/low-tier Android chipsets.
On iOS devices, excessive canvas memory allocation triggers WebKit Jetsam process termination (
onContentProcessDidTerminate), crashing the game session abruptly.Clamping DPR to
1.5reduces GPU backbuffer allocation and fill-rate by ~75%, stabilizing frame rates at 60 FPS while remaining visually crisp at standard mobile viewing distances.
Customizing or Uncapping maxDpr: You can customize the maximum DPR ceiling by setting "maxDpr" in game.config.prod.json:
1.5(default): Recommended for optimal battery, thermals, and stable 60 FPS on mobile GPUs.2.0: Crisp high-density resolution for lighter 2D canvas games or games with fine vector typography.3.0(or native): Leaveswindow.devicePixelRatiountouched at the device's native resolution.
Build Size Limits
Game bundle (zipped dist/ output)
100 MB
Server bundle (server-authoritative simulation code)
5 MB
The 100 MB game-bundle cap is the server-side default and is the binding constraint at upload; contact RUN.world ops if you need it raised. The 5 MB server-bundle cap is enforced by the Vite multiplayer plugin and is overridable via its maxBundleSize option. To stay under the limits:
Tree-shake and minify your client build.
Compress and dedupe assets (textures, audio, fonts).
Keep server-authoritative code lean; it ships separately from the client bundle.
Image content check
Every deploy checks the images in your build and in your CDN assets before they are uploaded. A deploy that contains sexual content is refused. Nothing from that build is published, and the CLI names each file that caused the refusal:
The check reads the file contents, not the file name. Renaming an image does not skip it.
Every frame of an animated GIF or WebP is checked, up to 120 frames.
Animated PNG (APNG), animated AVIF, HEIC, JPEG XL, and SVG files with animation, scripts, or
foreignObjectcannot be checked. Use PNG, JPEG, GIF, WebP, or a static SVG instead.Images that were checked before are not checked again, so a redeploy with the same art is fast.
If the CLI says the check could not run, try the deploy again.
Advanced game configuration
For more granular control, use rundot game ... subcommands:
game set-name
game set-description
game set-keywords
Always set keywords on your game. Keywords (a.k.a. tags) are the single biggest lever you control for visibility and discoverability on RUN.world. They:
Power in-app recommendations: the recs engine uses tags to decide which players see your game.
Drive in-app search: players who search "cozy" or "puzzle" only find games tagged that way.
Generate a public SEO slug page at
https://run.world/tags/<keyword>for every keyword, listing every game with that tag: free organic traffic from Google.
A game with no keywords is effectively invisible to the recs engine and to search.
Keywords are comma-separated and replace the full list each time. Running set-keywords again with a new list overwrites the previous one.
game delete-keyword
Remove a single keyword from your game without touching the others.
game list-versions
game add-editors
game remove-editors
All game subcommands accept --game-id to target a specific game (reads from game.config.prod.json if not provided).
Last updated