HTML Clay
  1. HTML Clay
  2. Guide
  3. Updates

Updates

How HTML Clay checks for new versions, installs updates from the tray menu, and behaves on macOS, Windows, and Linux.

HTML Clay checks for updates in the background, downloads new releases, and waits for you to install them from the tray menu. Open tabs and save permissions carry over across the restart.

Install an update#

While you are on the latest release, the top row of the tray menu shows the installed version, such as HTML Clay v1.13.8. When a new version has been downloaded and staged, that row changes to Restart to Update (vX.Y.Z).

  1. Click the HTML Clay icon in your menu bar or system tray.
  2. Click Restart to Update (vX.Y.Z).
  3. If an AI edit or a document program is running, HTML Clay asks Restart HTML Clay now to update to vX.Y.Z? Click Restart to stop the running task and continue.

Before restarting, HTML Clay waits for 500 ms with no file writes, up to 5 seconds. While the restart is in progress, save requests receive HTTP 503 with Retry-After: 2 and code restarting.

HTML Clay hands your open documents, save tokens, and permissions to the new process through update-handoff.json in the configuration folder, so your open browser tabs keep working and saving after the update finishes.

If the restart cannot complete right away, HTML Clay notifies you that it is still running the current version and keeps Restart to Update in the tray menu so you can try again. If the new version fails to start serving, HTML Clay rolls back to the previous binary and skips the failed version until a newer release is published.

How updates work by platform#

macOS#

On macOS, HTML Clay updates through Sparkle. Self-update requires HTML Clay to run from a writable .app bundle that includes an Ed25519 public key (SUPublicEDKey) and an X.Y.Z release version.

If macOS runs HTML Clay from a translocated path after download, self-update is disabled. Move HTML Clay to Applications so it can update itself.

If Sparkle does not quit the app within 40 seconds of clicking Restart to Update, HTML Clay reopens file writes and notifies you that the update will finish the next time you quit HTML Clay. Whenever Sparkle has prepared an update, quitting HTML Clay normally also installs it.

On macOS, you can also trigger an update from the terminal:

Shell
htmlclay update-now --version 1.13.8

The command asks the running HTML Clay process to update and prints accepted, already X.Y.Z, refused <reason>, failed <reason>, or starting, exiting with code 0 through 6.

Windows and Linux#

On Windows and Linux, HTML Clay uses its built-in signed-feed updater:

  • It checks https://download.htmlclay.com/update/stable.json 60 seconds after launch and every 6 hours after that.
  • It only accepts a feed signed by a built-in Ed25519 key.
  • It stores the highest version ever offered in updates/seen.json inside the configuration directory and refuses any older version.
  • It downloads and stages the new binary beside the existing installation and never replaces the running binary until you click Restart to Update (vX.Y.Z).

You can point the updater at an alternate signed feed by setting the HTMLCLAY_UPDATE_FEED environment variable.

When self-update is off#

Self-update is turned off when any of the following is true:

  • You set "updates": "off" in config.json.
  • The folder or .app bundle where HTML Clay is installed is not writable.
  • HTML Clay is running without a system tray (-no-tray).
  • On macOS, the app is running outside an .app bundle, is translocated, has no SUPublicEDKey, or Sparkle fails to start.
  • You are running a custom build without a release X.Y.Z version, update channel, or built-in signing key.

When self-update is off and the tray is active, HTML Clay checks https://download.htmlclay.com/htmlclay-release-info.json once at startup with a 5-second timeout. If a newer release is out, the tray menu shows Update available: vX.Y.Z, which opens the download page in your browser when clicked.