Quickstart

Deploy your game folder to a private preview, where only you can play it as OpenGame hosts it. The creator platform is internal-only for now, so you need an invitation from the OpenGame team.

Before you start

Get these from the person who invited you:

An account with internal access.
The CLI and SDK tarballs, opengamehq-cli-<version>.tgz and opengamehq-sdk-<version>.tgz.
Your origin: the https:// address the CLI signs in and uploads to. It is not opengame.io, which serves the agent guide but doesn’t take uploads yet.
A starter folder, if you want a starter and don’t have the OpenGame repository.

You also need:

Node.js 20.19, or 22.12 or later, for a starter, because that is Vite 7’s floor. A game you bring needs only the CLI’s floor, Node.js 18.17. Run node --version to check.
A game with index.html in its build output, or a starter from the next section.

No game yet? Copy a starter

A starter is a small game with opengame.json and the SDK already set up. Pick three-vite, phaser, react or javascript. With no preference, pick three-vite, a game called Orb Run; the others share the placeholder title Target practice. Use the install blocks below. They replace the starter’s repository-only SDK path with the tarball you downloaded. A plain npm install leaves the SDK missing without an error.

From the repository
From a starter folder

The starters are in the repository’s templates folder. Change the first four lines before you paste the block: REPO is your copy of the repository, TARBALLS is the folder you saved the tarballs in, STARTER is the starter you picked, and GAME is a new folder for your game, which must not exist yet.

REPO=~/opengame
TARBALLS=~/Downloads
STARTER=phaser
GAME=~/my-game
cd "$REPO/templates" &&
cd "$STARTER" &&
mkdir "$GAME" &&
cp -R . "$GAME" &&
cd "$GAME" &&
npm install "$TARBALLS"/opengamehq-sdk-*[0-9].tgz

Each line runs only if the one before it worked. A wrong REPO or STARTER, or an existing GAME, stops the block before anything is copied or installed. If only the last line fails, If a command fails covers it.

Move the folder the team sent you to where you want your game. Set GAME to that folder and TARBALLS to the folder you saved the tarballs in, then paste the block.

GAME=~/my-game
TARBALLS=~/Downloads
cd "$GAME" &&
npm install "$TARBALLS"/opengamehq-sdk-*[0-9].tgz

The *[0-9].tgz pattern skips a duplicate download such as opengamehq-sdk-0.1.0 (1).tgz. If you saved more than one version, use the newest file’s full name. npm saves the tarball’s path relative to the game folder, so if you move either one, run the npm install line again. For other engines, Engine support links each engine’s guide, which names its starter or export recipe.

Create your preview

Pick how you want to work. Both end with the same private preview.

With an agent
In your terminal

Open your game folder in Claude Code, Codex, Cursor or any coding agent that can run commands, and paste this prompt:

Deploy this game to OpenGame as a private preview.
If the CLI is missing or out of date, ask me for the internal CLI tarball.
Read https://opengame.io/for-agents.md, then follow the AGENTS.md in that CLI package.
Ask me for the internal OpenGame origin.
Sign in only with my approval.
Fix confirmed game findings.
Give me the private preview link.
Submit only if I ask.

The agent asks for the CLI tarball and your origin. The prompt on your origin’s /upload page has both filled in, so you can paste that one instead.When the agent signs you in, it gives you a link and a code in two groups of four, such as KTWQ-7MHP. Open the link, type the code, then press Allow access, which stays greyed out until the code matches.You’re done when the agent gives you a preview link. Open it while signed in to the same account. The agent guide is what the agent follows.

Install the CLI

Paste this block. If you saved the tarballs somewhere other than Downloads, change the first line. Delete any older opengamehq-cli tarball first, or npm installs both.

cd ~/Downloads &&
npm install -g opengamehq-cli-*[0-9].tgz

Then run opengame version. It prints opengame and the version in the tarball’s file name, such as opengame 0.3.1. If npm stops with EACCES, see If a command fails.

Point it at your origin

Replace https://your-origin with the origin the team gave you. The setting lasts until you close this terminal, so to keep it, add the line to ~/.zshrc or ~/.bashrc too.

export OPENGAME_API_URL=https://your-origin

Without it, the CLI talks to opengame.io, which doesn’t take uploads yet.

Describe your game

Run this step and the ones after it from your game folder.If you copied a starter, skip init: the starter already has opengame.json. Open it and change title and description to your game’s.If you brought your own game, run:

opengame init .

init reads the title from index.html and the build command from package.json. Before it writes anything, it may ask a few things. To skip the questions, give the answers in the command: add --description "…", --genre <slug> and --kind <kind>.

A description, when package.json has no description of 40 to 500 characters. Press Enter to skip.
A genre, from a menu, when it can’t guess one from the title and description. Move with the arrow keys and pick with Enter. Decide later is already highlighted, so Enter skips it.
What you are making: a game, a world, a decomp or a mod, each with a line that says what it means. Game is already highlighted, so Enter makes a game. Use the arrow keys to pick another.
Which game it is based on, for a decomp or a mod, such as Doom. You can’t skip this one, because a mod has to say what it changes. In the command, that is --kind mod --based-on "Doom".

Then it writes opengame.json. If a field is still missing or invalid, it prints Created a draft opengame.json. and names the field. Open the file and check three fields:

description: 40 characters or more on what the game is and how it plays.
genre: if it is wrong, opengame check lists the valid slugs.
build.output: the folder your build writes index.html into, such as dist.

Try it locally (optional)

opengame dev . --build

This builds the game and serves it at a local address with the same headers it gets on OpenGame. Open the address it prints. If the game includes an SDK, platform services run as a local mock, so you send no data to OpenGame here. The starters include the SDK package, and a copy of opengame-global.js works the same way. opengame dev adds no SDK, so a game without one has no window.OpenGame here. Press Ctrl+C to stop.To find problems before you upload, run the local checks on their own. OpenGame’s checks still run when you deploy.

opengame check . --build

Deploy

opengame deploy .

Deploy builds the game, checks it and uploads it, up to 200 MiB zipped (see the limits). The first time, it signs you in: a page opens in your browser, or use the link it prints. Type the code the terminal shows, and press Allow access. Once the upload is in, it prints the address of your deploy’s page and returns, while OpenGame’s checks run. The page shows each check as it runs, and Play once the preview is ready. To wait in the terminal instead, run opengame deploy . --wait.

Play the preview

Open Play on your deploy’s page, signed in to the same account, or run opengame open.The link has no expiry of its own. It keeps working while the release is one of your game’s 10 newest, and each visit starts a preview session that lasts 1 day. Check that the game loads, the controls work, it resizes and the sound plays.

If a command fails

Find the message the CLI or npm printed, open its entry, and do what it says. Most entries start with the code that --json output reports for that error. The last two have no single code, because they cover any finding about your game and any check that failed on OpenGame’s side. The repair guide covers every finding and exit code, and For agents covers --json for scripts.

npm error code EACCES

npm install -g couldn’t write to npm’s global folder, because your system owns that folder, not you. The CLI was not installed. Don’t rerun it with sudo. Give npm a global folder you own:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

npm config set is saved for later shells, and the export command is not. Add the export command to ~/.zshrc or ~/.bashrc too, so new shells find opengame.Then install the CLI again, changing the first line if you saved the tarballs somewhere other than Downloads:

cd ~/Downloads &&
npm install -g opengamehq-cli-*[0-9].tgz

no matches found, or npm fails with ENOENT

The SDK install couldn’t find the tarball, because TARBALLS isn’t the folder you saved it in. zsh prints no matches found. In bash, npm warns that the file seems to be corrupted, then exits with ENOENT. The starter is already copied and you are in the new folder, so don’t paste the block again: set TARBALLS to the right folder and run the npm install line on its own.

The OpenGame API is not available at an address

api_unavailable. If the address is https://opengame.io, this shell has no OPENGAME_API_URL, so the CLI used opengame.io, which doesn’t take uploads. Set it as in the terminal tab’s second step, then run the command again. If the message names your origin instead, check the address with the team.

Could not reach the OpenGame API at an address

network. The same fix applies when the CLI prints The OpenGame API at and an address, then sent an answer this CLI could not read. The CLI got no answer from the address it names, or got a page it couldn’t read, such as a proxy’s sign-in page. Most often that address is wrong: a typo, or https://your-origin from the terminal tab’s second step pasted as written. Run echo "$OPENGAME_API_URL", compare it with the origin the team gave you, and set it again. If the address is right, check that you are online, and that HTTPS_PROXY is set if your network needs a proxy. Then run the command again.

Claim a handle on OpenGame, then try again

handle_required. The account you signed in with has no handle yet, and every account that uses the CLI needs one. Claim it at opengame.io/handle, then run the command again.

Uploads are not open yet

uploads_closed. Signing in, previewing and reading your games all work, but OpenGame isn’t taking new uploads yet. Nothing was uploaded. The message names the day uploads open when there is one; run the command again then.

opengame.json already exists

manifest_exists. The folder already has a manifest, as every starter does, so init left it alone. Skip init and edit opengame.json to change the game’s details, or run opengame pull to get changes made on the website.

The checks are still running

checks_pending. deploy --wait or status --watch stopped waiting after 5 minutes. Your upload is safe and OpenGame’s checks carry on. Open your deploy’s page, or run opengame status --watch to follow them.

The upload did not finish

upload_interrupted. The connection dropped on every try. Your saved upload can be resumed. Keep the .opengame/ folder, check your connection and run opengame deploy . again. It resumes the same upload, or starts a fresh one if the old one has expired.

A finding about your game

Something in the build needs a change. Each finding names the problem, usually with a file and line, and the fix. Make the change, run opengame check . --build, then deploy again.

A check failed on OpenGame's side

The problem is ours, and your game is fine, so don’t change it. Wait a few minutes, then run the command the error names, or the same command again.

Submit for review

When the preview plays the way you want, run opengame submit from the game folder. Each deploy makes a new release, and submit takes the newest one once its checks have finished and it is ready. If that release isn’t ready, submit stops and names the command to run. Otherwise it asks you to confirm the release, then for any jam details. The first time you submit a game, you certify in your browser that you have the rights to everything in it. A reviewer then plays it and approves it or asks for changes. The game becomes public when the reviewer approves and publishes it. Enter a jam covers tracks, rules and following the review.

Keep building

Package your game

What goes in the folder and the manifest, and the upload limits.

Connect the SDK

Read the player, handle guests and respond to sign-in.

Add a leaderboard

Declare a board, submit scores and show results.

Update a live game

Preview a new release while players keep the published one.

Start

Guides

Reference

Before you start

No game yet? Copy a starter

Create your preview

If a command fails

Submit for review

Keep building

Package your game

Connect the SDK

Add a leaderboard

Update a live game

​Before you start

​No game yet? Copy a starter

​Create your preview

​If a command fails

​Submit for review

​Keep building

Package your game

Connect the SDK

Add a leaderboard

Update a live game

Before you start

No game yet? Copy a starter

Create your preview

If a command fails

Submit for review

Keep building