Verified against the public Agent Island v1.7.1 release on 2026-07-31. The release contains a universal macOS DMG and a Windows x64 ZIP. GitHub Releases is the version authority when a package manager and the release page disagree.
Start with the package you actually downloaded
On macOS 13 or newer, use AgentIsland-1.7.1.dmg. It contains an app that runs on Apple silicon and Intel Macs. Drag the app into /Applications before launching it. Running the copy from the mounted disk image makes later replacement and update checks harder to reason about.
On Windows 10 or 11 x64, use AgentIsland-1.7.1-win-x64.zip. Extract the archive to a normal folder and run AgentIsland.exe from the extracted directory. Starting the executable inside the compressed archive can leave dependencies unavailable to the process.
If you used Homebrew, WinGet, or Scoop, ask that package manager for its installed version first. A successful install command only proves that the package manager installed the version in its own index.
# macOS
brew info tristan666666/tap/agentisland
# Windows
winget list AgentIsland
scoop info agent-island/agentislandmacOS says the app cannot be opened
Agent Island does not currently use a paid Apple Developer account. The macOS package is ad-hoc signed rather than notarized. On the first launch, open Finder, locate Agent Island in Applications, right-click the app, and choose Open. Confirm the macOS prompt from that path.
This is different from disabling Gatekeeper globally. A per-app first launch preserves the operating system check for other downloads. After macOS records the choice, normal launches can use Spotlight, Finder, or Login Items.
If the app still fails, verify that you moved the app out of the DMG and that an older copy is not running. Activity Monitor should show at most one Agent Island process. Replace the copy in Applications only after the old process exits.
Package-manager installs need a version check
The official package commands are:
brew install tristan666666/tap/agentisland
winget install TristanTang.AgentIsland
scoop bucket add agent-island https://github.com/tristan666666/scoop-bucket
scoop install agent-island/agentislandPackage indexes can update after a GitHub release. Compare the offered version with the tag shown by the latest public release. If the package manager is behind, either wait for its index to refresh or install the release asset directly. Do not combine a direct install and a package-manager install without checking which executable starts.
A missing update prompt has two possible causes
Agent Island v1.7.1 checks the GitHub Releases API shortly after launch and then every six hours when automatic checks are enabled. A newer version opens a two-button prompt. Choosing the reminder option snoozes that version for seven days; a still newer release can prompt sooner.
Open Settings and use Check now when you need an immediate answer. That check should return one of three states: a newer release, up to date, or a request failure. A network filter that blocks GitHub API requests can produce the third state even when the app itself runs normally.
Builds older than v1.7.1 may not have the GitHub-backed update nudge. Those users should compare their installed version with the release page and update through Homebrew or a fresh download. Installing v1.7.1 or later establishes the current update-check path.
Know which mechanism verifies an update
The macOS app includes Sparkle and an embedded EdDSA public key. Sparkle verifies a signed update package before installation when an appcast-driven update runs. The GitHub-backed update nudge is separate: it discovers the latest version and opens the public release page.
This distinction matters during diagnosis. A GitHub request failure blocks discovery. A signature failure blocks installation. They have different logs and should not be collapsed into one generic updater error.
Windows opens, then closes immediately
Confirm that the ZIP was fully extracted and that Windows is starting the executable from the extracted folder. Then check whether Windows Security quarantined a file from the archive. Restore a file only after matching the archive to the official GitHub release and reviewing the source or release details.
Agent Island stores its Windows settings under the current user's roaming application-data directory. Re-extracting the ZIP does not automatically remove those settings. That is useful for upgrades, but it also means reinstalling the binary cannot repair every configuration problem.
Collect a small, non-sensitive report
A useful install report contains the operating system version, Agent Island version, install method, exact stage that failed, and the visible error text. Do not attach Claude Code or Codex transcripts, provider tokens, OAuth data, or private project paths. The install path can be diagnosed without uploading session contents.
When the app launches but shows no sessions, continue with the session detection checklist. Installation and discovery are separate paths.