Skip to main content

Building Cauldron decks locally

Castle normally runs your Cauldron workspace for you, in the editor on castle.xyz and in the Castle app. If you'd rather work on your own computer, install castle-web, the Cauldron command-line tool from the castle-web-cli npm package. It opens the same Play, Files and Parameters panels in your browser, while you edit the deck with your own tools.

note

The castle-web tool is different from the Castle CLI, which works with classic decks.

Setup​

You need Node.js. Install the tool, then sign in with your Castle account:

npm install -g castle-web-cli
castle-web login

Making a deck​

castle-web init my-deck                    # starts from the 2D Scene Editor kit
castle-web init my-deck --kit physics-3d
castle-web init my-deck --remix <deckId> # starts from a published deck

init creates the deck, installs its dependencies, and starts a local server; open the URL it prints. Pass --no-serve to skip starting the server. See Kits for the kits you can start from.

What's in a deck​

my-deck/
castle.json the deck's id, title, imports, editor settings and server settings
package.json npm dependencies
index.html
... your scenes, blueprints, behaviors, art and code
imports/ other decks this one builds on, including its kit (read-only)
.castle/ local state: server logs, screenshots, generated guides

A deck made from a kit also has a CLAUDE.md file, and an AGENTS.md link to it, explaining how the kit works. AI coding assistants such as Claude Code and Codex read these automatically.

Running the workspace​

castle-web serve (and init, which runs it for you) starts the workspace on localhost, so only your own computer can open it. To open it from a phone or another computer on your network, pass --lan, or --host <address> for one address:

castle-web serve my-deck --lan

The local workspace has no sign-in of its own. With --lan or --host, anyone who can reach the address can open the editor, read and change the deck's files, and run commands in its terminal as you. serve prints a warning when it starts this way. Use it only on a network you trust.

Commands​

These are the commands you'll use most. Run castle-web --help to list all of them and their options, or castle-web <command> --help for one.

CommandWhat it does
castle-web serve [dir] [--lan]Starts the local workspace for a deck.
castle-web restartReloads every open panel.
castle-web screenshotSaves a screenshot of the running deck.
castle-web check [dir]Builds the deck and its server the same way publishing does, to catch errors early.
castle-web install [dir]Installs the deck's npm dependencies.
castle-web save-deck [dir]Publishes the deck to Castle.
castle-web logs [dir]Shows a published multiplayer deck's latest server session: how it ended and its last log lines. --rooms lists recent sessions.
castle-web reset-leaderboards [dir]Clears every leaderboard on the deck and keeps its saved data. --undo puts the scores back, for up to a day.
castle-web get-deck [dir] [--deck-id <id>]Downloads a deck's source from Castle. Without --deck-id, it uses the id in castle.json.
castle-web list-decks [--kind mine|saved|kits]Lists decks this one could import.
castle-web add-import <deckId|url|kit>Adds another deck as a read-only dependency under imports/.
castle-web update-import [alias]Updates imports to their latest version.
castle-web fork-import-file <path>Gives this deck its own copy of one imported file.
castle-web revert-import-file <path>Drops that copy and goes back to the import's file.
castle-web save-version -m <message>Saves a version of the deck.
castle-web list-versionsLists saved versions.
castle-web restore-version <version>Restores a saved version.

Publishing​

castle-web save-deck bundles the deck into a single file, uploads it along with its server if it has one, and publishes it at castle.xyz/d/<deckId>. The first save creates the deck and writes its id into castle.json.

If someone else has saved the deck since your folder last synced with it, for example from the Cauldron editor, save-deck refuses rather than overwrite their work. Run castle-web get-deck --side to fetch the saved copy into .castle/ beside your files and compare, or pass --force to save over it.

To guard against a save that silently loses something, pass --refuse-drops, or set "saveGuard": { "refuseDrops": true } in castle.json. save-deck then compares your folder with the deck's saved source and refuses, saving nothing, if your folder is missing a file the saved deck has, or a key or non-empty value inside one of its JSON files. It lists each missing piece. When a removal is on purpose, name it with --allow-drop <path> (or --allow-drop "<path>#<pointer>" for one value inside a JSON file); you can repeat it.

A new deck saved from the command line is Unlisted, so only people with the link can find it. Later saves keep whatever visibility the deck has. Pass --visibility private or --visibility unlisted to change it. To make a deck Public, change its visibility in the deck's settings (see Save and publish).

Back to What is Cauldron?