Agent Island Install and Update Troubleshooting

Almost every install or update problem is one of four things: the wrong package, a macOS quarantine flag, a package manager sitting a release behind, or an update that installed while the old process was still running. This guide works through them in the order that resolves the most cases first.

Before you start

You know where you installed from — GitHub release, Homebrew, WinGet, or Scoop

1. Identify the install you actually have

The fix depends on the source, so start here. Homebrew, WinGet, and Scoop can all lag behind the current GitHub release.

macOS — what the tap offers:

brew info tristan666666/tap/agentisland

If the tap looks stale, refresh its metadata before anything else:

brew update && brew upgrade tristan666666/tap/agentisland

You should see: a version that matches the latest release. If it still lags, install the DMG directly

2. Clear the macOS quarantine flag

Agent Island is signed ad hoc rather than with a paid Developer ID, so macOS can refuse the first launch with "app is damaged and can't be opened". That message means quarantine, not a corrupted download. The Homebrew cask strips the attribute for you; a manually mounted DMG may not.

xattr -dr com.apple.quarantine /Applications/AgentIsland.app

The -r matters: the updater lives in a nested bundle, and a non-recursive strip leaves it quarantined — which then shows up later as "updater failed to start".

You should see: the app opening normally on the next launch, and Check for Updates working

3. Fix a Windows launch that closes immediately

Windows marks archives downloaded from the internet, and the app can exit on start because of it. Unblock the ZIP before extracting: right-click the file → Properties → tick Unblock → Apply, then extract again into a folder you own.

Extracting into a protected location such as Program Files with a copy that was never unblocked reproduces the same exit.

You should see: Agent Island staying resident in the system tray after launch

4. Make sure updates can reach you

macOS updates arrive through Sparkle with a signed appcast. In Settings → General, confirm Check for updates automatically is on, then use Check now to test the path immediately.

A silent Check now has two innocent causes: you are already on the newest build, or you are running a build made with update checking disabled.

You should see: either an update sheet, or a clear confirmation that this is the newest version

5. Quit fully before updating

An update can replace the app on disk while the old process keeps running and keeps reporting the old version. Quit from the island menu (Quit Agent Island) rather than just closing a panel, then relaunch.

You should see: the version in the app matching the release you expected

6. Reinstall as the last step, not the first

Preferences are keyed to the bundle identifier and survive a reinstall, so reinstalling loses nothing — but it also fixes nothing that the four steps above have not already covered. Reinstall from your original channel to keep future updates on the same path.

If it does not work

Homebrew keeps installing an older version

Tap metadata is cached — brew update first. If it is still behind, the tap has not been bumped yet; install the DMG from the release page.

"App is damaged and can't be opened"

Quarantine, not corruption. Apply step 2. If it survives that, re-download over HTTPS and compare the file size against the release asset.

"Updater failed to start"

The nested updater bundle is still quarantined. Re-run the xattr command with -r so it reaches the whole bundle.

Update installs but the version does not change

The old process was running during the swap. Quit fully, relaunch, and check again.

Windows update did not appear

Windows builds are attached to the same release as macOS but do not use Sparkle. Download the current ZIP from the release page and replace the folder.

For how updates are signed and verified end to end, read secure macOS updates.

← All guides