Updating Koyd

Update from the app

1. When a signed release is available, an Update button appears in the workspace header. Settings → General shows the app and server versions and offers Check for updates.
2. Choose Update to download and verify the server, core, runtime, dependencies, and PWA as one package. Progress appears in a banner at the top of the app.
3. Let active turns, queues, swarms, and background agent work finish. Close terminals and browser sessions, and stop custom app backends and app AI work.
4. Koyd waits for an idle instance, saves a backup, restarts the new version, and verifies its identity and readiness.
5. The client reconnects and checks for its app update. When the PWA is served by that server, the same action activates the new app assets. Other connected browsers notice the new server version and offer their own app update in the header.

Good to know · The server computer must stay awake. The brief restart disconnects clients. Connect over Wi-Fi sharing turns off at restart; re-enable it on the server computer before reconnecting other devices. Other instances on the machine keep running on their existing releases until they are restarted.

What is checked

The server accepts only newer stable releases for its own platform and processor. It verifies the publisher’s Ed25519 signature, the archive’s signed size and SHA-256 checksum, safe archive paths, and the package’s file manifest before preparing the release.

The previous program remains intact. The installed command switches only after the new server passes its startup and identity checks. If startup fails and shutdown can be verified, Koyd restores the saved data snapshot and starts the previous version.

Where one-click updates are available

Automatic restart is available for the current release of a per-user installation running through koyd start. Portable, source, custom-path, and foreground/service-managed deployments use the manual process below.

A build predating the server updater needs one manual installation of an updater-enabled release. A separately hosted PWA gets assets from its own host; updating a connected server cannot publish a new client to that host.

Manual update

1. Download and extract the complete matching server package.
2. Run its installer. Existing server data, config, and already-running versions are preserved.
3. When ready, use koyd stop followed by koyd start for the instance you want to update.
4. Refresh the client when it offers a new PWA version.

koyd stop
koyd start --open

For a service manager, stop the service, install the matching release, and restart using the manager. Preserve your instance’s data, configuration, and endpoint.

If an update needs attention

A failed download or signature check leaves the running version untouched. Read the update notice and try again after fixing connectivity or disk space. A corporate firewall, VPN or intercepting proxy such as Zscaler is named as the likely cause when it blocks the download. Koyd does not force-kill an unverified process to complete an update.

While the server restarts for an update, the app says so and reconnects on its own; the usual connection-lost warning is kept for outages that are not part of an update. If the server has not come back after five minutes, the app asks you to run koyd start on the server computer.

The installation’s update.log and update-state.json record restart progress. An interrupted transaction may leave a .koyd-update.json marker beside the data directory, a backup, and failed-start data. You do not need to remove that marker: the next koyd start checks that the updater has stopped, restores the complete backup when the new version was never activated, and reports the outcome in the app. Backups and failed-start copies are kept for you to review.

Disk space and retained versions

Allow room for the compressed download, extracted package, new installed version, and a complete data-directory backup. Previous versions and backups are retained for recovery. Clean them up only after verifying the update and ensuring no running instance still uses them.