Publishing #

The local app is plain static files. Optional remote mode adds the Rust host and its private database; there is no account system yet. This page covers what to publish, what the web server must do, and how to ship and roll back a model. For the markup the app expects, see host-page.md.

Frontend build prerequisites #

Use Node.js 24 or newer and run npm ci from the repository before building. The shared rules need Rust 1.88+ with the wasm32-unknown-unknown target and wasm-bindgen-cli at exactly the version core/wasm/Cargo.lock pins (core); core/wasm/build.sh names the missing piece. npm run typecheck checks all TS/TSX with strict mode (after npm run core). npm run build writes dist/; site/build.sh OUT remains the deployment/preview entry point. It builds the rules module (tokenling_core_bg.wasm), checks types and bundles Preact plus the app into main.js, and inference into a separate brain.js, before replacing output. site/bundle.mjs accepts an output directory argument, reads no environment variables and copies the rules module beside both bundles. The builder hashes emitted JavaScript, source maps and the module together, so dependency and rule changes also get a fresh immutable path. Model and runtime assets are still published separately. No Node process, package registry or Preact CDN is needed to serve or use the built app.

What gets published #

<base>/                      the page (index.html), sw.js and _headers, from site/build.sh
<base>/bench.html            unlinked brain benchmark using this release's model/runtime
<base>/assets/               the font, manifest.webmanifest and icons
<base>/app/<hash>/           bundled main.js, brain.js, source maps and tokenling_core_bg.wasm, under a content hash
<base>/models/<id>/          exported models (see export-and-runtime.md)
<base>/runtime/<name>/       the vendored transformers.js + ONNX Runtime files

<base> is the URL path the site is served under (/ for a whole domain).

Piece	Produced by	Notes
Page, benchmark, app, worker, assets	BASE=<base> site/build.sh OUT	fills the page and test/bench.html from site/release.json; leaves OUT/models and OUT/runtime alone
Model	train/export.sh CKPT OUT	writes tokenizer/config JSON, onnx/model_q4.onnx and SHA256SUMS (plus an eval/ file that is not published)
Runtime	train/vendor.sh OUT	pinned transformers.js and its matching ONNX Runtime build
Install model and runtime	STATIC_ROOT=… train/publish.sh MODEL_DIR MODEL_ID RUNTIME_DIR RUNTIME_NAME	verifies checksums first; BASE (default tokenling), FILE_MODE (default 0644) and DIR_MODE (default 0755) are optional

site/build.sh copies and renders the new static files in a temporary sibling directory before replacing output entries. A copy, release-validation or render failure during staging leaves the previous output untouched; models/ and runtime/ are preserved on successful builds too. The final multi-entry installation is not an atomic directory swap.

publish.sh finishes and checks the model partial and any needed runtime partial before publishing either. A new runtime is renamed first, then the model; a runtime-copy failure removes the partials without consuming the model id, so the same command can be retried. Existing runtime directories are left alone, and an existing model directory is never replaced. To build into the same tree, point site/build.sh at $STATIC_ROOT/$BASE.

site/release.json #

What the page says about the release. It is project data, not host data:

Key	Meaning
modelId, size	the current model directory and the byte size of its onnx/model_q4.onnx
trained	one line for the page's details
news	what the current brain does better, for the upgrade dialog
features	features the current brain was trained for (host-page.md)
older	older brains, newest first, {"id", "features"}, that visitors may keep running until they upgrade; only brains that speak the current prompt format
runtime	the runtime directory name under <base>/runtime/
source	URL of the source code for the page's link (SOURCE overrides it)

A deployment's external RELEASE file may also contain analyticsToken: the public Cloudflare Web Analytics site token. Keep deployment identifiers out of the repository's release file.

site/build.sh also takes MODELS_URL and RUNTIME_URL to load the model or runtime from other paths, and MODEL_ID/SIZE overrides (the preview uses them). CF_ANALYTICS_TOKEN overrides analyticsToken; an empty value disables analytics even when the release override contains a token. Both settings default to disabled and accept only an empty string or a 32-character hexadecimal token.

The build always includes bench.html, without a navigation link or analytics beacon. It uses the same resolved model/runtime URLs and model id as the app, including build overrides. It runs on opening, downloads its own model copy without using the pet's model cache, and reports results locally; it neither reads nor changes the saved pet. Serve it with isolation headers and Cache-Control: no-cache so a new release updates its model/runtime selection. See testing.md for its query options and measurements.

Optional page analytics #

With a configured token, the builder emits the Cloudflare Web Analytics module snippet before the closing body tag and adds a visible disclosure about page visits and performance. It never adds app event reporting or passes pet/owner fields, chat, diary or save data to analytics. Without a token, neither the snippet nor its disclosure is emitted.

Use the module form so the external script uses CORS while COOP/COEP remain enabled. After enabling it, verify that exactly one beacon script loads, its report succeeds, crossOriginIsolated remains true, and blocking the beacon or going offline does not stop the pet. Inspect a report from a synthetic test pet to confirm private app fields are absent. Provider setup, site tokens and deployment receipts belong in the operator's documentation. Avoid combining a manual snippet with a second automatically injected one.

Web server requirements #

Any static file server or static host works; nothing runs on the server.

• HTTPS (or localhost). Cache Storage, persistent storage, service workers, notifications and threads need a secure context.
• Trailing slash. Serve the page at <base>/ (redirect <base> to it): the service worker is registered relative to the page and its scope is that directory.
• MIME types: .mjs and .js as text/javascript, .wasm as application/wasm, .json as JSON, .webmanifest as application/manifest+json. Range requests are not required.
• Cross-origin isolation on the page and everything under <base>: Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp. Without them the WebAssembly backend runs on one thread: 2.0 tokens/s measured, against 5.9 with them (export-and-runtime.md). Cross-origin resources require appropriate CORS or CORP permission; keep the app, model and runtime same-origin.
• Immutable caching for app/*, models/* and runtime/*: Cache-Control: public, max-age=31536000, immutable. This is only safe because those directories never change in place. Serve sw.js with Cache-Control: no-cache (or a short max-age) so worker updates arrive.
• Compression is optional; the .onnx and runtime .wasm files barely compress. The app's rules module (about 0.45 MB) shrinks to about a third with gzip.
• Allow for sizes: about 97 MB per model and about 85 MB of runtime (a browser fetches only one of the .wasm builds; the one transformers.js loads is 27 MB).

site/build.sh writes these header rules to <base>/_headers, the format some static hosts read. Other servers need the same rules in their configuration.

The shipped service worker passes .onnx downloads through to the browser without respondWith, including when MODELS_URL changes the path. Keep that bypass when embedding the app behind another service worker: proxying long model streams can end them early in Firefox (Error in input stream). The model's separate transformers-cache still supplies it offline.

Shipping a change #

Code or page only (nothing the model sees): run npm test, preview with test/dev-site.sh (see testing.md), build with site/build.sh and copy the output to the server. Keep old app/<hash>/ directories when copying (no delete-sync of app/): a tab opened before the deploy may still start its brain worker from its own version's directory.

A new model:

1. train/export.sh CKPT OUT/tokenling-vN.
2. train/publish.sh OUT/tokenling-vN tokenling-vN RUNTIME_DIR RUNTIME_NAME (the runtime step is skipped if that directory already exists).
3. Edit site/release.json: the new modelId, size, trained and news; move the previous model to the front of older if the prompt format did not change (otherwise empty older); list any new features.
4. Build and deploy the page, then test a fresh profile end to end (download, cached reload, a chat with each lookup tool, a diary page) and a profile that has the previous brain (the upgrade dialog, the download and the swap).

Visitors who already have a pet keep their brain until they accept the upgrade when its prompt format is still compatible; nobody loses a pet, chat or diary to a model change.

Rollback: point modelId back at the previous model (and take it out of older), rebuild and deploy. Old model directories can stay on disk. A visitor who already upgraded to the withdrawn brain has nothing usable cached and downloads the restored one again.

If the prompt format changed (see AGENTS.md), empty older: older brains cannot read the new format, so pets with only an old brain doze until the new one is downloaded. Saved pets still load, because their state stores plain chat lines, but expect a few odd replies until the old history scrolls out of the context. If a stored shape changed, bump the save version and add a migration (pet-simulation.md).

v6 changes sleeping replies and filters owner quotes from the chat header. Its release therefore has an empty older list; v2–v5 are incompatible.

Doing the GPU work #

Training and bulk teacher generation need the GPUs. On a shared machine:

1. Look first. Check nvidia-smi and whatever else is serving from those GPUs for in-flight work, and note what is resident so you can restore it.
2. Free the GPUs. Do not start jobs on cards other services need.
3. train/teachers.sh start, wait, run gen_data.py, then stop. The script starts each server as its own process group and stops it by group, so nothing is killed by name pattern (a pkill -f pattern inside a shell command can match that same shell's command line).
4. Train on one or both GPUs (CUDA_VISIBLE_DEVICES). Export and quantization are CPU-only and can run after the GPUs are given back.
5. Hand the GPUs back as soon as they are free: restart whatever you stopped, restore what was resident, and verify each service with a real request. Do not hold the GPUs while only CPU work remains.
6. Record the dates, the downtime and the results in your run receipt.

Optional remote pet host #

The static app supports an independent Rust host. REMOTE_ENDPOINT optionally pre-fills its address; otherwise owners enter one. It never changes the local default. The equivalent release override key is remoteEndpoint. Do not embed private access keys in deployment configuration or the host page.

The host has required listen, database, model/release, native runtime and allowed-origin inputs documented in server/README.md. Keep private SQLite state and backups outside Git. Use HTTPS for remote clients and exact CORS origins. Authenticated API data use no-store; the service worker bypasses Authorization requests and /api/ paths. Alerts remain browser/device managed; there is no new push service.

Run the Rust ownership/API tests and prompt parity, then check setup choices, both transfer directions, closed-page background turns, reconnect/outage recovery and the 360 px layout. Native CUDA and simultaneous CPU/GPU bursts have a limited qualification receipt. Repeat it with the selected runtime/device before deployment; it does not establish sustained capacity or public-host readiness.

Live checks #

curl -fsSI https://HOST/<base>/                                  # 200, with the COOP/COEP headers
curl -fsS  https://HOST/<base>/models/tokenling-v6/SHA256SUMS
curl -fsSI https://HOST/<base>/sw.js                             # 200, text/javascript, not immutable
curl -fsSI https://HOST/<base>/assets/manifest.webmanifest       # 200, application/manifest+json
(cd <published model dir> && sha256sum -c SHA256SUMS)
curl -fsSI https://HOST/                                         # no COOP/COEP outside <base>, if you scoped them

Then run the browser flow in testing.md against the live URL with a fresh persistent profile, and check the layout at 360 px width.