# Auto-updates

Publish signed releases from any static host and let a built app download and install them itself: one key pair, one `tarve release` command and three calls in your app.

## How it works

`tarve release` copies your built executables to an output folder and writes `latest.json`: the version, notes and, for each platform, the file URL, size and SHA-256, signed with your Ed25519 private key. Upload the folder anywhere that serves files over HTTPS: GitHub Releases, S3 or R2, a CDN or your own server.

The app embeds the public key. `checkForUpdate` downloads `latest.json`, rejects it unless the signature matches, and compares the version with the one baked in by `tarve build`. The download is checked against the signed size and hash, so a compromised host or CDN cannot ship a different binary.

## Set up

1. ### Create a signing key

   Once per app. Store the private key in your CI secrets (as `TARVE_UPDATE_PRIVATE_KEY`) and never commit it. If you lose it, installed copies can no longer be updated.

   ```sh
   bunx tarve keygen
   # private key: ./tarve-update.key (keep it secret and out of git)
   # public key:  wVZvRojxPspr35X0YYJ0QRePrwDLUEWhY9pS1Ou7iVQ=
   ```

2. ### Build with a version

   `--version`, or the `version` of a `package.json` with a `"tarve"` field.

   ```sh
   # the version is baked into the executable; checkForUpdate compares against it
   bunx tarve build app.tsx --version 1.2.0 --outfile dist/win/App.exe
   bunx tarve build app.tsx --version 1.2.0 --target linux-x64 --outfile dist/linux/App
   ```

3. ### Release

   ```sh
   bunx tarve release --version 1.2.0 \
     --artifact win32-x64=dist/win/App.exe \
     --artifact linux-x64=dist/linux/App \
     --public-key wVZvRojxPspr35X0YYJ0QRePrwDLUEWhY9pS1Ou7iVQ= \
     --notes "Faster startup" \
     --out dist/updates
   # dist/updates/latest.json
   # dist/updates/App-1.2.0-win32-x64.exe
   # dist/updates/App-1.2.0-linux-x64
   ```

4. ### Upload

   Upload the contents of `dist/updates` and keep `latest.json` at a stable URL. Upload the executables first and `latest.json` last, so no client sees a manifest whose files are not there yet.

5. ### Check from the app

   ```tsx title="updates.ts"
   import { canInstallUpdate, checkForUpdate, downloadUpdate, installUpdate } from "@tarve/core";

   const UPDATES = {
     url: "https://example.com/my-app/latest.json",
     publicKey: "wVZvRojxPspr35X0YYJ0QRePrwDLUEWhY9pS1Ou7iVQ=",
   };

   export async function updateIfAvailable(onProgress: (percent: number) => void) {
     const update = await checkForUpdate(UPDATES);
     if (!update) return; // up to date, or no build for this platform
     if (!canInstallUpdate()) {
       // installed by a package manager or in a read-only folder: point the user to a download instead
       return;
     }
     const file = await downloadUpdate(update, {
       onProgress: (received, total) => onProgress(Math.round((received / total) * 100)),
     });
     installUpdate(file); // swaps the executable, starts the new version and exits
   }
   ```

## App packs: updates without the runtime

A built executable is mostly runtime: Bun, Node.js or txiki.js and the native library, about 100 MB. Between two releases only your code and files change. An executable built with `--packs` also runs **app packs**: `.tarve` files, like Electron's `app.asar`, holding the app's bundled code and files. A release then downloads a few hundred kilobytes instead of the whole executable.

Unlike asar, a pack is signed with your update key (Ed25519 over a header that lists the SHA-256 of every file), compressed and encrypted (AES-256-GCM, with a key derived from your private key). The executable verifies it on every launch and decrypts the code in memory: it never reaches the disk in clear. Encryption keeps the code out of reach of anyone who downloads the pack; the key is inside the executable, so it slows down, but cannot stop, someone who takes that apart.

A pack runs only in executables of the same Tarve version, runtime and platform that provide its native features and plugin libraries. When a release changes any of those, ship the executable as well: `checkForUpdate` picks the executable for clients that cannot run the pack. Build the pack with the same name, app id and icon as the executable (the `"tarve"` field of `package.json` keeps them in one place).

```sh
# once: an executable that also runs app packs (keeps the private key out of it: only a derived key goes in)
bunx tarve build app.tsx --version 1.2.0 --packs --outfile dist/win/App.exe

# each release: the app's code and files, signed and encrypted (a few hundred KB)
bunx tarve pack app.tsx --version 1.2.1
bunx tarve release --version 1.2.1 \
  --pack dist/App-1.2.1-win32-x64-bun.tarve \
  --artifact win32-x64=dist/win/App.exe
# executables built with --packs download the pack; older ones, and any that cannot run it, get the executable
```

## Windows code signing

The update signature only protects the updater. Windows has its own trust: without an Authenticode signature, SmartScreen warns on first launch and antivirus software is more suspicious. `--sign` runs your signing tool on each Windows executable before it is hashed, so `latest.json` describes the signed file. The executable in your build folder is not modified. Linux artifacts are skipped.

Any tool works: `signtool`, Azure Trusted Signing, `osslsigncode`. Tarve fails the release if the command exits with an error, leaves the file unchanged or turns it into something that is no longer an executable. Certificates come from a certificate authority (OV or EV) or from Azure Trusted Signing. SmartScreen reputation builds up over downloads, even with EV.

```sh
# signtool (Windows SDK), any certificate in the store or a .pfx
bunx tarve release --version 1.2.0 --artifact win32-x64=dist/win/App.exe \
  --sign "signtool sign /fd sha256 /tr http://timestamp.digicert.com /td sha256 /a {file}"

# osslsigncode from Linux or CI
export TARVE_SIGN_COMMAND='osslsigncode sign -pkcs12 cert.pfx -pass "$PFX_PASS" -h sha256 -t http://timestamp.digicert.com -in {file} -out {file}.signed && mv {file}.signed {file}'
bunx tarve release --version 1.2.0 --artifact win32-x64=dist/win/App.exe
```

## latest.json

The payload is signed as it is, byte for byte. Never edit it by hand: run `tarve release` again.

```tsx title="latest.json"
{
  "payload": "{\"name\":\"App\",\"version\":\"1.2.0\",\"pubDate\":\"2026-10-15T12:00:00.000Z\",\"platforms\":{\"win32-x64\":{\"url\":\"App-1.2.0-win32-x64.exe\",\"sha256\":\"9f2c…\",\"size\":118712320}}}",
  "signature": "Base64 Ed25519 signature of payload"
}
```

## What is validated

| Stage | Checks |
| --- | --- |
| `Manifest` | Ed25519 signature over the exact payload; version, date, platform names, URLs, 64-hex SHA-256 and positive integer sizes; at most 1 MiB. |
| `Transport` | HTTPS only, for both latest.json and the artifacts. Plain HTTP is accepted for localhost, or everywhere with allowInsecure. |
| `Identity` | A manifest whose name differs from the app's name is rejected, so one key can sign several apps safely. |
| `Version` | Only strictly newer versions are offered: no downgrades, no reinstalling the same build. |
| `Download` | Content-Length and byte count must equal the signed size, the SHA-256 must match, and the file must start like a Windows (MZ) or Linux (ELF) executable. A failed download is deleted. |
| `App pack` | On every launch: the Ed25519 signature over its header, the SHA-256 of each file it reads, AES-256-GCM, its name, version (newer than the embedded app), runtime, platform, Tarve native ABI, plugin libraries and native features. A pack that fails is skipped; one that throws or crashes while starting is marked bad and the previous pack, or the embedded app, runs instead. |
| `Install` | Refuses to overwrite bun, node or txiki themselves, missing or non-executable files, and executables in read-only folders. On Windows the old executable is restored if the swap fails. |
| `Release` | Version format, platform names, duplicate platforms, missing, empty or wrong-format artifacts, HTTP base URLs, a key that does not match --public-key, and a --sign command that fails, leaves the file unchanged or corrupts it. |

## Where self-updating works

An app can only replace itself when it may write to its own folder: a per-user location such as `%LOCALAPPDATA%\Programs` or `~/.local/bin`, or a portable folder. Under `Program Files`, `/usr/bin` or a package manager, `canInstallUpdate()` returns false and the update should go through that installer instead. `tarve run` and `tarve dev` never self-update: there the executable is Bun or Node itself.

On Windows the running executable is renamed to `App.exe.old`, the new one takes its place and the next update check deletes the old file. App packs install in a per-user folder, so they work under `Program Files` too.

## tarve release options

| Option | Meaning |
| --- | --- |
| `--version 1.2.0` | Required. The release version; it must be newer than the installed one. |
| `--artifact platform=path` | Repeatable. platform is os-arch as in process.platform/process.arch: win32-x64, linux-x64. |
| `--key path \| base64` | Private key. Defaults to TARVE_UPDATE_PRIVATE_KEY, then ./tarve-update.key. |
| `--public-key base64` | The key your app ships with. The release fails when the private key does not belong to it. |
| `--pack path` | Repeatable. An app pack from tarve pack; it is listed under the platform and runtime it was built for. |
| `--sign command` | Authenticode command run on each Windows artifact before hashing; {file} is the quoted path. Defaults to TARVE_SIGN_COMMAND. |
| `--base-url https://…/` | Absolute prefix for artifact URLs, for a CDN. Without it, URLs are relative to latest.json. |
| `--name App` | Recorded in the manifest; apps built under another name reject it. |
| `--notes text` | Release notes, returned as update.notes. |
| `--out dist/updates` | Output folder for latest.json and the renamed artifacts. |

## API

Exported by `@tarve/core`.

| Function | Description |
| --- | --- |
| `checkForUpdate(options)` | Fetches latest.json, checks its signature and fields, and resolves the newer Update for this platform or null. update.kind is "pack" when this executable can run the release's app pack, else "executable". Options: url, publicKey, currentVersion, platform, name, allowInsecure, fetch, signal. |
| `downloadUpdate(update, options?)` | Streams the artifact next to the executable and checks its size, SHA-256 and executable format. Options: onProgress, path, allowInsecure, fetch, signal. |
| `installUpdate(file, options?)` | Replaces the executable (or installs the app pack in its per-user folder) and, by default, starts the new version with the same arguments and exits. Options: executable, restart, args. |
| `canInstallUpdate(update?)` | Whether this process can install the update: an app pack whenever the executable runs packs, an executable when it is a built app in a writable folder. |
| `cleanupUpdate(executable?)` | Removes the previous executable left behind on Windows; checkForUpdate already calls it. |
| `compareVersions(a, b)` | Semver ordering: 1.10.0 > 1.2.0, 1.0.0 > 1.0.0-rc.1, build metadata ignored. |
| `verifyUpdateManifest(signed, publicKey)` | The signature and field checks of checkForUpdate, for custom transports. |

---

Tarve v0.13.8 · HTML version: https://tarve.dev/docs/updates · Index for agents: https://tarve.dev/llms.txt
