What a macOS updater can verify, and what it cannot
Separate release discovery, package signatures, and first-launch approval before diagnosing an update failure.
An update prompt looks like one action, but the macOS path crosses three different trust decisions: release discovery, package verification, and first launch. Keeping them separate made Agent Island's updater easier to reason about and easier to support.
I help run Agent Island, an open-source local status companion for Claude Code and Codex. This note records the boundary we use in the current macOS build.
Release discovery answers only "is there a newer version?"
The app checks GitHub Releases shortly after launch and then every six hours when automatic checks are enabled. A manual Check now action uses the same public source.
The response gives us a release tag and public release page. A numeric dotted comparison can tell whether that tag is newer than the installed version. It cannot authenticate a DMG, and it cannot distinguish a malicious replacement package from the genuine build.
This distinction is useful during failures. If a firewall blocks the GitHub API, the version lookup can fail while the installed app keeps working. That is a discovery problem, not a corrupt application.
Sparkle authenticates the package
The macOS build includes Sparkle for the package update path. Its appcast declares the version, package URL, and EdDSA signature. Sparkle verifies that signature against a public key embedded in the installed app.
The matching private key stays outside the application bundle. A changed package URL is not enough to produce a valid update. The package still needs a signature from that key.
This gives each component one job:
- GitHub Releases says which public version is current.
- Sparkle decides whether the downloaded update is trusted.
A useful error should preserve that separation. "Could not check the latest version" and "downloaded update failed signature verification" point to different investigations.
Gatekeeper controls the first launch
Agent Island does not currently use a paid Apple Developer account. The macOS package is ad-hoc signed rather than notarized, so first launch requires Finder's right-click and Open flow.
That is a separate macOS trust decision. Gatekeeper decides whether the downloaded application may run. Sparkle's EdDSA check protects later update packages. Disabling Gatekeeper for the whole machine would remove a wider system control just to solve one app's first launch.
A per-app approval keeps the exception narrow.
Older builds may need one manual update
Adding an updater framework does not automatically rescue every historical install. A build can contain the framework while its feed is empty or its version-discovery path is incomplete.
The current GitHub-backed version nudge is present from Agent Island v1.7.1. An older build may need one manual comparison and download before it enters that path. Telling those users to wait for an automatic prompt would be inaccurate.
A support report needs six facts
When an update fails, these details usually locate the boundary:
- Installed Agent Island version.
- macOS version.
- Direct DMG or Homebrew installation.
- Result of Check now.
- Whether discovery or installation failed.
- Exact visible error text.
Claude Code transcripts, provider tokens, OAuth data, and private project paths are not needed for this investigation.
The canonical implementation note is Verifiable macOS Updates. The important design rule is to name each trust decision before trying to fix it.
Comments
Join the discussionNo comments yet. Be the first to comment.
