Release Channels & Updates

Swarmfile installs update themselves, but never silently and never without you saying so. This page covers where installers come from, how updates are delivered and verified, and how to reinstall a machine cleanly.

Where installs come from#

A machine's hosts are baked into its install, not compiled into the binary: packaging writes the hub, identity, site, and update endpoints into the bundled config.json, so a staging install stays on staging. See Engine Config File.

Installers are available two ways under releases.swarmfile.com:

• Stable aliases - releases.swarmfile.com/latest/Swarmfile.pkg, .../latest/Swarmfile.dmg, .../latest/swarmfile-amd64.deb, .../latest/Swarmfile-Setup.exe (Windows ARM64), .../latest/Swarmfile-x64-Setup.exe, and the bare .msi files. These are what the download page links.
• Versioned paths - releases.swarmfile.com/v0.2.35/Swarmfile.pkg and so on, so a scripted install can pin an exact build whose SHA-256 stays valid. Each artifact ships with a .sha256 file and there is a combined SHA256SUMS per release. Homebrew, winget, and Chocolatey packages point at the same signed artifacts.

Use the stable aliases for people and the versioned paths for automated fleet installs.

How updates work#

Updates live in the Desktop App, not the engine:

• It checks once at startup and then every 45 minutes while running. Repeated failures back off, up to about every six hours.
• A found update only raises a notification: a pill in the header and a card in Diagnostics. Swarmfile never installs an update on its own - Install now is the only path, and that is deliberate: an unattended restart while a save or render is running is worse than being a few days behind.
• If an update sits uninstalled for a week, the Desktop App sends one desktop notification naming the version - still informational, still install-on-your-command. (A restart re-raises the pill, so the nudge is for the tray that stays running for weeks.) You can also press the manual Check for updates action in Diagnostics at any time.

What happens when you press Install now differs by platform:

• macOS and Windows - the app downloads the signed package and installs it, then restarts itself (and its engine). On Windows an unelevated app starts the Swarmfile Updater helper (an on-demand, never-auto-triggering SYSTEM task) which verifies the package signature and applies it.
• Linux - the app cannot self-install (it runs as your user, and package installation needs root). It shows a notification pointing at the .deb for you to install; there is no silent privilege escalation.

There is no beta, nightly, or insider channel. Every release publishes to the single stable channel; staging is a separate environment (its own hosts and buckets), not a different update channel.

Update integrity#

Updates are verified before they are applied:

• The update manifest's artifacts are signed with a project Ed25519 (minisign) key. The public key is compiled into the app and into the Windows updater helper, so a compromised update server cannot hand you a package that verifies - the endpoint can be moved, the trusted key cannot.
• The app itself refuses an update whose signature does not verify, and refuses a manifest that is not strictly newer than the installed version.
• macOS installers are Developer ID-signed and notarized/stabled. Windows release installers are Authenticode-signed in the release pipeline. Linux .debs are not distro-signed (no apt repository key); verify them against the published .sha256/SHA256SUMS and rely on the updater's own signature when updating.
• Installing an older version over a newer one is not supported: the Windows MSI refuses downgrades, and the updater refuses non-newer manifests. To move a machine backward, remove the app and install the exact older package from its versioned path.

Version numbering#

Versions are 0.<minor>.<patch>; the current line is 0.2.x, and the newest published version is whatever the stable release manifest reports (updates.swarmfile.com/stable/latest.json - test-updates.swarmfile.com for the staging channel). The version is embedded in the installer name and in every versioned URL, and release publishing is monotonic - an older version can never overwrite the current latest manifest. The engine, CLI tools, and Desktop App in one install always share the same version.

Reinstalling or repairing#

When an install is unhealthy - a broken mount helper, a missing CLI tool, a half-applied update - reinstall rather than removing things by hand:

• Desktop App: Diagnostics → Reinstall… (Windows and macOS).
• Command line, headless, or scripted: swarmfile-doctor --repair --yes. It derives the update host from the installed app (or SWARMFILE_UPDATER_ENDPOINT), downloads the full installer for the platform, and runs it (.pkg, msiexec, or dpkg -i), so it needs the same privileges a normal install does (sudo/SYSTEM).

On Windows, an update also refuses to run when the install directory is writable by non-administrators - the elevated helper stages and swaps files there, so a location any user can write is not a safe update target. If you hit that, reinstall to a protected location such as Program Files.

A repair keeps your local state: cached content, the queued-upload database, config, and sign-in token all live outside the application bundle (see Uninstall & Clean Reinstall for the exact paths). It is the supported way to move a .dmg-only macOS install onto the .pkg layout that installs the engine service and puts the CLI on PATH.

If the update manifest cannot be read, --repair reinstalls the currently installed version rather than guessing - so a repair never accidentally upgrades or downgrades a machine.

Where to go next#

• Supported Platforms & System Requirements - what each installer contains.
• Network Requirements - the hosts above in firewall-allowlist form.
• Deploying to Your Team - fleet rollout, silent install, and repair at scale.