Releases and remote updates
Status: implemented and keyed. The desktop app (Electron, apps/desktop)
checks its channel's update feed — automatically in the background and on
demand — downloads an update, verifies its signature, installs it and restarts.
The signing keypair exists: the public half is compiled into the shell (key ID
DCD4A446DD335DBD). What remains before an update can actually reach anyone is
the private half in the repo secrets and a first v* tag.
- Shell:
apps/desktop/src/updater.ts(electron-updater + the signature check),src/minisign.ts, the key insrc/updater-key.ts - Config:
apps/desktop/electron-builder.json(targets,publish) - CI:
.github/workflows/release.yml,scripts/publish-update-manifests.mjs - Frontend:
packages/core/src/modules/updates/(auto.tsis the background checker;AppShellstarts it)
The channel is chosen per call
The app has a release channel, and the channel is a user setting rather than
a build-time fact — the same binary must be able to follow either. So
updater_check and updater_install point electron-updater's generic feed at
the channel's files on every call, rather than using the one electron-builder
bakes into app-update.yml.
The signature is the whole security model
The feed and the installer come over HTTPS from GitHub Releases, and HTTPS only says the bytes came from that host. Anyone who can publish a release — or take over the account — can serve an installer. electron-updater checks the download's sha512 against the feed, but feed and installer come from the same place, so that only proves the bytes arrived intact.
What makes an update unforgeable is a minisign signature made in CI with the
release key: installUpdate fetches <installer>.sig, verifies the downloaded
file against UPDATER_PUBKEY (Ed25519, BLAKE2b-prehashed — src/minisign.ts,
tested against real tauri signer output), and refuses to install, deleting the
download, if it does not match. autoInstallOnAppQuit is off, so nothing
unverified can be installed behind its back on quit. There is deliberately no
bypass, not even behind a flag.
The key is the one the Tauri shell used, and so is the tool that signs with it
(tauri signer, which writes standard minisign). That is deliberate: installs
still on the Tauri shell verify their move to Electron against the same
identity — see Moving installs off the Tauri shell.
One-time setup
Already done for this repository; written down for a new key.
pnpm dlx @tauri-apps/cli@2.9.6 signer generate -w $HOME/.tauri/horrible.key
$HOME rather than ~ because PowerShell passes a bare ~ through to a native
command literally, producing a directory called ~ in the repo.
- Public half →
UPDATER_PUBKEYinapps/desktop/src/updater-key.ts. - Private half → repo secret
TAURI_SIGNING_PRIVATE_KEY; its password →TAURI_SIGNING_PRIVATE_KEY_PASSWORD.
The private key never enters the repository. Losing it means no existing install can ever be updated again — a new key is a new identity and every client refuses a manifest it cannot verify. Back it up somewhere that is not the machine that generated it.
A development build (pnpm dev:desktop) never updates itself: updater_check
returns an error saying so rather than "up to date", which would be a lie. So
does an install electron-updater cannot update in place (a .deb, or an
unpacked directory rather than the AppImage).
Channels and the fixed manifest URL
The app reads its manifest from a permanent, non-moving release tagged
updater, not from /releases/latest/download/. GitHub resolves "latest" to
the newest non-prerelease, so a beta manifest published on a prerelease would
be unreachable there and a stable manifest would be shadowed the moment a beta
was promoted. A fixed tag has no such semantics. Only the index lives there; the
feeds point at assets on the real release — by absolute URL, which
publish-update-manifests.mjs writes in, since electron-builder writes bare file
names that would resolve against the updater release. It also merges the two
mac jobs' feeds into the one latest-mac.yml electron-updater reads.
publish-manifest runs after all four platform builds. A manifest published
earlier would offer an update that 404s on whichever platform is still building.
For the same reason the release is not a draft: a draft release's assets need an
authenticated request to download, so a manifest pointing at them would
verify-then-404 on every client.
The tag decides the channel: v1.2.3 → latest*.yml, v1.2.3-beta.1 →
beta*.yml. Switching a client from beta back to stable does not downgrade it —
it simply finds nothing until stable catches up.
Windows updates are differential: electron-builder publishes a .blockmap
beside each installer and electron-updater downloads only the blocks that changed,
which matters for an installer that carries a gigabyte of backend runtime. The
signature is still checked on the reassembled file.
Moving installs off the Tauri shell
Versions up to 0.4.4 were Tauri builds. Their updater reads updater/latest.json
(beta.json) in Tauri's format and verifies a minisign signature with the same
key — so publish-manifest keeps writing that file, pointing at the Electron
installers:
- Windows: the Tauri updater runs the new NSIS installer. It is
electron-builder's assisted installer, so the user clicks through it once. Its
customInstallhook (apps/desktop/build/installer.nsh) then removes the Tauri install silently — Tauri's uninstaller keeps app data in silent mode, and$HORRIBLE_DATA_DIRis never an installer's business anyway — and puts back the Start-menu and desktop shortcuts that uninstaller removed (both shells name them after the product). - Linux AppImage: the Tauri updater swaps the AppImage file in place, and the next start is the Electron build.
- macOS: not bridged. The Tauri updater there wants a
.app.tar.gz, which this build does not produce; those installs update by hand once.
Automatic checks
Nobody opens a settings page to ask whether their app is old, so the app asks on
its own: once about 30 seconds after launch, then on a timer, targeting one
check every six hours. packages/core/src/modules/updates/auto.ts is that
layer and nothing more — it calls the same checkForUpdate the button does, and
installing still goes through the same signature-verified updater_install.
It is started once by AppShell and is a no-op in the browser layout.
Three decisions in it are load-bearing:
- The interval is measured from the last completed check, not from process
start. A desktop app is left running for weeks and also restarted twenty
times an afternoon; keying off process start means the first kind never checks
twice and the second checks on every launch.
lastCheckedAtis persisted inlocalStorage, and the stamp is written on completion — stamping at the start would silence retries for six hours after a check that never returned. A stamp in the future (a clock that was wrong, or moved) is treated as due rather than trusted, since trusting it parks the app for the size of the skew. - A failed background check is never surfaced. "Could not ask" is a real
state and the settings section reports it, because a user who clicked deserves
the truth — but an offline laptop producing a toast every six hours teaches
people to dismiss update notices unread, which is the one habit this mechanism
cannot afford. The same reasoning caps the nagging at once per version:
notifiedVersionis remembered, so dismissing is how a user says no and a newer version is what makes it a fresh event. - There is no silent-install policy.
app.autoUpdateisnotifyornever. Anautovalue would have to mean download-and-restart, because that is what the installer does — the process is replaced. Restarting an app somebody is working in, to deliver something that was not urgent enough to interrupt them for, is worse than being one version behind. The restart is always a click the user made.
The notice is a persistent toast (duration: 0) carrying a single action.
An update notice that expires after four seconds is one a user only catches by
accident. Toast.action was added for this and is deliberately one action, not
a list: a toast that grows a row of buttons has become a dialog that does not
block, and the thing that asks is dialogs.
What an update must not touch
Everything under $HORRIBLE_DATA_DIR is versioned independently of the app:
| Thing | Keyed by | Cost to re-fetch |
|---|---|---|
llamacpp/bin/<tag>-<variant>/ | an upstream llama.cpp tag | minutes, ~100 MB |
hassault/bin/<version>/ | this app's own version | seconds, ~20 MB |
| managed GGUFs | repo + filename | tens of GB |
| activation traces | llamaBuild + modelSha | not reproducible |
libraries, LanceDB, secrets.db | nothing — they are the user's | irreplaceable |
None of it is invalidated by the app version changing, so the installer is never
pointed at that directory. This is a property of where the data lives rather
than something the updater enforces, which is exactly why it is written down.
The Fernet master key is a step further out — ~/.horrible/secrets.key, outside
the data dir entirely — so neither an update nor a data-dir copy touches it.
The bundled backend runtime
The desktop shell has always supervised the backend but never carried it: without a
repo checkout the supervisor reported unavailable — "packaged builds don't bundle the
backend yet" — which made a packaged install an app with no brain. A release now ships
one.
scripts/build-backend-runtime.mjs builds it, in CI before electron-builder runs (after,
and the installer is built around an empty directory). The output lands in
apps/desktop/backend-runtime/ and ships as an extraResources entry, outside the asar:
backend-runtime/
python/ relocatable CPython + every locked dependency in its site-packages
backend/ the backend source tree, verbatim
pyproject.toml
runtime.json what was built
A real interpreter, not a frozen binary. PyInstaller and friends freeze the import
graph at build time, and this backend's import graph is not knowable at build time:
backend/sdk/loader.py discovers plugins from bundled dirs,
HORRIBLE_PLUGINS_DIR and pip entry points, the training module spawns notebook
kernels, and dash execs user scripts. Freezing breaks all of that quietly — the app
starts and third-party plugins simply never appear. Shipping an ordinary relocatable
CPython means nothing about import resolution differs between a checkout and a package,
which is the property worth ~1 GB.
Dependencies come from uv export --frozen --no-dev — the lockfile's exact versions,
no extras. Extras are opt-in by design (torch alone is ~460 MB), every one of them is
lazy-imported, and each answers with an install hint rather than a 500.
BUNDLED_RUNTIME_DIR in apps/desktop/src/backend.ts, the --out default in
build-backend-runtime.mjs, and the extraResources entry in electron-builder.json
are the same path written three times. Only the first reports anything if they drift, and
what it reports is "no backend found" — which reads like a build that failed rather
than a name that moved.
The runtime is resolved after a repo checkout, never before. A developer running the
packaged app from their own tree wants their edits; a bundled runtime is by definition
the code as it was at release time, and silently preferring it is how you spend an
afternoon debugging a change that was never running. bundledRuntimeIn also checks
for backend/app.py and the interpreter rather than just the directory: an interrupted
install leaves a folder that exists and cannot run, and "no backend found" points at the
install while a Python ModuleNotFoundError points at nothing useful.
Two consequences worth knowing. The runtime carries no .git, so
paths.repo_root() returns None and user data resolves to the
per-OS location instead of into the installation directory — which on Windows is under
Program Files. And the installer grows: the Windows NSIS
setup measures 233 MB against 10 MB before, for 1.00 GB unpacked. Bundling
~50,000 files also makes the compression step slow — makensis spends several minutes
of CPU on it, which is worth knowing before assuming a release build has hung.
Features that shell out to uv at runtime — the training module's project venvs
(envs.install) and the notebook kernels built on them — need uv on PATH, which a
packaged install does not provide. They degrade to an error rather than working; giving
them the shipped interpreter is a separate change.
Assets that ride the release but are not in the manifest
The build-native job builds the hassault native client
for all four targets and uploads hassault-native-{win,macos,linux}-{x64,arm64} to
the same release. Those assets are not in the signed manifest and are not
touched by an update: the backend fetches the one matching this app's version
(backend/modules/hassault/client_install.py), verifies it against the sha256
GitHub publishes for the asset, and installs it under $HORRIBLE_DATA_DIR — where,
per the table above, an installer never reaches.
Two things follow that are easy to get wrong. publish-manifest needs
both build jobs: a manifest is what makes a release reachable, and a release
reachable before its client assets exist is one where every Install button answers
"publishes no client for your platform". And the asset names are a contract with
client_install.asset_name, which computes the name rather than matching loosely
— these are names we control, so a rename should be a clear miss rather than a
wrong download. backend/tests/test_hassault_client_install.py reads the workflow
file and pins them.
The client is a download rather than part of the installer because it is versioned and
launched by the backend (the route that starts it is a backend route), and lives
under $HORRIBLE_DATA_DIR with everything else an installer must not touch.
Bundle targets
Targets (electron-builder.json): nsis (Windows — an assisted, per-user
installer; there is no MSI, which could not update a running app anyway), dmg +
zip (macOS — the zip is what the mac updater consumes), and AppImage + deb
(Linux — only the AppImage updates itself).
Nothing here is code-signed by a platform authority yet, so Windows SmartScreen and macOS Gatekeeper will both warn on first launch. That is a separate, paid problem from update signing, which is about this app trusting its own updates and is what actually stops a malicious update. One platform makes it more than a warning: macOS will not apply an update to an app that is not code-signed (Squirrel.Mac requires it), so until there is an Apple Developer ID the mac build checks and downloads, and then the install fails with that reason.