Technical Manual sections
Reference › Technical Manual › Updates
In production, Kitten updates itself and the app it serves in one transaction: either both move to their new versions and the new server’s home page is healthy, or both go back to where they were. (Without a deployed app, the kitten update command updates only Kitten.)
These are the parts:
KittenPackage(src/lib/KittenPackage.ts) asks the distribution server (distributionHostin version.json, which is kittens.small-web.org unless the build sets another) for the newest releases (releases(apiVersion)), stages a release (stage()), and activates a staged one (activate()).To stage a release, it downloads the package and its signature into updates/downloads/, verifies the signature against
PUBLIC_KEYS(src/lib/packageSignature.ts), extracts the package into versions/<exact version>.staging/, checks its version.json, and runs the package’s owninstall --stage. Then it checks the launcher withbash -nandkitten --version, runsupdate-guard.js check, and only then renames the folder to versions/<exact version>/. To activate a version, it points the app and runtime symbolic links at the version and its runtime (see Installation layout).AppRepository(src/AppRepository.ts) is the deployed app’s git working copy. It follows thereleasebranch when the remote has one, and the remote’s default branch otherwise. It reports the installed commit and the head of that branch, each with the Kitten API version that it declares in theengines.kittenfield in its package.json.AutomaticUpdates(src/AutomaticUpdates.ts) schedules and runs checks. The first check runs at a random time between one and ten minutes after the server starts listening, and the next ones everykitten._db.settings.autoUpdate.intervalmilliseconds (six hours by default, never when it is-1). A check’s trigger is'scheduled', or'requested'by the webhook, the Settings app, or thekitten updatecommand. A check that starts while another one runs returns the result of the running check.
A check runs like this:
If an update is pending (updates/pending exists), the check ends as
busy. Otherwise, it fetches the head of the tracked branch and asks for the newest release of each API version involved (the running Kitten’s, the installed commit’s, and the head’s).The
chooseUpdateTarget()function (src/lib/updateTarget.ts) chooses a target: a Kitten release and an app commit. It prefers the head with the newest Kitten for the head’s API version, then the installed commit with a newer Kitten, and then the head with the running Kitten. It never chooses a head that declares an older API version than the running Kitten’s, and it skips every target that failed before (updates/failed/). A head that declares no API version is only a candidate in a requested check, which treats it as declaring the running Kitten’s API version.The
apply()function (src/lib/applyUpdate.ts) checks that there is enough free space (requiredBytes()in src/lib/updateSpace.ts) and stages the Kitten release if Kitten changes. It refuses an app that has local work the checkout would overwrite, or that is on another file system than the data home. It installs the app’s changed dependencies in updates/staged-dependencies/ and records the status code of the home page as the baseline. Then it writes the pending record (updates/pending, in thestagedstate, with astartDeadlineSecondsof five times the last start’s duration and at least 60 seconds), activates the new Kitten, and asks for a restart.In production, when updates/pending exists, the launcher runs the update guard (src/entry/update-guard.ts, src/lib/updateGuard.ts) before it starts Kitten. If the history already contains the update as confirmed, the guard deletes the pending record and exits with 0. If a
stagedrecord is for another version, the guard points the symbolic links at that version and exits with 3. (If the links already point there, the guard exits with 1 and reports the launcher to run. If the folder of that version or of its runtime doesn’t exist, the guard deletes the pending record and exits with 0.) Otherwise, the guard switches over (switchTo()in src/lib/updateTransaction.ts): it snapshots db/ and _db/ in updates/snapshots/, checks out the app commit, moves the staged dependencies into place, and sets the record tostartedwith one attempt.Once it is listening, the Kitten Server requests its own home page. If the status is healthy (
isHealthy()in src/lib/updateConfirmation.ts: a response with a status under 500, or any result if the home page had no response or a status of 500 or more before the update), theconfirm()function removes the change logs that the 2026-11-07 release recorded in updates/history.jsonl (removeRecordedChangeLogs()), adds the update to it, deletes the pending record, and deletes the staged dependencies and the snapshots of other updates. After an update that changed Kitten, it also prunes every version and runtime other than the new and the previous ones. (After an app-only update, it preserves every version and runtime.) Otherwise, the server exits with the restart request code. A worker thread (startDeadline()) ends the process withSIGKILLif the server hasn’t confirmed the update within the record’sstartDeadlineSeconds.Each start that finds a
startedrecord with fewer thanMAX_FAILED_STARTS(2) attempts adds one attempt and starts the new version again. A start that finds two attempts, or a record for another version, rolls the update back (rollBack()): it checks out the previous commit, removes the files the update added, restores node_modules, moves the app’s databases to updates/failed-data/<id>/ and restores the snapshot, points the symbolic links back, records the target as failed, adds the rollback to the history, and deletes the pending record. If a step of the rollback fails, Kitten keeps the record, and the next start tries again.
State Diagram: The states of an update
The automatic updates use these files and folders in updates/ in the data home:
pending: the record of the update in progress. (The guard renames a record that it cannot read to pending.unreadable.)
history.jsonl: one line per confirmed or rolled-back update. The Settings app shows the last ten.
last-check.json: the outcome of the last check, which the Settings app shows.
failed/: one file per target that failed. The Settings app’s Try again (
tryAgain()) deletes them and runs a requested check.failed-data/: the app’s databases as they were when an update was rolled back, one folder per update.
start-seconds: how long the last production start took.
snapshots/, staged-dependencies/, and downloads/: the working folders of an update. A start without a pending record deletes the first two (
pruneAtStart()).
The unit tests cannot exercise an update on a real server. The automatic updates rehearsal does. Run its reset and scenarios 1, 2, 14, 6, 7, and 12 (npm run rehearsal -- 1 2 14 6 7 12) before a release that changes install, build-templates/kitten, update-guard.js, KittenPackage.ts, or AutomaticUpdates.ts, and its reset and all fifteen (npm run rehearsal) before a release that changes the update transaction or starts a new Kitten API version.
Source code: