Auto-update internals

Channels, the latest.yml manifest format, the runtime update flow, and how to host your own feed.

The Getting Started version covers what an ordinary user needs. This page is for understanding the moving parts or hosting a custom update feed.

Release channels

Channel	Manifest URL
stable	`https://github.com/ProjectKumo/KumoApp/releases/latest/download/latest.yml`
beta	`https://github.com/ProjectKumo/KumoApp/releases/download/pre-release/latest.yml`

Settings → Updates can override the manifest URL for private feeds or local testing. Leave it blank to use the channel default.

Manifest format

latest.yml is published alongside each release:

version: 0.0.1
channel: stable
downloadURL: https://github.com/ProjectKumo/KumoApp/releases/download/0.0.1/Kumo-macos-0.0.1-arm64.dmg
assetName: Kumo-macos-0.0.1-arm64.dmg
sha256: <64-character-sha256>
releaseNotes: |
  See https://github.com/ProjectKumo/KumoApp/releases/tag/0.0.1

The same fields are accepted as JSON, for local testing and backwards compatibility.

Runtime flow

AppUpdateManager polls the manifest every five minutes.
When a new version is found, Kumo posts a macOS notification with three actions:
- Install Now
- Remind Me Later
- Restart Now (once the download is ready)
The download writes to ~/Library/Application Support/Kumo/updates/downloads/.
The detached DMG installer logs to ~/Library/Application Support/Kumo/logs/app-update-installer.log.
The installer mounts the DMG, copies Kumo.app over the current install, and re-launches the app.

The SHA-256 in the manifest is verified against the downloaded artifact before the installer is invoked. A checksum mismatch aborts the update.

The download is asynchronous and resumable. If Kumo is closed mid-download, the next polling cycle picks up where it left off.

Auto-replacement requires the current app's parent directory to be writable. If Kumo is in a protected location (or installed for the whole machine), the update flow reports a clear error and the DMG can be installed manually from the download page in Settings → Updates.

Host your own feed

To host a custom feed (for private builds, an internal beta, or anything else):

Build a notarized DMG.
Compute its SHA-256.
Publish latest.yml with the fields above.
Point Settings → Updates → Manifest URL at your latest.yml.

Anything that can serve static files over HTTPS works — S3, R2, GitHub Pages, a private nginx, and so on.

Manual check

Open Settings → Updates and click Check for Updates. The same check is also exposed in the custom About window.

Roll back

To roll back to a specific release:

Download the DMG for the desired version from GitHub Releases.
Quit Kumo.
Replace /Applications/Kumo.app with the version from the DMG.
Launch Kumo.

state.json and preferences.json decode missing fields with defaults, so downgrades do not invalidate persisted state. Features added in newer versions will of course be absent.