Connect your game

Use sandscape init when you already have a browser game on your computer and want to add it to Sandscape.

From the game folder:

sandscape init . --name "Neon Drift"

Or pass the folder from its parent directory:

sandscape init ./my-game --name "Neon Drift"

init creates a project, connects the local folder to it, and uploads the files that are not excluded. It also registers recognized images, 3D models, and audio files as Sandscape assets without charging coins.

After init succeeds, the folder works with pull, push, and publish. The file .sandscape/project.json records the connection.

Check the entry point

Sandscape serves index.html from the root of the connected folder. Keep that file at the root. The rest of the game can use any folder structure.

You can connect a folder without index.html, but you cannot publish a playable build until the file exists and has been pushed.

Set the project name

Use --name for the title you want to see in your Sandscape project list. If you omit it, the CLI derives a name from the folder. For example, train-game becomes Train Game.

Passing the real game title avoids having to rename a generic folder later.

Review ignored files before you connect

init and push read .gitignore and .sandscapeignore from the project root. A matched file stays on your computer and is not uploaded.

Before running init:

1. Add a root .gitignore if the project does not have one. Exclude dependencies, build output, logs, and scratch files.
2. Check that your game assets, concept art, reference material, and source files are not ignored. Add a negation rule such as !reference/hero.png when needed.
3. Put files that should remain in git but should not go to Sandscape in .sandscapeignore.

Only the ignore files at the project root are read. Nested .gitignore files do not affect the upload.

The CLI always excludes:

• node_modules, .git, .sandscape, .ssh, .aws, and .gnupg directories
• CLI and coding-agent files such as CLAUDE.md, AGENTS.md, .claude, .agents, .codex, and .cursor
• Credentials such as .env, private key files, .npmrc, .netrc, and credentials.json
• Symlinks

You cannot add an always-excluded path back with a negation rule. The CLI reports ignored paths and credential-shaped files before the upload completes. Read that summary if the uploaded file count looks wrong.

See What syncs and what does not for the complete rules.

Optional AI description pass

sandscape init . --name "Neon Drift" --backfill

--backfill asks Sandscape to read the imported game and create a platform-side design with its concept, art style, asset descriptions, and development plan. This makes the project easier to continue in the web app.

The CLI shows the estimated coin cost and your current balance before the pass starts. The file import itself is free. Only the optional backfill costs coins.

If backfill cannot run, the import can still succeed. The files remain on Sandscape and the folder remains connected. The error message will tell you whether the account lacks access or coins.

Import errors

• If init says the folder is already a Sandscape project, use sandscape push instead.
• If a file is missing after the import, check the ignore summary and the root ignore files.
• If the import exceeds a size limit, split the upload or exclude local-only source material. See Transfer limits.