Updates
How AgentGrid auto-updates and how to force a clean reinstall.
AgentGrid ships an auto-updater so installed copies stay current with the latest release. You can let it run automatically or manage updates from Settings -> Updates.
How auto-update works
AgentGrid uses electron-updater against the public GitHub Releases repository:
https://github.com/agent-grid/agent-grid-releases/releasesOn startup (and on a schedule while the app is running) it resolves the latest stable release metadata, compares it against the running version, and downloads the immutable versioned build in the background if one is available. The Update ready banner appears once the download is staged. Click What's new in the banner to read the release notes for every version between the one you have and the one you're about to install. Close the notes with X, EscEsc or a click outside them, and the update stays ready to install. After the update installs, the first launch shows a What's new card for the new version. If the release has a clip, it plays muted on a loop, with controls to unmute or scrub, and stays paused if your system asks to reduce motion.
In Settings -> Updates you can:
- See the current version, update status, staged version, and last check time.
- Run Check for updates manually.
- Turn automatic background updates on or off.
- Choose Install and restart to download an available update and install it, or install an update already staged.
Install updates automatically takes effect immediately. With it off, AgentGrid does not check or download in the background or install on quit. Check for updates only checks the feed; choose Install and restart to download and install an available version.
After a manual download, AgentGrid waits for running work automatically. For an already staged update, Install and restart offers Restart when finished if panes are still active. AgentGrid waits for team leads, workers, Coordinator turns, queued messages, and background work to finish before restarting; you can cancel the pending restart or choose Install now later.
You can also ask the Coordinator to update AgentGrid: it checks for the latest version, downloads it and restarts, unless work is still mid-turn; tell it to update anyway to interrupt that work.
Quitting while work is running does not install a staged update, except on Windows with the background service off (below). Finish the work before installing the update.
On Windows, the installer starts only after AgentGrid has fully closed. If shells that AgentGrid started are still sitting in the install folder, the update closes those and continues. An app you opened yourself, such as your own terminal or editor, is named in Close these apps to finish the update, and the version you have stays until you close it. With automatic updates on and the background service off, quitting while work runs installs the update anyway, because quitting ends that work, and an update still waiting after a crash installs the next time AgentGrid opens with nothing running. If a Windows update still won't install, close the apps named in that list, or restart Windows and try again, or download the latest installer. On a Windows computer set to British Columbia, with no time zone saved in AgentGrid, the account picker stays on Pacific time all year.
Previously installed builds still read the legacy Vercel Blob updater feed. During the migration window, each release also publishes versioned binaries and updater metadata there so those installations can move onto a GitHub-enabled version.
The public release repository backs the marketing site's download page. /api/download/{mac|win|linux-appimage|linux-deb} on agentgrid.sh prefers verified GitHub release metadata and redirects to its immutable asset URL. Until the first complete GitHub release is available, the site falls back to the existing Blob downloads.
On macOS, if you reopen AgentGrid while an update is installing, a notice explains that installation can take a few minutes. AgentGrid closes that launch and reopens after the installer finishes. Let the installation finish before trying again.
Update channel and platforms
| Platform | Target | Channel | Architecture |
|---|---|---|---|
| macOS | .dmg, .zip | Latest stable release | arm64 (Apple Silicon) and x64 (Intel) |
| Windows | NSIS .exe installer | Latest stable release | x64 and arm64 |
| Linux | .AppImage and .deb | Latest stable release | electron-builder default |
macOS ships both arm64 and x64 dmgs. electron-updater picks the build that matches the running Mac from the same latest-mac.yml manifest — Apple Silicon and Intel each auto-update to their matching arch.
On Windows on ARM, choosing to install for all users puts the ARM64 build in C:\Program Files\AgentGrid rather than Program Files (x86). Before each release, every Windows installer is checked to make sure it unpacks the complete app on its architecture.
When auto-update can't progress
If Check for updates reports that update checks are unavailable, restart AgentGrid or reinstall the latest version. Manual checks work with automatic updates turned off.
If the app reports any other update failure, or you want to drop back to a clean state, force a reinstall:
- Quit AgentGrid fully (check the tray / dock — the single-instance lock means a hidden copy will block a fresh launch).
- Download the latest installer from agentgrid.sh/download.
- Run the installer over the top of the existing install. On macOS, drag the new
.appinto/Applicationsand replace. - Launch AgentGrid. Your
userDatadirectory carries over, so spaces, recent projects, and paired mobile devices stay intact.
If you want to also reset state, delete the userData directory between steps 1 and 4 — see Logs and diagnostics.
Code signing and notarization
The macOS build runs with the hardened runtime and is notarized by Apple. If macOS refuses to open the app the first time, right-click the .app and choose Open to bypass the Gatekeeper warning once.
Windows releases are code-signed. A valid current installer should identify AgentGrid as the publisher rather than showing the older unsigned-build warning.