# TypeTorch

> TypeTorch is a roblox-ts framework and toolchain that updates live Roblox games without restarting servers. A small Luau kernel baked into the place loads each build (a payload of ModuleScripts uploaded as a private Model asset) and hot-swaps server and client code in seconds while players stay. Code uses @typetorch/framework (modules with dependency injection, lifecycle hooks, troves, guarded networking, hot assets, an in-game dev menu); the typetorch CLI (alias tt) builds, uploads, approves, signs (prod) and deploys, and runs the Studio loop (typetorch serve) that the TypeTorch Studio plugin attaches to. An optional self-hosted backend holds the fleet API, analytics, errors, notifications, feedback, live events and a web explorer. roblox-ts only. Early: APIs still change. Released versions (2026-11-15): cli 0.18.1, framework 0.7.1, kernel 0.5.7, transformer 0.3.2, dev-server 0.3.3 (0.4.0 is on main, not on npm), Studio plugin 0.7.1. The npm packages are published from version tags with npm trusted publishing; the Studio plugin ships as TypeTorchSync.rbxm on GitHub releases (not npm); the backend is unversioned and runs from a checkout or its Docker image.

Docs: https://www.typetorch.dev (the links below). The Markdown sources are in https://github.com/typetorch/docs (same paths, with .md; the overview /docs is README.md).

Key facts for agents:
- Never handle secrets (Open Cloud keys, signing key files, backend tokens) and never act on Roblox (deploy, publish, keys, approve, settings writes): those are user steps. Follow agents/AGENTS.md.
- Every module must be stoppable and restartable: everything in this.trove, no module-level state (persist plain data with this.ctx.persist; per-player maps with this.ctx.playerState), players via onPlayerAdded/observePlayers (replays on every swap), characters via @rbxts/observers with the stop function in the trove, no RemoteEvents (createNetwork), no _G. A cleanup function never calls trove.remove/add/extend (Trove throws while cleaning); this.ctx is usable from onInit on (never in field initializers); libraries with module-level setup (Vide's stepper, TopbarPlus) leak per swap unless stepped from the trove or loaded once outside the payload.
- Modules reach each other by constructor injection; elsewhere (methods, plain classes, command handlers) with Dependency<T>() / TypeTorch.module<T>(), from onInit on (never in a constructor, field initializer or module top level). A dependency cycle is broken with Lazy<T> (a field `= Lazy<T>()`, or a constructor parameter with @typetorch/transformer 0.2.1+) or Dependency<T>() in a method.
- The payload holds only Folders and ModuleScripts; entry points are src/server/boot.ts and src/client/boot.ts.
- The template repo decides the toolchain (package.json, tsconfig.json, default.project.json, studio.project.json), but its package versions are behind npm (framework 0.5.0, kernel 0.5.1, cli 0.9.1 in its lock): after cloning, `bun add` the newest @typetorch/* packages and `rokit add seaofvoices/darklua` (fresh-setup "Take the newest versions").
- Debug macros (`$print`, `$dbg`, ...) come from @typetorch/transformer 0.3.2+ (`@typetorch/transformer/macros`); rbxts-transform-debug is no longer needed.
- Compiler (CLI 0.16+): goblox (`bun add -d goblox`, roblox-ts ported to Go) when installed, else rbxtsc; TYPETORCH_COMPILER or typetorch.json "compiler" picks one. goblox runs @typetorch/transformer itself and ignores other JS tsconfig plugins.
- Production pack (CLI 0.17+, every channel): build/upload/deploy strip comments, set __DEV__ = false and drop unused *.story modules with darklua before upload, so the artifact id and signature cover the final bytes. Without darklua it warns "darklua not found" and uploads unpacked. `--no-minify` turns it off; typetorch.json "minify" is ignored as an unknown key through CLI 0.18.1. `typetorch serve` never packs.
- No CI for games (the owner's rule: supply-chain risk). Never add workflows, actions or hosted CI to a game repo; builds, cloud tests and deploys run on the user's machine and keys never go to CI. (TypeTorch's own packages are released by tag-triggered GitHub workflows; not something to copy into a game.)
- Roles in game: owner (experience creator or group owner, plus members with role "owner") and dev; a legacy "admin" counts as dev. The dev-only tools (Claude, Logs > Upload, Dex edits, Network blocking, Server > Experiments, server state for non-owners) work under dev rules for every dev, or on a public server an owner switched to a dev branch for owners only; read-only everywhere else. With kernel and framework 0.5.6+ the devtools client code reaches devs only.
- The cloud test (before every prod deploy) runs onInit/onStart in a headless task against the live game's DataStores, MemoryStores, MessagingService and HTTP, with no players and no place scripts; TypeTorch.channel is "dev" there and the AnalyticsEngine sends nothing. workspace:GetAttribute("TypeTorchTest") is true there: guard side effects with it; never wait on place scripts.
- Dev access: typetorch.json members/revoked/devBadgeId reach servers only through `typetorch access push` (the signed settings record; kernel 0.3.8+). ServerScriptService.LoadStringEnabled stays off in a live game (only remote-claude's in-game run_luau needs it; kernel deploy patches leave it alone; `kernel deploy --loadstring` turns it on for a test place). Kernel 0.3.6+: players are never on an empty baseplate (held until a build runs; the backup build baked by kernel deploy, peers, retries).
- Settings (kernel 0.3.8+): ONE signed record in the game's DataStore (TypeTorch / settings, at most 32 KB, game at most 16 KB), written only by the CLI with both prod keys (`typetorch settings status|get|set|unset|push`, `access push`, `backend setup`, `experiment`, `notify key rotate`): access, defaultBranch, channels, backend {url, key, analytics, notify} (plus the fleet/analytics sections derived for kernels before 0.4), and game values read with `TypeTorch.liveConfig(key, { default, parse? })` (server only; get(), onChanged). Reserved game keys: `tt.events` (live events) and `feedback` (the rating scale). Servers verify it, keep the last good copy, re-read about every minute and within seconds of the CLI's ping. No ConfigService keys (no universe:write); `config push` is gone.
- Analytics dials in backend.analytics: flushSeconds 5-300 (default 15) and recordShare 0-1 (`backend setup`), experiments (`typetorch experiment`), and techEvery, recordSeconds 10-600 (default 60), positions (up to 64 event names), joinData full|summary|off and joinLaunchPrefix, which no command writes yet.
- Cross-server (kernel 0.3.8+, server only): `TypeTorch.messaging.subscribe(topic, (data, meta) => ...)` (returns a disconnect for the trove) and `publish(topic, data, { to? })` over one kernel-held MessagingService topic (listeners hear prod servers and their own branch by default; 1 KiB per message; a no-op in the cloud test; Studio loops back). `TypeTorch.servers({ includeDev? })` lists live servers, `TypeTorch.setServerInfo({...})` adds public fields (400 bytes).
- Detached jobs (kernel 0.3.8+, server only): `TypeTorch.runDetached(fn)` runs fn on a kernel thread a deploy can't kill (for ProfileStore/ProfileService loads, saves and releases) and returns a Promise that settles while the generation runs; 256 at once per server.
- Loading screens (kernel 0.3.8+): a place script in ReplicatedFirst waits for ReplicatedFirst.TypeTorchKernelClient's ClientReady = true and Holding = nil; ReplicatedFirst attributes TypeTorchBootScreen = "<ScreenGui name>" and TypeTorchKernelScreen = false.
- Safe deploys: a cloud test before every prod publish; a 15 s boot budget; each server rolls a new build back at 3 errors from it within 30 s or a failed onStart (typetorch.json "health": { errors 1-100, window 5-300 s, rollback, prod/dev }); `deploy --wait` rolls the branch back when 20% of servers fail (typetorch.json "autoRollback": { "failedPct": 1-100 }). With a backend the CLI posts deploy marks (POST /v1/fleet/deploy, /v1/fleet/mark) shown on the explorer's Deploys page and charts.
- Live events (framework 0.7.1): scheduled changes of game values made on the explorer's Live events page and signed with `typetorch settings set game.tt.events -`; each server switches them on its own clock; `TypeTorch.liveEvents()` (active, upcoming, onChanged) for game UI. Backend limits: 8 values of 1 KB each per event, 50 pending, 8 KB schedule, 31 days long, 366 days ahead.
- Live debug (framework 0.7.1 + kernel 0.5.7, server only): `remoteDebug.command(name, fn)` (owner-run buttons that must be read-only), `remoteDebug.stream(name, fn, { hz, kind })` (sampled only while watched; "points" draw on the live map) and `fleet.column(name, fn)` (Fleet page columns; never personal data). Limits: 32 commands, 8 streams, 16 columns per server. Builds on remote debug (kernel 0.5.0+): the server pulls allow-listed read-only commands while an owner watches it in the explorer.
- Notifications: native Roblox experience notifications run by the backend: kinds in typetorch.json "notifications", `TypeTorch.notifications()` want/drop/setOff/onOpen (server) and promptOptIn (client), signed taps, `typetorch notify push|status|templates|test|send|key rotate|pause|resume`. Templates are made by hand in the Creator Dashboard.
- Feedback (framework 0.7.0, server only): `TypeTorch.feedback().submit(player, { rating?, text?, topic?, ctx? })` writes one `feedback` analytics row; the explorer's Feedback page reads them.
- Backend API keys: named keys `ttk_<id>_<secret>` with roles game|lookup|support|analyst|admin over HTTP (/v1/admin/keys); the CLI's `typetorch keys create|list|revoke` ship in the next CLI release (on main after 0.18.1).
- Studio (CLI 0.11+): `typetorch serve` runs the compiler in watch mode, rojo serve and a loopback control API (127.0.0.1:34880-34887); the Studio plugin attaches by itself to the serve whose universeId matches the place and, with kernel 0.5.4+, reloads a running playtest on save. Agents: `serve --detach`, `typetorch studio status|reconnect|play|stop|logs`, `typetorch mcp`. `serve --remote` (Cloudflare quick tunnel + one pairing link for a Studio on another machine). `serve --claude` (the plugin's Claude tab, Code mode: Apply, Deploy to dev, Discard) needs @typetorch/dev-server 0.4.0, not on npm yet (0.3.3 exits with "unexpected argument"); Claude reading the open place from Studio is planned. Starting serve with --remote or --claude, and the hot asset Upload / Publish buttons, are user steps.

## Get started

- [Overview](https://www.typetorch.dev/docs): index, how it works, repositories, releases
- [Fresh setup](https://www.typetorch.dev/getting-started/fresh-setup): `typetorch init` (the guided setup, resumable, repair mode, optional backend on Coolify, a VPS without Docker or this PC, AGENT_PROMPT.md), then by hand: tools (Bun, Rokit, Rojo, Lune, darklua), clone the template, take the newest versions, typetorch.json, API key scopes (no universe:write; legacy-asset:manage can't be granted to API keys), signing keys (offline backup), LoadStringEnabled (off in a live game), kernel publish, first deploy (cloud test, --wait), dev branch, owners and devs (typetorch access push), /tt, rollback
- [Migrate an existing game](https://www.typetorch.dev/getting-started/migrate): toolchain, boot modules, Flamework/Knit/singletons to modules, the swap-safety rules with before/after code, debug macros, shutdown (onStop is not a save point), networking, UI, data, optional analytics, the cloud test, cross-server messages, installing the kernel in a place with content (kernel deploy --place-file patches only the kernel), checklist, pitfalls
- [Go-live checklist](https://www.typetorch.dev/guides/go-live-checklist): moving a game with live players: prepare, a copy of the game, a dev-branch soak with live tests, data check, cut-over, what to do if it goes wrong

## Agents

- [Agent playbook](https://www.typetorch.dev/agents/AGENTS): detect, plan, toolchain, migrate step by step, local checks, stop at user actions, "What you need to do" list, report template, manual kernel updates by agents
- [Claude Code skill](https://www.typetorch.dev/agents/skills/typetorch-migrate/SKILL): the playbook's essentials as a skill; also in the plugin marketplace typetorch/claude-plugin (`/plugin marketplace add typetorch/claude-plugin`, `/plugin install typetorch@typetorch`)

## Build your game

- [Runtime API](https://www.typetorch.dev/guides/runtime-api): TypeTorch.* identity, startInfo, onSwapOut, onUpdatePending, onBranchChanged, persist, playerState, module/tryModule and Dependency<T>(), roles, servers, messaging, runDetached, liveConfig, liveEvents, remoteDebug and fleet (live debug), notifications, feedback, loading screens, logs, hot assets
- [State with charm](https://www.typetorch.dev/guides/state): atoms per generation; server atoms from persist, charm-sync over a createNetwork leaf, the client's hydrate request in onStart, patterns that survive swaps
- [Networking](https://www.typetorch.dev/guides/networking): createNetwork, guards, limits, requests, invokeWithTimeout and per-leaf timeouts, emit, Flamework networking names, supported parameter types and the transformer's leaf warnings
- [Cross-server messages](https://www.typetorch.dev/guides/messaging): TypeTorch.messaging subscribe/publish, who hears what, verified MessagingService limits, TypeTorch's own topics, TypeTorch.servers() and setServerInfo, moving from MessagingService
- [Player data](https://www.typetorch.dev/guides/player-data): the swap-safe pattern with ProfileStore and ProfileService (writes as DataHost jobs or TypeTorch.runDetached), developer product receipts recorded before PurchaseGranted, shutdown
- [Loading screens](https://www.typetorch.dev/guides/loading-screen): ClientReady, ClientGeneration, Holding, TypeTorchBootScreen, TypeTorchKernelScreen, a place-script recipe
- [Hot assets](https://www.typetorch.dev/guides/hot-assets): TypeTorchAsset, typetorch assets sync (or the Studio plugin's panel), assets types, hotAsset(), updating held tools, migrating templates
- [The dev menu](https://www.typetorch.dev/guides/dev-menu): the header, dev-only tools, panes and windows, the command palette, tabs (Artifact, Modules, Server, Manage, Logs, Dex, Network, Claude), /tt commands (including /tt bundle)
- [Player feedback](https://www.typetorch.dev/guides/feedback): TypeTorch.feedback().submit, rating scales in game.feedback, rate limits, the feedback row, the Feedback page, moving from a custom event
- [Coming from Flamework](https://www.typetorch.dev/guides/from-flamework): typetorch migrate --from flamework (local codemod, --net compat or native, a Markdown report, --dry-run), createFlameworkCompat, network leaf diagnostics, the full mapping

## Deploy

- [Deploy and rollback](https://www.typetorch.dev/guides/deploy-and-rollback): deploy stages, the compiler (goblox or rbxtsc), the production pack (darklua, --no-minify), artifact ids, shared #seq, ProtocolHash, approval and proposals, safe deploys (cloud test, health window, 15 s boot budget, deploy --wait and automatic rollback, reports), rollouts, never an empty server (the backup build, backup refresh, deploy --reupload), promote, rollback, the deployment log, deploy marks on the backend, pins, kernel updates, timings
- [Branches and channels](https://www.typetorch.dev/guides/branches-and-channels): prod/dev, effective channel, private and reserved servers, owners switch any server in place (Switch, Load here), branch ls / branch rm and the 32-branch cap
- [Prod signing](https://www.typetorch.dev/guides/prod-signing): Root Key and Fallback Key, typetorch keys init/rotate/resign, key asset, kernel 0.3 rule, bootstrap heads, boot fail-safe, back up and drill
- [Settings](https://www.typetorch.dev/guides/settings): the signed settings record, fields, commands, endpoint checks before signing, reserved game keys (tt.events, feedback), the analytics dials, join data (full|summary|off), TypeTorch.liveConfig, how servers read and verify it, moving from ConfigService

## Operate (the self-hosted backend)

- [Live servers and alerts](https://www.typetorch.dev/guides/fleet-and-alerts): kernel heartbeats (every 30 s), reports and alerts to the backend (typetorch backend setup / run / bless), typetorch servers/report/alerts, alert codes, backend alerts, the deploy history, webhooks, error logs and drop rules, budget view, remote debug, Roblox server logs, server location, debug bundles, debugging endpoints (GET /v1/fleet/servers, POST /v1/sql)
- [Live debug](https://www.typetorch.dev/guides/live-debug): game-declared commands, streams and Fleet columns, limits, the server's Game and Live map tabs, the all-servers live map (/live), safety rules, routes
- [The explorer](https://www.typetorch.dev/guides/explorer): the backend's web app: sign in (admin token, Roblox, typetorch.dev) and roles, every page by sidebar group, the filter bar, command palette, compare and explain, deploy markers, saved queries, Roblox parity
- [Analytics](https://www.typetorch.dev/guides/analytics): AnalyticsEngine (server and client, collectors, zones, first-session recording, positions), the event format, the join row and jd, notification rows, DuckDB server or Cloudflare Basin, the analytics dials, experiments (typetorch experiment weights|settle|stop|resume|clear|force), queries, node graphs, bun run report, privacy and Right to Erasure, a local quick start
- [Recordings and maps](https://www.typetorch.dev/guides/recordings-and-maps): what the game sends (recordings, positions, a map prop), map export and alignment, the Maps page (2D and 3D), the Recordings page and replay, quit autopsy, first actions, queries, limits
- [Live events](https://www.typetorch.dev/guides/live-events): how a scheduled change of live values works, scheduling and signing one, checking servers have it, game code, the lift report, routes
- [Notifications](https://www.typetorch.dev/guides/notifications): kinds in typetorch.json, intents (want/drop/setOff/onOpen) and promptOptIn, the funnel, typetorch notify commands, dry run, templates, a halted kind, send failures, signed taps and key rotation, a playbook, open spikes
- [Running the backend](https://www.typetorch.dev/guides/backend-operations): environment, runtime settings, backend alerts, the audit log, backups and restore, disk space, backend stats, deploys on Coolify, API docs for agents, Open Cloud key scopes per feature
- [API keys](https://www.typetorch.dev/guides/api-keys): named backend keys with roles and scopes, typetorch keys create/list/revoke (next CLI release), the admin API, built-in env tokens, per-player events and summary endpoints, the event allow-list, per-key rate limit, audit
- [Security model](https://www.typetorch.dev/guides/security): who can do what, what protects prod, the backend, devtools for devs only, keys and tokens, serve's control API and remote Studios, no CI for games, never publish secrets, agents
- [Troubleshooting](https://www.typetorch.dev/guides/troubleshooting): real errors and fixes (cloud test, --wait, swaps, fleet, quick tunnels, analytics, settings and signing keys, dependency cycles)

## Tooling

- [Testing in Studio](https://www.typetorch.dev/guides/studio-testing): studio.project.json, the Studio plugin (TypeTorchSync.rbxm from its GitHub release), typetorch serve, live reload in a playtest (kernel 0.5.4+), the hot assets panel, agents and Studio, a Studio on another machine (serve --remote), Claude in Studio (serve --claude), a session you must not publish
- [remote-claude](https://www.typetorch.dev/guides/remote-claude): Claude Code prompted from a dev server (--users defaults to typetorch.json owners), Live and Code modes, attach context, Toolbox, from Studio (serve --claude, dev-server 0.4.0: Apply, Deploy to dev, Discard), security

## Optional

- [CLI reference](https://www.typetorch.dev/reference/cli): every command and flag, identity, keys, registry, message format
- [Framework reference](https://www.typetorch.dev/reference/framework): API reference
- [Kernel reference](https://www.typetorch.dev/reference/kernel): the loader, boot, swaps, settings, fleet reports
- [Transformer reference](https://www.typetorch.dev/reference/transformer): guards, dependency injection, debug macros, migrating from Flamework
- [Dev-server reference](https://www.typetorch.dev/reference/dev-server): remote-claude security model and HTTP contract
- [Studio plugin reference](https://www.typetorch.dev/reference/studio-plugin): install, layout, the control API it speaks
- [Backend reference](https://www.typetorch.dev/reference/backend): row format, queries, Basin, the DuckDB server, fleet API endpoints, error logs, remote and live debug, the explorer, sign-in (Roblox or typetorch.dev), a VPS guide, load tests
- [Template](https://github.com/typetorch/template): the starter game (Target Rush) and reference setup
- [Analytics contract (SCHEMA.md)](https://github.com/typetorch/framework/blob/main/src/analytics/SCHEMA.md): every column, event and prop, tt-rec-1, sink settings, transport