Fresh setup: from zero to a live hot-swap

This guide sets up a new TypeTorch game from the starter template and ends with a live server that hot-swaps while you play. Every step ends with Check: what you should see when it worked.

The quick way: typetorch init

With Bun installed, run this in an empty folder (CLI 0.10+; with the CLI installed globally, typetorch init or tt init):

bunx @typetorch/cli init

It asks one question at a time and walks through steps 1 to 11 below. It does the terminal work itself, and for the parts that happen in Creator Hub (creating the experience, the API key) it links the exact page and checks the result. Each step says why it exists, links the section below that it replaces, and checks its result the way typetorch doctor would. Every upload, deploy and SSH session gets its own y/N.

Step	What it does
1. tools	checks Bun, git and Rokit (offers to run Bun's install script)
2. project	clones the template (into this folder when it is empty, else into a new subfolder named after the project), drops the template's origin, runs bun install, rokit install and a first typetorch build
3. roblox	reads your experience from its Creator Hub URL (the creator comes from Roblox), probes the Open Cloud key and writes it to .env, finds your user id from your Roblox username (a group game; a user-owned game takes the creator), then shows and writes typetorch.json and commits it
4. keys	keys init and keys init --fallback (step 7), then commits typetorch.json
5. kernel	an empty place: kernel deploy --dry-run, then --replace-place --yes; a place with Studio content: kernel deploy --install (a patch, which needs the place setting "Allow place to be updated using Save Place API")
6. backend	optional, below
7. deploy	commits, deploys main (prod), offers a dev branch and deploys it, then access push
8. agent	writes AGENT_PROMPT.md

The typetorch.json it writes maps git main to prod and git dev to dev, sets "approval": "prod", and makes you the only member, as owner. A folder that already holds a roblox-ts game stops at step 2: moving a game is a migration.

The scope list init shows for the Open Cloud key leaves out universe.place:write, but --replace-place in its kernel step publishes a place file and needs it. Add it to the key for an empty place (the full scope list is in step 6 below).

• Optional backend. The backend step can set one up for you: on a VPS with Coolify, on a VPS without Docker (a systemd service with Caddy in front, your domain or a free sslip.io name), or on this PC behind a free Cloudflare quick tunnel. It can also point the game at a backend you already run, or skip it. typetorch init --teardown removes what that step installed. See Live servers and alerts.
• Agent prompt. The last step asks what your game is, then writes AGENT_PROMPT.md: what is set up and the rules from the agent playbook, for your coding agent's first message. typetorch init --agent prints it again. When claude is on your PATH, it offers to add the typetorch/claude-plugin marketplace and start Claude Code with that prompt.
• Package versions. init itself runs the CLI you started it with, but the game gets the versions the template pins, which are behind npm today (take the newest versions). Afterwards bun run typetorch ... runs the game's own CLI.
• Stopped half way? Run it again. It continues at the first unfinished step (progress is in .typetorch/init.json, which never holds a secret).
• Already set up? In a game that already has typetorch.json, bun run typetorch init checks what each step left behind (tools, dependencies, the Open Cloud key, the key files, the backend, the dev branch). It lists what is missing or broken and offers to run that step again. --phase <name> runs again from that step (preflight, project, roblox, keys, kernel, backend, deploy, agent).
• Scripts and tests. --answers <file> replays the answers from a JSON array of strings. Secrets never come from that file: they come from the environment or .env. --dir <folder> starts somewhere other than the working directory.

The steps below are what init does, by hand. Use them as the reference when a step fails, or to set things up yourself.

By hand

You need about an hour. Steps 3 to 9 are done once per game.

Who does what. Some steps need the account that owns the experience. For a group-owned game that is the group owner (or a member whose group role may create assets and publish places). They are marked (owner).

1. Install the tools

Tool	Why	Install
Bun 1.3+	package manager; runs the builds	PowerShell: powershell -c "irm bun.sh/install.ps1 | iex"; bash: curl -fsSL https://bun.sh/install | bash
git	every build is identified by its commit	your OS package manager
Rokit	pins Rojo and Lune per project	the Rokit releases page, then rokit self-install
Roblox Studio	creating the experience, settings, testing	create.roblox.com
TypeTorch Studio plugin (optional)	only for testing in Studio with typetorch serve	TypeTorchSync.rbxm from the studio-plugin releases into Studio's plugins folder

roblox-ts, Rojo and Lune are installed per project in step 2. Two more per-project tools, added in the game folder after step 2:

Tool	Why	Install
darklua	the production pack (CLI 0.17+): strips comments and whitespace from the payload that build, upload and deploy make. Without it every build warns darklua not found: this payload isn't minified and uploads the unpacked code	rokit add seaofvoices/darklua (the template's rokit.toml doesn't list it yet)
goblox (optional)	a Go port of roblox-ts, several times faster; typetorch build uses it when it is installed (CLI 0.16+, Compiler). The template's build script ends with rbxtsc, so each build then warns and runs goblox directly; end the script with goblox instead. goblox doesn't run the template's rbxts-transform-debug plugin: move the macros first (Debug macros)	bun add -d goblox

Check:

bun --version
git --version
rokit --version

Each prints a version (Bun 1.3 or newer).

2. Get the code

Clone the template and install:

git clone https://github.com/typetorch/template my-game
cd my-game
git remote remove origin
bun install
rokit install

• bun install gets every TypeTorch package from npm: @typetorch/framework and @typetorch/kernel, and as dev dependencies @typetorch/transformer, @typetorch/cli and @typetorch/dev-server. It also installs roblox-ts.
• rokit install installs Rojo and Lune at the versions pinned in rokit.toml.
• bun run typetorch <command> runs the CLI (the template's "typetorch": "typetorch" script). Without installing, npx @typetorch/cli <command> runs the same CLI. The CLI runs on Node 20+ or Bun; builds still need Bun.
• Run the compiler through bun run build (or bunx rbxtsc). In a Bun project on Windows, npx rbxtsc runs an unrelated placeholder package.

Check:

rojo --version
bun run build
bun run typetorch build

• rojo --version prints 7.7.0-rc.1 inside my-game.
• bun run build compiles with no errors.
• bun run typetorch build prints a built <id> (branch ..., channel ...) line, then .typetorch/payload.rbxm ... modules, and sources template <commit>, framework v<version>, kernel v<version> (the npm versions you installed). A newer CLI also prints a compiler line (rbxtsc <version> or goblox <version>).

Take the newest versions

The template's versions are behind. Its bun.lock installs these, not the newest on npm:

Package	The template installs	npm (2026-11-15)
@typetorch/framework	0.5.0	0.7.1
@typetorch/kernel	0.5.1	0.5.7
@typetorch/cli	0.9.1	0.18.1
@typetorch/transformer	0.2.1	0.3.2
@typetorch/dev-server	0.2.3	0.3.3

Many commands in these docs need a newer CLI (typetorch serve needs 0.11+), live reload in Studio needs kernel 0.5.4+, and step 8 publishes the kernel from node_modules/@typetorch/kernel. So update before step 8:

bun add @typetorch/framework@latest @typetorch/kernel@latest
bun add -d @typetorch/cli@latest @typetorch/transformer@latest @typetorch/dev-server@latest
rokit add seaofvoices/darklua
bun run build

The template's studio.project.json (Studio testing) doesn't map the kernel's RemoteDebug, Bundle and LiveDebug modules, so a playtest warns TypeTorchKernel.<name> is missing and runs without them. Add them under ServerScriptService.TypeTorchKernel as node_modules/@typetorch/kernel/place.project.json maps them.

Commit the changed package.json, bun.lock and rokit.toml. Later, bun run typetorch update moves the CLI alone to the newest version (it asks first; --check only shows the versions).

A game set up with typetorch init already has the template's kernel in its place. After the update, bun run typetorch kernel deploy --dry-run, then bun run typetorch kernel deploy, patches the newer kernel in (Kernel updates). The patch needs the place setting Allow place to be updated using Save Place API on and no Team Create session.

Unreleased framework or kernel changes (optional)

Skip this unless you need a framework, kernel or transformer change that isn't on npm yet. Clone those repos next to your game:

games/            any folder
  my-game/        your game
  framework/      https://github.com/typetorch/framework
  kernel/         https://github.com/typetorch/kernel
  transformer/    https://github.com/typetorch/transformer

From the games folder:

git clone https://github.com/typetorch/framework
git clone https://github.com/typetorch/kernel
git clone https://github.com/typetorch/transformer
cd framework
bun install
cd ../transformer
bun install
cd ../my-game
bun run packages
bun run build

• bun run packages builds ../framework and ../transformer, packs all three into .typetorch/packages/, and extracts them over node_modules/@typetorch: a local override of the npm versions. Run it again after you pull or change a checkout.
• The override stays on across bun install until bun run packages --off, which deletes it and reinstalls the npm versions.
• With the override, typetorch build stamps the checkouts' commits as the payload's sources (framework <commit>, kernel <commit>) instead of the npm versions.
• On Windows with git's core.autocrlf on, --off can rewrite bun.lock with other line endings, so the next build id ends in -dirty. git checkout -- bun.lock makes the tree clean again.

3. Create the group and the experience (owner)

A group-owned game is the usual setup: the payloads, the key asset and the hot assets are uploaded to the group, and LoadAsset only loads assets that the experience's owner owns.

1. Create a group on Roblox, or use your existing one.
2. In Studio: File > New > Baseplate, then File > Publish to Roblox As.... Pick the group as the creator and create a new experience. (The kernel deploy in step 8 replaces this baseplate.)
3. In Creator Hub, open the experience's "..." menu and use Copy Universe ID and Copy Start Place ID.

Check: you have two numbers, the universe id and the place id, and the experience shows the group as its creator.

4. Experience settings (owner)

In Studio, with the place open: File > Game Settings > Security.

Setting	Value	Why
Allow HTTP Requests	on	the kernel's live server reports (fleet API), analytics, and the Claude tab (remote-claude). The kernel place file turns it on too
Enable Studio Access to API Services	on	Studio playtests read branch heads and DataStores
Allow Mesh / Image APIs	optional	only for images Claude shows in the chat; the owner must be 13+ and ID-verified
Allow Loading Third Party Assets	optional	only for remote-claude Toolbox inserts. It applies to every server of the experience

ServerScriptService.LoadStringEnabled (not in Game Settings, in Studio's Properties) turns loadstring on for the whole place. Only remote-claude's run_luau needs it, on dev servers. Turn it on only in a place where you want run_luau (a test place); keep it off in a live game.

• kernel deploy patches (--place-file, CLI 0.7.3+) leave your place's value as it is.
• kernel deploy --replace-place (step 8) publishes it off (CLI 0.7.5+; older CLIs with a kernel up to 0.3.5 publish it on: turn it off in Studio afterwards if this place won't use run_luau).
• kernel deploy --loadstring (CLI 0.7.5+) turns it on on purpose, in both modes: use it for a test place where you want run_luau.
• bun run typetorch doctor reports it (loadstring).

Check: the settings stay on after you reopen Game Settings.

5. typetorch.json

The template's typetorch.json belongs to the template's own test game. Replace it with yours:

{
	"project": "my-game",
	"universeId": 1234567890,
	"placeId": 9876543210,
	"creator": { "groupId": 1234567 },
	"defaultBranch": "prod",
	"branches": { "main": "prod" },
	"channels": { "prod": "prod" },
	"members": { "111111111": "owner" },
	"devBadgeId": null,
	"approval": "prod",
	"kernel": "node_modules/@typetorch/kernel"
}

Remove the template's signingPublicKeys, keyAssetId and fallbackPublicKey: step 7 writes yours.

Field	Meaning
project	a short name, used in asset names
universeId, placeId	your experience (step 3)
creator	the experience owner: { "groupId": … } or { "userId": … }. Payloads are uploaded to it
defaultBranch	the branch public servers run (prod)
branches	git branch → TypeTorch branch. Unlisted git branches map to their own name, lowercased, / → -
channels	TypeTorch branch → prod or dev. Unlisted: prod for defaultBranch, dev for everything else
members	Roblox user id → owner or dev (who gets the dev menu; see step 11). The old role admin counts as dev. Servers see it after typetorch access push
revoked	optional: user ids that lose dev access
devBadgeId	optional badge id; its holders are devs
approval	all (default): every deploy waits for your y/N; prod: only prod-channel deploys do; none
kernel	the kernel folder for kernel deploy (node_modules/@typetorch/kernel, or a kernel checkout)
signingPublicKeys, revokedKeys, fallbackPublicKey, keyAssetId	written by typetorch keys (step 7). Don't edit by hand
backend	optional, { "url": ... }: written by typetorch backend setup (Live servers and alerts); CLI 0.8's fleet key is read once, with a warning
health	optional, { "errors": 3, "window": 30, "rollback": true }, with "prod" / "dev" overrides: when a server rolls a new build back (kernel 0.3.7+; Set the health window)
autoRollback	optional, { "failedPct": 20 }: deploy --wait rolls the branch back at this % of failed servers (1-100; Wait and automatic rollback)
backup	optional, { "refresh": "auto", "healthyHours": 3 } (the defaults): a prod deploy or promote at your terminal makes the build it replaced the place's backup build, once that build ran healthyHours (0-168) with no failure; "off" leaves it to kernel deploy and typetorch backup refresh (The backup build)
compiler	optional, "goblox" or "rbxtsc". Unset: goblox when it is installed, else rbxtsc; TYPETORCH_COMPILER overrides it (Compiler)
notifications	optional: the experience notification kinds and caps that typetorch notify push sends to the backend (Notifications)

Unknown keys are ignored with a warning (unknown key "..." (ignored)). That includes minify, which the darklua warning suggests: CLI 0.18.1 doesn't read it yet, so use --no-minify on build, upload or deploy to skip the production pack.

Commit it:

git add typetorch.json
git commit -m "My game"

Check: bun run typetorch doctor lists typetorch.json as ok with your universe and place (key checks fail until step 6).

6. The Open Cloud API key (owner)

Create it in Creator Hub > Open Cloud > API Keys > Create API Key, as the group owner (or a member allowed to upload and publish for the group). A key acts with its owner's permissions.

Add these permissions and select your experience where asked:

CLI job	Commands	Scopes
assets	deploy, upload, promote (of an unfinished upload), test --cloud, keys init / rotate (the key asset), assets sync / status, doctor	asset:read, asset:write; Luau Execution universe.place.luau-execution-session:read and :write (the cloud test that runs before every prod deploy, hot assets, doctor's place check)
deploy	deploy, rollback, promote, approve, pin, keys rotate / resign, deployments, report; settings, backend setup, access push	universe-messaging-service:publish; DataStore universe-datastores.objects:read, plus :create and :update (the shared deploy number and the signed settings, below)
place	kernel deploy, kernel restore	Luau Execution (universe.place.luau-execution-session:read and :write: the place is patched in a task, no download), and asset:read to record the place version; universe.place:write to publish a place file: --replace-place (step 8), a --place-file copy, kernel restore <file>

• The shared deploy number. Every machine that deploys (your PC, a second PC, remote-claude) takes the next deploy number (#seq) from the game's DataStore: the kernel's records of past deploys, and a counter the CLI claims atomically. That's what the DataStore scopes are for. Without them a deploy uses only your PC's log (fine while you deploy from one machine), and the deploy warns and uses this machine's log only.
• Not needed: universe:write and universe:read (ConfigService). Since kernel 0.3.8 TypeTorch keeps no ConfigService keys: dev access, the fleet API and the analytics settings live in one signed settings record in the game's DataStore.
• Not available to API keys today: legacy-asset:manage, the download of a place file. kernel deploy doesn't need it: the default engine patches the place through Luau Execution. A copy (--place-file) is the fallback, see step 8. Creator Hub doesn't offer it for API keys.
• Set an expiry date, and add your IP under accepted IP addresses if you can.
• Everything runs from your machine. TypeTorch ships no CI for games, so the key never has to leave your PC.

Put the keys in the game repo's .env. It's gitignored by the template, and it's where the CLI reads secrets (typetorch.json holds everything else, CLI 0.9). Add one line, then save:

OPENCLOUD_API_KEY=<your key>

With the TypeTorch backend, two more lines go there: TYPETORCH_API_KEY=<the backend's game key> and TYPETORCH_ADMIN_TOKEN=<the backend's admin token> (then bun run typetorch backend setup --url <backend>). --env-file <path> or TYPETORCH_ENV_FILE (real environment) read another file instead of .env.

• One shared key (OPENCLOUD_API_KEY) is the simple setup. You may split it per job instead: OPENCLOUD_ASSETS_KEY, OPENCLOUD_DEPLOY_KEY and OPENCLOUD_PLACE_KEY (each falls back to the shared key).
• remote-claude reads the key the same way (environment, then the game repo's .env) and needs the shared key (OPENCLOUD_API_KEY); see remote-claude.
• Never commit a key, never paste it into chat or an issue, and never give it to an agent.

Check: bun run typetorch doctor. The key assets, key deploy and key place lines are ok (or warn with "shared"), and each scope ... probe is ok for the scopes you added. The messaging probe publishes one harmless message to the topic TypeTorch/doctor.

7. Prod signing keys

With kernel 0.3, public servers only run prod builds that you signed. Two key pairs do it: the main key (shown as Root Key in the dev menu) and the Fallback Key. Details: Prod signing.

bun run typetorch keys init
bun run typetorch keys init --fallback
git add typetorch.json
git commit -m "Prod signing keys"

• keys init writes the main key file ~/.config/typetorch/keys/<universeId>.key, creates the key asset (a small group-owned Model that lists the trusted public keys) and writes signingPublicKeys and keyAssetId into typetorch.json.
• keys init --fallback writes ~/.config/typetorch/keys/<universeId>.fallback.key and fallbackPublicKey.
• Back up both key files and the game repo's .env offline (an encrypted USB stick, or a password manager). They are plaintext and never leave your PC. Never put them in a repo. Before a live game depends on them, also split off an asset:write key and plan a rotation drill (Prod signing: back up and drill).

Check: bun run typetorch doctor shows both key files ok and matching typetorch.json, and the key asset as Approved.

8. Publish the kernel place (owner)

The kernel is the only TypeTorch code in the place. Today kernel deploy publishes the whole place from the kernel's place file: a baseplate, a spawn and the kernel. That is right for this fresh place.

bun run typetorch kernel deploy --dry-run
bun run typetorch kernel deploy --replace-place --yes

• The dry run runs the kernel's Lune syntax check, prints the kernel version and hash, and builds .typetorch/place.rbxl with your trust roots stamped: KeyAssetId, FallbackPublicKey and BootstrapHeads. Check the keys line shows your key asset id.
• --replace-place --yes publishes it. It refuses without the keys from step 7.
• Never use --replace-place on a place with Studio-built content: it wipes it (it stays in the place's version history). For such places kernel deploy patches only the kernel into the live place, with no download, when the place allows saving through the API (Creator Hub > Permissions); otherwise into a Studio copy. See migrate: install the kernel.
• Studio must not have the place open in Team Create while you publish: that returns 409.

Check: join the game from the Roblox app. Open the Developer Console (F9) > Server. You should see:

[TypeTorch] kernel <version> (API 1) on a public server, branch prod, signed deploys only (keys: key asset)
[TypeTorch] branch prod: nothing loaded (no verified, bootstrap or usable stored head); peers and the backup next, and waiting for a signed deploy

(<version> is the kernel you installed, for example 0.5.7. A kernel from the local override shows its commit: kernel <version>@<commit>.)

Type /tt status in chat: it answers (you are the owner, so you are a dev).

9. First deploy

Commit everything, stay in the game (keep that server running), then deploy from the main branch:

git status
bun run typetorch deploy --dry-run
bun run typetorch deploy

• main maps to the TypeTorch branch prod (prod channel), so the CLI builds a clean prod build (debug prints removed; packed with darklua when it is installed), uploads it, waits for moderation, runs the cloud test (the build boots headless in your place, about 11 s), then asks y/N. Answer y: it signs the message with both keys and publishes it.
• Then it waits up to 90 s for the servers' reports, and rolls the branch back by itself if the build fails on them (safe deploys). That needs the fleet API; until you set it up, the wait is skipped with a note.
• The CLI also stores the head in the game's DataStore (the durable head; it needs the deploy key's DataStore scopes from step 6), so servers that start later boot it even if none was running. Without those scopes only running servers get the deploy: keep one open for the first deploy.

Check:

• The CLI prints deployed #1 prod@<commit> -> <artifact id> (asset <id>) in ....
• In game, within a few seconds, the Target Rush pad and the lobby coins appear. You stay connected.
• /tt status shows the generation. The dev menu (step 11) shows your artifact with two verified badges.
• bun run typetorch deployments lists #1 with * (live).

10. A dev branch

git switch -c dev
bun run typetorch deploy

• dev is a dev-channel branch: unsigned, and with "approval": "prod" it publishes without a y/N.
• Public servers ignore it. In game, type /tt new dev: you are teleported to a new reserved server running dev.

Check: /tt status in the new server says reserved server, branch dev (dev). Change a value in src/shared/rush/config.ts (for example TARGET_SIZE), commit, deploy again, and watch the targets change while you play. More in Branches and channels.

11. The dev menu and who gets it

Devs open the dev menu with the DEV button, Ctrl+Shift+D or /tt dev. A player is a dev when they are:

• the experience owner (the user creator, or rank 255 in the owning group): always;
• in members (owner or dev; an old admin counts as dev), once you published the lists (below);
• a holder of the devBadgeId badge (published the same way; awarding the badge in game is planned);
• anyone in a Studio playtest;

and not in revoked. Owners are the experience's creator (or the owning group's owner) and members with the role owner: they also get the Manage tab and can switch any server in place. Prod-channel servers (every public server) show the menu read-only. Tabs: The dev menu.

Publish the lists after every change to members, revoked or devBadgeId:

bun run typetorch access push

• It writes the access field of the game's signed settings record (DataStore TypeTorch, key settings), signed with both prod keys (step 7), then pings the servers. Game code can write DataStores but can't sign, and servers refuse a record that doesn't verify, so nothing in your game can make itself a dev. --dry-run shows the lists first.
• Servers need kernel 0.3.8+ to read it. Running servers apply a push within seconds (the ping), or within about a minute without it.
• Before the first push, only the experience owner is a dev. After a change, servers keep the old lists until the next push (a revoked dev stays a dev). deploy and doctor (dev access) warn about both; bun run typetorch access status compares typetorch.json with the last push.

Check: as the owner you see the DEV button in game. After access push, a member sees it too.

12. /tt chat commands

Devs only. They work even when a build is broken, so they are the fallback when the dev menu can't open.

Command	What it does	Who
/tt status	branch, channel, artifact, kernel build, signing mode	dev
/tt branch <name>	switch this server to a branch	devs on private or reserved servers; owners on any server
/tt new <branch> [assetId]	open a reserved server on a branch (pinned to an artifact if given) and teleport you	dev
/tt reload	load the branch head again	dev
/tt rollback	swap this server back to its previous artifact	dev; owners on prod-channel servers
/tt pin <assetId> / /tt unpin	hold this server on a known artifact / release it	devs on dev servers; owners on any server
/tt bundle	send a debug bundle of this server to the backend (kernel 0.5.3+)	dev
/tt dev	open the dev menu	dev

/tt grant and /tt revoke are planned.

13. Roll back

bun run typetorch rollback --branch prod

It points prod back to the previous different build. Nothing is rebuilt or uploaded, so it takes about 1 to 2 seconds. --to <commit|artifactId|assetId|#seq> picks a build. It asks y/N and signs like a deploy. More in Deploy and rollback.

Check: bun run typetorch deployments shows a rollback row marked live; in game the previous version runs.

Next steps

• Testing in Studio: run your local code with bun run typetorch serve (CLI 0.11+) and the Studio plugin; saves reload a running playtest (kernel 0.5.4+).
• Live servers and alerts: typetorch servers, deploy reports, alerts, and the automatic rollback after a bad deploy.
• Analytics: your own analytics, experiments and player journeys (the template already creates the engine).
• Player data before you save anything for players.
• Hot assets: let builders update models and UI live.
• remote-claude: prompt Claude Code from inside a dev server.
• Troubleshooting when something doesn't match a Check.